This uses the column grouping feature and the ability to document an individual key within a column to better, in my opinion, organize the documentation for the Logical_Port table.
This will make it easier to document a new port type that a future commit will add. Signed-off-by: Ben Pfaff <[email protected]> --- ovn/ovn-nb.xml | 382 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 202 insertions(+), 180 deletions(-) diff --git a/ovn/ovn-nb.xml b/ovn/ovn-nb.xml index 78b146e..37556cf 100644 --- a/ovn/ovn-nb.xml +++ b/ovn/ovn-nb.xml @@ -86,207 +86,229 @@ A port within an L2 logical switch. </p> - <column name="name"> - <p> - The logical port name. - </p> + <group title="Core Features"> + <column name="name"> + <p> + The logical port name. + </p> - <p> - For entities (VMs or containers) that are spawned in the hypervisor, - the name used here must match those used in the <ref key="iface-id" - table="Interface" column="external_ids" db="Open_vSwitch"/> in the - <ref db="Open_vSwitch"/> database's <ref table="Interface" - db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id" - table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup - key to identify the network interface of that entity. - </p> + <p> + For entities (VMs or containers) that are spawned in the hypervisor, + the name used here must match those used in the <ref key="iface-id" + table="Interface" column="external_ids" db="Open_vSwitch"/> in the + <ref db="Open_vSwitch"/> database's <ref table="Interface" + db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id" + table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup + key to identify the network interface of that entity. + </p> - <p> - For containers that are spawned inside a VM, the name can be - any unique identifier. In such a case, <ref column="parent_name"/> - must be populated. - </p> - </column> + <p> + For containers that share a VIF within a VM, the name can be any + unique identifier. See <code>Containers</code>, below, for more + information. + </p> + </column> - <column name="type"> - <p> - Specify a type for this logical port. Logical ports can be used to model - other types of connectivity into an OVN logical switch. Leaving this - column blank maintains the default logical port behavior, which is - for a VM (or VIF) interface. The following other types are defined: - </p> + <column name="type"> + <p> + Specify a type for this logical port. Logical ports can be used to + model other types of connectivity into an OVN logical switch. The + following types are defined: + </p> - <dl> - <dt><code>localnet</code></dt> - <dd>A connection to a locally accessible network from each - <code>ovn-controller</code> instance. A logical switch can only - have a single <code>localnet</code> port attached and at most one - regular logical port. This is used to model direct connectivity - to an existing network.</dd> - </dl> - - <dl> - <dt><code>vtep</code></dt> - <dd>A port to a logical switch on a VTEP gateway. In order - to get this port correctly recognized by the OVN controller, the - <ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code> - and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code> - must also be defined.</dd> - </dl> - </column> + <dl> + <dt>(empty string)</dt> + <dd> + A VM (or VIF) interface. + </dd> + + <dt><code>localnet</code></dt> + <dd> + A connection to a locally accessible network from each + <code>ovn-controller</code> instance. A logical switch can only + have a single <code>localnet</code> port attached and at most one + regular logical port. This is used to model direct connectivity to + an existing network. + </dd> + + <dt><code>vtep</code></dt> + <dd> + A port to a logical switch on a VTEP gateway. + </dd> + </dl> + </column> + </group> - <column name="options"> - <p> + <group title="Options"> + <column name="options"> This column provides key/value settings specific to the logical port - <ref column="type"/>. The following options are defined: - </p> + <ref column="type"/>. The type-specific options are described + individually below. + </column> - <dl> - <dt><code>network_name</code></dt> - <dd> - Must be set when <ref column="type"/> is <code>localnet</code>. - <code>ovn-controller</code> uses local configuration to determine - exactly how to connect to this locally accessible network. - </dd> - </dl> - - <dl> - <dt><code>vtep-physical-switch</code></dt> - <dd> - The name of the VTEP gateway. Must be set when - <ref column="type"/> is <code>vtep</code>. - </dd> - </dl> - - <dl> - <dt><code>vtep-logical-switch</code></dt> - <dd> - A logical switch name connected by the VTEP gateway. Must be - set when <ref column="type"/> is <code>vtep</code>. - </dd> - </dl> - </column> + <group title="Options for localnet ports"> + <p> + These options apply when <ref column="type"/> is + <code>localnet</code>. + </p> - <column name="parent_name"> - When <ref column="name"/> identifies the interface of a container - spawned inside a tenant VM, this column represents the VM interface - through which the container interface sends its network traffic. - The name used here must match those used in the <ref key="iface-id" - table="Interface" column="external_ids" db="Open_vSwitch"/> in the - <ref db="Open_vSwitch"/> table, because hypervisors in this case use - <ref key="iface-id" table="Interface" column="external_ids" - db="Open_vSwitch"/> as a lookup key to identify the network interface - of the tenant VM. - </column> + <column name="options" key="network_name"> + Required. The name of the network to which the <code>localnet</code> + port is connected. Each hypervisor, via <code>ovn-controller</code>, + uses its local configuration to determine exactly how to connect to + this locally accessible network. + </column> + </group> - <column name="tag"> - <p> - When <ref column="type"/> is empty and <ref column="name"/> identifies - the interface of a container spawned inside a tenant VM, this column - identifies the VLAN tag in the network traffic associated with that - container's network interface. When there are multiple container - interfaces inside a VM, all of them send their network traffic through a - single VM network interface and this value helps OVN identify the correct - container interface. - </p> - - <p> - When <ref column="type"/> is set to <code>localnet</code>, this can be - set to indicate that the port represents a connection to a specific - VLAN on a locally accessible network. The VLAN ID is used to match - incoming traffic and is also added to outgoing traffic. - </p> - </column> + <group title="Options for vtep ports"> + <p> + These options apply when <ref column="type"/> is <code>vtep</code>. + </p> - <column name="up"> - This column is populated by <code>ovn-northd</code>, rather than by - the CMS plugin as is most of this database. When a logical port is bound - to a physical location in the OVN Southbound database <ref - db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code> - sets this column to <code>true</code>; otherwise, or if the port - becomes unbound later, it sets it to <code>false</code>. This - allows the CMS to wait for a VM's (or container's) networking to - become active before it allows the VM (or container) to start. - </column> + <column name="options" key="vtep-physical-switch"> + Required. The name of the VTEP gateway. + </column> - <column name="enabled"> - This column is used to administratively set port state. If this column is - empty or is set to <code>true</code>, the port is enabled. If this column - is set to <code>false</code>, the port is disabled. A disabled port has all - ingress and egress traffic dropped. - </column> + <column name="options" key="vtep-logical-switch"> + Required. A logical switch name connected by the VTEP gateway. + </column> + </group> + </group> - <column name="addresses"> + <group title="Containers"> <p> - Addresses owned by the logical port. + When a large number of containers are nested within a VM, it may be too + expensive to dedicate a VIF to each container. OVN can use VLAN tags + to support such cases. Each container is assigned a VLAN ID and each + packet that passes between the hypervisor and the VM is tagged with the + appropriate ID for the container. Such VLAN IDs never appear on a + physical wire, even inside a tunnel, so they need not be unique except + relative to a single VM on a hypervisor. </p> <p> - Each element in the set must take one of the following forms: + These columns are used for VIFs that represent nested containers using + shared VIFs. For VMs and for containers that have dedicated VIFs, they + are empty. </p> - <dl> - <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt> - <dd> - <p> - An Ethernet address owned by the logical port. Like a physical - Ethernet NIC, a logical port ordinarily has a single fixed Ethernet - address. - </p> - - <p> - When a OVN logical switch processes a unicast Ethernet frame whose - destination MAC address is in a logical port's <ref - column="addresses"/> column, it delivers it only to that port, as - if a MAC learning process had learned that MAC address on the port. - </p> - </dd> - - <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt> - <dd> - <p> - This form has all the effects of the previous form. It also - indicates that the logical port owns the given IPv4 address. - </p> - - <p> - The OVN logical switch uses this information to synthesize - responses to ARP requests without traversing the physical network. - The OVN logical router connected to the logical switch, if any, - uses this information to avoid issuing ARP requests for logical - switch ports. - </p> - </dd> - - <dt><code>unknown</code></dt> - <dd> - This indicates that the logical port has an unknown set of Ethernet - addresses. When an OVN logical switch processes a unicast Ethernet - frame whose destination MAC address is not in any logical port's <ref - column="addresses"/> column, it delivers it to the port (or ports) - whose <ref column="addresses"/> columns include <code>unknown</code>. - </dd> - </dl> - </column> + <column name="parent_name"> + The VM interface through which the nested container sends its network + traffic. This must match the <ref column="name"/> column for some + other <ref table="Logical_Port"/>. + </column> - <column name="port_security"> - <p> - A set of L2 (Ethernet) addresses - from which the logical port is allowed to send packets and to which it - is allowed to receive packets. If this column is empty, all addresses - are permitted. Logical ports are always allowed to receive packets - addressed to multicast and broadcast addresses. - </p> + <column name="tag"> + <p> + The VLAN tag in the network traffic associated with a container's + network interface. + </p> - <p> - Each member of the set is an Ethernet address in the form - <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>. - </p> + <p> + When <ref column="type"/> is set to <code>localnet</code>, this can + be set to indicate that the port represents a connection to a + specific VLAN on a locally accessible network. The VLAN ID is used to + match incoming traffic and is also added to outgoing traffic. + </p> + </column> + </group> - <p> - This specification will be extended to support L3 port security. - </p> - </column> + <group title="Port State"> + <column name="up"> + This column is populated by <code>ovn-northd</code>, rather than by the + CMS plugin as is most of this database. When a logical port is bound + to a physical location in the OVN Southbound database <ref + db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code> + sets this column to <code>true</code>; otherwise, or if the port + becomes unbound later, it sets it to <code>false</code>. This allows + the CMS to wait for a VM's (or container's) networking to become active + before it allows the VM (or container) to start. + </column> + + <column name="enabled"> + This column is used to administratively set port state. If this column + is empty or is set to <code>true</code>, the port is enabled. If this + column is set to <code>false</code>, the port is disabled. A disabled + port has all ingress and egress traffic dropped. + </column> + + </group> + + <group title="Addressing"> + <column name="addresses"> + <p> + Addresses owned by the logical port. + </p> + + <p> + Each element in the set must take one of the following forms: + </p> + + <dl> + <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt> + <dd> + <p> + An Ethernet address owned by the logical port. Like a physical + Ethernet NIC, a logical port ordinarily has a single fixed + Ethernet address. + </p> + + <p> + When a OVN logical switch processes a unicast Ethernet frame + whose destination MAC address is in a logical port's <ref + column="addresses"/> column, it delivers it only to that port, as + if a MAC learning process had learned that MAC address on the + port. + </p> + </dd> + + <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt> + <dd> + <p> + This form has all the effects of the previous form. It also + indicates that the logical port owns the given IPv4 address. + </p> + + <p> + The OVN logical switch uses this information to synthesize + responses to ARP requests without traversing the physical + network. The OVN logical router connected to the logical switch, + if any, uses this information to avoid issuing ARP requests for + logical switch ports. + </p> + </dd> + + <dt><code>unknown</code></dt> + <dd> + This indicates that the logical port has an unknown set of Ethernet + addresses. When an OVN logical switch processes a unicast Ethernet + frame whose destination MAC address is not in any logical port's + <ref column="addresses"/> column, it delivers it to the port (or + ports) whose <ref column="addresses"/> columns include + <code>unknown</code>. + </dd> + </dl> + </column> + + <column name="port_security"> + <p> + A set of L2 (Ethernet) addresses from which the logical port is + allowed to send packets and to which it is allowed to receive + packets. If this column is empty, all addresses are permitted. + Logical ports are always allowed to receive packets addressed to + multicast and broadcast addresses. + </p> + + <p> + Each member of the set is an Ethernet address in the form + <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>. + </p> + + <p> + This specification will be extended to support L3 port security. + </p> + </column> + </group> <group title="Common Columns"> <column name="external_ids"> -- 2.1.3 _______________________________________________ dev mailing list [email protected] http://openvswitch.org/mailman/listinfo/dev
