From 2567fb84e9a7a10fc3d3243d0fa224f228afa790 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 18 Oct 2016 21:03:32 +0100 Subject: [PATCH] doc: Convert IntegrationGuide to rST Signed-off-by: Stephen Finucane Signed-off-by: Russell Bryant --- IntegrationGuide.md | 169 ------------------------------- IntegrationGuide.rst | 195 ++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- ovn/CONTAINERS.OpenStack.md | 4 +- ovn/ovn-architecture.7.xml | 6 +- ovn/ovn-sb.xml | 2 +- 6 files changed, 202 insertions(+), 176 deletions(-) delete mode 100644 IntegrationGuide.md create mode 100644 IntegrationGuide.rst diff --git a/IntegrationGuide.md b/IntegrationGuide.md deleted file mode 100644 index 5d3e574b603..00000000000 --- a/IntegrationGuide.md +++ /dev/null @@ -1,169 +0,0 @@ -Integration Guide for Centralized Control -========================================= - -This document describes how to integrate Open vSwitch onto a new -platform to expose the state of the switch and attached devices for -centralized control. (If you are looking to port the switching -components of Open vSwitch to a new platform, please see the PORTING -document.) The focus of this guide is on hypervisors, but many of the -interfaces are useful for hardware switches, as well. The XenServer -integration is the most mature implementation, so most of the examples -are drawn from it. - -The externally visible interface to this integration is -platform-agnostic. We encourage anyone who integrates Open vSwitch to -use the same interface, because keeping a uniform interface means that -controllers require less customization for individual platforms (and -perhaps no customization at all). - -Integration centers around the Open vSwitch database and mostly involves -the 'external_ids' columns in several of the tables. These columns are -not interpreted by Open vSwitch itself. Instead, they provide -information to a controller that permits it to associate a database -record with a more meaningful entity. In contrast, the 'other_config' -column is used to configure behavior of the switch. The main job of the -integrator, then, is to ensure that these values are correctly populated -and maintained. - -An integrator sets the columns in the database by talking to the -ovsdb-server daemon. A few of the columns can be set during startup by -calling the ovs-ctl tool from inside the startup scripts. The -'xenserver/etc_init.d_openvswitch' script provides examples of its use, -and the ovs-ctl(8) manpage contains complete documentation. At runtime, -ovs-vsctl can be be used to set columns in the database. The script -'xenserver/etc_xensource_scripts_vif' contains examples of its use, and -ovs-vsctl(8) manpage contains complete documentation. - -Python and C bindings to the database are provided if deeper integration -with a program are needed. The XenServer ovs-xapi-sync daemon -('xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync') provides an -example of using the Python bindings. More information on the python -bindings is available at 'python/ovs/db/idl.py'. Information on the C -bindings is available at 'lib/ovsdb-idl.h'. - -The following diagram shows how integration scripts fit into the Open vSwitch -architecture: - - +----------------------------------------+ - | Controller Cluster + - +----------------------------------------+ - | - | - +----------------------------------------------------------+ - | | | - | +--------------+---------------+ | - | | | | - | +-------------------+ +------------------+ | - | | ovsdb-server |-----------| ovs-vswitchd | | - | +-------------------+ +------------------+ | - | | | | - | +---------------------+ | | - | | Integration scripts | | | - | | (ex: ovs-xapi-sync) | | | - | +---------------------+ | | - | | Userspace | - |----------------------------------------------------------| - | | Kernel | - | | | - | +---------------------+ | - | | OVS Kernel Module | | - | +---------------------+ | - +----------------------------------------------------------+ - - -A description of the most relevant fields for integration follows. By -setting these values, controllers are able to understand the network and -manage it more dynamically and precisely. For more details about the -database and each individual column, please refer to the -ovs-vswitchd.conf.db(5) manpage. - - -Open_vSwitch table ------------------- -The Open_vSwitch table describes the switch as a whole. The -'system_type' and 'system_version' columns identify the platform to the -controller. The 'external_ids:system-id' key uniquely identifies the -physical host. In XenServer, the system-id will likely be the same as -the UUID returned by 'xe host-list'. This key allows controllers to -distinguish between multiple hypervisors. - -Most of this configuration can be done with the ovs-ctl command at -startup. For example: - - ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \ - --system-id="${UUID}" "${other_options}" start - -Alternatively, the ovs-vsctl command may be used to set a particular -value at runtime. For example: - - ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"' - -The 'other_config:enable-statistics' key may be set to "true" to have OVS -populate the database with statistics (e.g., number of CPUs, memory, -system load) for the controller's use. - - -Bridge table ------------- -The Bridge table describes individual bridges within an Open vSwitch -instance. The 'external-ids:bridge-id' key uniquely identifies a -particular bridge. In XenServer, this will likely be the same as the -UUID returned by 'xe network-list' for that particular bridge. - -For example, to set the identifier for bridge "br0", the following -command can be used: - - ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"' - -The MAC address of the bridge may be manually configured by setting it -with the "other_config:hwaddr" key. For example: - - ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab" - - -Interface table ---------------- -The Interface table describes an interface under the control of Open -vSwitch. The 'external_ids' column contains keys that are used to -provide additional information about the interface: - - attached-mac - - This field contains the MAC address of the device attached to - the interface. On a hypervisor, this is the MAC address of the - interface as seen inside a VM. It does not necessarily - correlate to the host-side MAC address. For example, on - XenServer, the MAC address on a VIF in the hypervisor is always - FE:FF:FF:FF:FF:FF, but inside the VM a normal MAC address is - seen. - - iface-id - - This field uniquely identifies the interface. In hypervisors, - this allows the controller to follow VM network interfaces as - VMs migrate. A well-chosen identifier should also allow an - administrator or a controller to associate the interface with - the corresponding object in the VM management system. For - example, the Open vSwitch integration with XenServer by default - uses the XenServer assigned UUID for a VIF record as the - iface-id. - - iface-status - - In a hypervisor, there are situations where there are multiple - interface choices for a single virtual ethernet interface inside - a VM. Valid values are "active" and "inactive". A complete - description is available in the ovs-vswitchd.conf.db(5) manpage. - - vm-id - - This field uniquely identifies the VM to which this interface - belongs. A single VM may have multiple interfaces attached to - it. - -As in the previous tables, the ovs-vsctl command may be used to -configure the values. For example, to set the 'iface-id' on eth0, the -following command can be used: - - ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"' - diff --git a/IntegrationGuide.rst b/IntegrationGuide.rst new file mode 100644 index 00000000000..4a591fae650 --- /dev/null +++ b/IntegrationGuide.rst @@ -0,0 +1,195 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +========================================= +Integration Guide for Centralized Control +========================================= + +This document describes how to integrate Open vSwitch onto a new platform to +expose the state of the switch and attached devices for centralized control. +(If you are looking to port the switching components of Open vSwitch to a new +platform, please see the PORTING document.) The focus of this guide is on +hypervisors, but many of the interfaces are useful for hardware switches, as +well. The XenServer integration is the most mature implementation, so most of +the examples are drawn from it. + +The externally visible interface to this integration is platform-agnostic. We +encourage anyone who integrates Open vSwitch to use the same interface, because +keeping a uniform interface means that controllers require less customization +for individual platforms (and perhaps no customization at all). + +Integration centers around the Open vSwitch database and mostly involves the +``external_ids`` columns in several of the tables. These columns are not +interpreted by Open vSwitch itself. Instead, they provide information to a +controller that permits it to associate a database record with a more +meaningful entity. In contrast, the ``other_config`` column is used to +configure behavior of the switch. The main job of the integrator, then, is to +ensure that these values are correctly populated and maintained. + +An integrator sets the columns in the database by talking to the ovsdb-server +daemon. A few of the columns can be set during startup by calling the ovs-ctl +tool from inside the startup scripts. The ``xenserver/etc_init.d_openvswitch`` +script provides examples of its use, and the ovs-ctl(8) manpage contains +complete documentation. At runtime, ovs-vsctl can be be used to set columns in +the database. The script ``xenserver/etc_xensource_scripts_vif`` contains +examples of its use, and ovs-vsctl(8) manpage contains complete documentation. + +Python and C bindings to the database are provided if deeper integration with a +program are needed. The XenServer ovs-xapi-sync daemon +(``xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync``) provides an example +of using the Python bindings. More information on the python bindings is +available at ``python/ovs/db/idl.py``. Information on the C bindings is +available at ``lib/ovsdb-idl.h``. + +The following diagram shows how integration scripts fit into the Open vSwitch +architecture: + +:: + + Diagram + + +----------------------------------------+ + | Controller Cluster + + +----------------------------------------+ + | + | + +----------------------------------------------------------+ + | | | + | +--------------+---------------+ | + | | | | + | +-------------------+ +------------------+ | + | | ovsdb-server |-----------| ovs-vswitchd | | + | +-------------------+ +------------------+ | + | | | | + | +---------------------+ | | + | | Integration scripts | | | + | | (ex: ovs-xapi-sync) | | | + | +---------------------+ | | + | | Userspace | + |----------------------------------------------------------| + | | Kernel | + | | | + | +---------------------+ | + | | OVS Kernel Module | | + | +---------------------+ | + +----------------------------------------------------------+ + +A description of the most relevant fields for integration follows. By setting +these values, controllers are able to understand the network and manage it more +dynamically and precisely. For more details about the database and each +individual column, please refer to the ovs-vswitchd.conf.db(5) manpage. + +``Open_vSwitch`` table +---------------------- + +The ``Open_vSwitch`` table describes the switch as a whole. The +``system_type`` and ``system_version`` columns identify the platform to the +controller. The ``external_ids:system-id`` key uniquely identifies the +physical host. In XenServer, the system-id will likely be the same as the UUID +returned by ``xe host-list``. This key allows controllers to distinguish +between multiple hypervisors. + +Most of this configuration can be done with the ovs-ctl command at startup. +For example: + +:: + + $ ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \ + --system-id="${UUID}" "${other_options}" start + +Alternatively, the ovs-vsctl command may be used to set a particular value at +runtime. For example: + +:: + + $ ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"' + +The ``other_config:enable-statistics`` key may be set to ``true`` to have OVS +populate the database with statistics (e.g., number of CPUs, memory, system +load) for the controller's use. + +Bridge table +------------ + +The Bridge table describes individual bridges within an Open vSwitch instance. +The ``external-ids:bridge-id`` key uniquely identifies a particular bridge. In +XenServer, this will likely be the same as the UUID returned by ``xe +network-list`` for that particular bridge. + +For example, to set the identifier for bridge "br0", the following command can +be used: + +:: + + $ ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"' + +The MAC address of the bridge may be manually configured by setting it with the +``other_config:hwaddr`` key. For example: + +:: + + $ ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab" + +Interface table +--------------- + +The Interface table describes an interface under the control of Open vSwitch. +The ``external_ids`` column contains keys that are used to provide additional +information about the interface: + +attached-mac + + This field contains the MAC address of the device attached to the interface. + On a hypervisor, this is the MAC address of the interface as seen inside a + VM. It does not necessarily correlate to the host-side MAC address. For + example, on XenServer, the MAC address on a VIF in the hypervisor is always + FE:FF:FF:FF:FF:FF, but inside the VM a normal MAC address is seen. + +iface-id + + This field uniquely identifies the interface. In hypervisors, this allows + the controller to follow VM network interfaces as VMs migrate. A well-chosen + identifier should also allow an administrator or a controller to associate + the interface with the corresponding object in the VM management system. For + example, the Open vSwitch integration with XenServer by default uses the + XenServer assigned UUID for a VIF record as the iface-id. + +iface-status + + In a hypervisor, there are situations where there are multiple interface + choices for a single virtual ethernet interface inside a VM. Valid values + are "active" and "inactive". A complete description is available in the + ovs-vswitchd.conf.db(5) manpage. + +vm-id + + This field uniquely identifies the VM to which this interface belongs. A + single VM may have multiple interfaces attached to it. + +As in the previous tables, the ovs-vsctl command may be used to configure the +values. For example, to set the ``iface-id`` on eth0, the following command +can be used: + +:: + + $ ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"' diff --git a/Makefile.am b/Makefile.am index dee8d6e034d..f7bba1dd85e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -86,7 +86,7 @@ docs = \ INSTALL.XenServer.rst \ INSTALL.userspace.rst \ INSTALL.Windows.rst \ - IntegrationGuide.md \ + IntegrationGuide.rst \ MAINTAINERS.md \ OPENFLOW-1.1+.md \ PORTING.md \ diff --git a/ovn/CONTAINERS.OpenStack.md b/ovn/CONTAINERS.OpenStack.md index d640d7c488b..8f74e6fe353 100644 --- a/ovn/CONTAINERS.OpenStack.md +++ b/ovn/CONTAINERS.OpenStack.md @@ -22,7 +22,7 @@ interface (VIF) of VM-A. * When VM-A is created on a hypervisor, its VIF gets added to the Open vSwitch integration bridge. This creates a row in the Interface table -of the Open_vSwitch database. As explained in the [IntegrationGuide.md], +of the Open_vSwitch database. As explained in the [IntegrationGuide.rst], the vif-id associated with the VM network interface gets added in the external_ids:iface-id column of the newly created row in the Interface table. @@ -119,4 +119,4 @@ a MAC address and IP address for that interface. ovn-docker will then create a veth pair, insert one end inside the container as 'eth0' and the other end as a port of a local OVS bridge as an access port of the chosen VLAN. -[IntegrationGuide.md]:IntegrationGuide.md +[IntegrationGuide.rst]:IntegrationGuide.rst diff --git a/ovn/ovn-architecture.7.xml b/ovn/ovn-architecture.7.xml index de2a376d051..bc5dfb77188 100644 --- a/ovn/ovn-architecture.7.xml +++ b/ovn/ovn-architecture.7.xml @@ -42,7 +42,7 @@
  • One or more (usually many) hypervisors. Hypervisors must run Open vSwitch and implement the interface described in - IntegrationGuide.md in the OVS source tree. Any hypervisor + IntegrationGuide.rst in the OVS source tree. Any hypervisor platform supported by Open vSwitch is acceptable.
    • @@ -295,7 +295,7 @@
  • On a hypervisor, any VIFs that are to be attached to logical networks. The hypervisor itself, or the integration between Open vSwitch and the - hypervisor (described in IntegrationGuide.md) takes care of + hypervisor (described in IntegrationGuide.rst) takes care of this. (This is not part of OVN or new to OVN; this is pre-existing integration work that has already been done on hypervisors that support OVS.) @@ -445,7 +445,7 @@
  • Eventually, a user powers on the VM that owns the VIF. On the hypervisor where the VM is powered on, the integration between the hypervisor and - Open vSwitch (described in IntegrationGuide.md) adds the VIF + Open vSwitch (described in IntegrationGuide.rst) adds the VIF to the OVN integration bridge and stores vif-id in external_ids:iface-id to indicate that the interface is an instantiation of the new VIF. (None of this code is new diff --git a/ovn/ovn-sb.xml b/ovn/ovn-sb.xml index b484f59a07a..4e0047a8b59 100644 --- a/ovn/ovn-sb.xml +++ b/ovn/ovn-sb.xml @@ -1593,7 +1593,7 @@ tcp.flags = RST; which ovn-controller/ovn-controller-vtep in turn finds out by monitoring the local hypervisor's Open_vSwitch database, which identifies logical ports via the conventions described - in IntegrationGuide.md. (The exceptions are for + in IntegrationGuide.rst. (The exceptions are for Port_Binding records with type of l3gateway, whose locations are identified by ovn-northd via the options:l3gateway-chassis