diff --git a/doc/source/admin/ovn/baremetal.rst b/doc/source/admin/ovn/baremetal.rst new file mode 100644 index 00000000000..81688be0704 --- /dev/null +++ b/doc/source/admin/ovn/baremetal.rst @@ -0,0 +1,66 @@ +.. _ovn_baremetal: + +==================================== +Baremetal provisioning guide for OVN +==================================== + +The purpose of this page is to describe how the baremetal provisioning +can be configured with ML2/OVN. + +Currently, baremetal provisioning with ML2/OVN can be achieved using +the OVN's built-in DHCP server for IPv4 or using Neutron's DHCP agent +for either IPv4 or IPv6. + +How to configure it +------------------- + +Scheduling baremetal ports +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first thing to know is that when a port with VNIC ``baremetal`` is +created, ML2/OVN will create an OVN port of the type ``external``. These +ports will be bound to nodes that have external connectivity and are +responsible to responding to the ARP requests on behalf of the baremetal +node. + +For more information about external ports, its scheduling and +troubleshoot please check the :ref:`External Ports guide +`. + +Metadata access +~~~~~~~~~~~~~~~ + +Different from ML2/OVS, ML2/OVN requires to have the +``ovn-metadata-agent`` running on the node that the virtual machines +are running onto. Since baremetal requires an external port that will +be bound to another node, as explained `Scheduling baremetal ports`_ +section, it is required that the ``ovn-metadata-agent`` is also deployed +on the nodes marked with the ``enable-chassis-as-gw`` option so it can +serve metadata to the baremetal nodes booting off those external ports. + +Using OVN built-in DHCP for PXE booting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Currently, only IPv4 is supported for PXE booting a baremetal node using +the OVN's built-in DHCP server. It's also required to have OVN running +the version **22.06** or above. + +The version of OVN used for baremetal provisioning should include the +following commits [[#]_] [[#]_]. + +And last, make sure that configuration option +``[ovn]/disable_ovn_dhcp_for_baremetal_ports`` is set to **False** +(the default). + +Using Neutron DHCP Agent for PXE booting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If using the OVN built-in DHCP server is not desirable or if +PXE booting nodes off IPv6 is required, the operator will need +to deploy Neutron's DHCP agents on the controller nodes and also +disable the OVN's DHCP server for the baremetal ports by setting the +``[ovn]/disable_ovn_dhcp_for_baremetal_ports`` configuration option to +**True** (defaults to False). + +.. [#] https://github.com/ovn-org/ovn/commit/0057cde2a64749bd2dbbaff525f7a1edccbd9c8a +.. [#] https://github.com/ovn-org/ovn/commit/9cbd79c9ebbd0b6d0ea08c2cc70e234e56bb0415 diff --git a/doc/source/admin/ovn/external_ports.rst b/doc/source/admin/ovn/external_ports.rst new file mode 100644 index 00000000000..09571d16eb9 --- /dev/null +++ b/doc/source/admin/ovn/external_ports.rst @@ -0,0 +1,136 @@ +.. _ovn_external_ports: + +================== +OVN External Ports +================== + +The purpose of this page is to describe how +ML2/OVN leverages the use of OVN's `external ports +`_ +feature. + +What is it +~~~~~~~~~~ + +The external ports feature in OVN allows for setting up a port that lives +externally to the instance and is reponsible for replying to ARP requests +(DHCP, internal DNS, IPv6 router solicitation requests, etc...) on its +behalf. At the moment this feature is used in two use cases for ML2/OVN: + +1. :ref:`SR-IOV` +2. :ref:`Baremetal provisioning` + +ML2/OVN will create a port of the type ``external`` for ports with the +following VNICs: + +* direct +* direct-physical +* macvtap +* baremetal + +Also, ports of the type ``external`` will be scheduled on the gateway +nodes (controller or networker nodes) in HA mode by the OVN Neutron +driver. Check the `OVN Database information`_ section for more +information. + +OVN Database information +~~~~~~~~~~~~~~~~~~~~~~~~ + +the ML2/OVN driver identifies a gateway node by the +``ovn-cms-options=enable-chassis-as-gw`` and ``ovn-bridge-mappings`` +options in the external_ids column from the ``Chassis`` table in the +OVN Southbound database: + +.. code-block:: bash + + $ ovn-sbctl list Chassis + _uuid : 12b13aff-a821-4cde-a4ac-d9cf8e2c91bc + external_ids : {ovn-cms-options=enable-chassis-as-gw, ovn-bridge-mappings="public:br-ex", ...} + hostname : controller-0 + name : "1a462946-ccfd-46a6-8abf-9dca9eb558fb" + ... + +.. end + +For more information about both of these options, please +take a look at the `ovn-controller documentation +`_. + +These options can be set by running the following command locally on each +gateway node (note, the ``ovn-bridge-mappings`` will need to be adapted +to your environment): + +.. code-block:: bash + + $ ovs-vsctl set Open_vSwitch . external-ids:ovn-cms-options=\"enable-chassis-as-gw\" external-ids:ovn-bridge-mappings=\"public:br-ex\" + +.. end + +As mentioned in the `What is it`_ section, every time a Neutron port +with a certain VNIC is created the OVN driver will create a port of the +type ``external`` in the OVN Northbound database. These ports can be +found by issuing the following command: + +.. code-block:: bash + + $ ovn-nbctl find Logical_Switch_Port type=external + _uuid : 105e83ae-252d-401b-a1a7-8d28ec28a359 + ha_chassis_group : [43047e7b-4c78-4984-9788-6263fcc69885] + type : external + ... + +.. end + +The ``ha_chassis_group`` column indicates which HA Chassis Group that +port belongs to, to find that group do: + +.. code-block:: bash + + # The UUID is the one from the ha_chassis_group column from + # the Logical_Switch_Port table + $ ovn-nbctl list HA_Chassis_Group 43047e7b-4c78-4984-9788-6263fcc69885 + _uuid : 43047e7b-4c78-4984-9788-6263fcc69885 + external_ids : {} + ha_chassis : [3005bf84-fc95-4361-866d-bfa1c980adc8, 72c7671e-dd48-4100-9741-c47221672961] + name : neutron-4b2944ca-c7a3-4cf6-a9c8-6aa541a20535 + +.. end + +.. note:: + The external ports will be placed on a HA Chassis Group for the + network that the port belongs to. Those HA Chassis Groups are named as + ``neutron-``, as seeing in the output above. You + can also use this "name" with the ``ovn-nbctl list`` command when + searching for a specific HA Chassis Group. + +The chassis that are members of the HA Chassis Group are listed in +the ``ha_chassis`` column. Those are the gateway nodes (controller +or networker nodes) in the deployment and it's where the ``external`` +ports will be scheduled. In order to find which gateway node the external +ports are scheduled on use the following command: + +.. code-block:: bash + + # The UUIDs are the UUID members of the HA Chassis Group + # (ha_chassis column from the HA_Chassis_Group table) + $ ovn-nbctl list HA_Chassis 3005bf84-fc95-4361-866d-bfa1c980adc8 72c7671e-dd48-4100-9741-c47221672961 + _uuid : 3005bf84-fc95-4361-866d-bfa1c980adc8 + chassis_name : "1a462946-ccfd-46a6-8abf-9dca9eb558fb" + external_ids : {} + priority : 32767 + + _uuid : 72c7671e-dd48-4100-9741-c47221672961 + chassis_name : "a0cb9d55-a6da-4f84-857f-d4b674088c8c" + external_ids : {} + priority : 32766 + +.. end + +Note the ``priority`` column from the previous command, the chassis with +the highest ``priority`` from that list is the chassis that will have +the external ports scheduled on it. In our example above, the chassis +with the UUID ``1a462946-ccfd-46a6-8abf-9dca9eb558fb`` is the one. + +Whenever the chassis with the highest priority goes down, the ports will +be automatically scheduled on the next chassis with the highest priority +which is alive. So, the external ports are HA out of the box. diff --git a/doc/source/admin/ovn/index.rst b/doc/source/admin/ovn/index.rst index d189bc99960..65cfdd16a24 100644 --- a/doc/source/admin/ovn/index.rst +++ b/doc/source/admin/ovn/index.rst @@ -17,3 +17,5 @@ OVN Driver Administration Guide availability_zones routed_provider_networks smartnic_dpu + baremetal + external_ports diff --git a/doc/source/admin/ovn/sriov.rst b/doc/source/admin/ovn/sriov.rst index 89dac9c9ba3..bc98a6f8344 100644 --- a/doc/source/admin/ovn/sriov.rst +++ b/doc/source/admin/ovn/sriov.rst @@ -11,28 +11,9 @@ basic guide for SR-IOV`. External ports ~~~~~~~~~~~~~~ -In order for SR-IOV to work with the -Neutron driver we are leveraging the `external ports -`_ -feature from the OVN project. When virtual machines are booted -on hypervisors supporting SR-IOV nics, the local ovn-controllers are -unable to reply to the VM's DHCP, internal DNS, IPv6 router solicitation -requests, etc... since the hypervisor is bypassed in the SR-IOV case. OVN -then introduced the idea of having ``external`` ports which are able to -reply on behalf of those VM ports external to the hypervisor that they -are running on. - -The OVN Neutron driver will create a port of the type ``external`` -for ports with the following VNICs set: - -* direct -* direct-physical -* macvtap - -Also, ports of the type ``external`` will be scheduled on the gateway -nodes (controller or networker nodes) in HA mode by the OVN Neutron -driver. Check the `OVN Database information`_ section for more -information. +The SR-IOV feature is leverage by OVN ``external`` ports. For more +information about external ports, its scheduling and troubleshoot, +please check the :ref:`External Ports guide `. Environment setup for OVN SR-IOV ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -52,109 +33,6 @@ The only differences required for an OVN deployment are: or networker nodes) -OVN Database information -~~~~~~~~~~~~~~~~~~~~~~~~ - -Before getting into the ports information, the previous sections -talks about **gateway nodes**, the OVN Neutron driver identifies -a gateway node by the ``ovn-cms-options=enable-chassis-as-gw`` and -``ovn-bridge-mappings`` options in the external_ids column from the -``Chassis`` table in the OVN Southbound database: - -.. code-block:: bash - - $ ovn-sbctl list Chassis - _uuid : 12b13aff-a821-4cde-a4ac-d9cf8e2c91bc - external_ids : {ovn-cms-options=enable-chassis-as-gw, ovn-bridge-mappings="public:br-ex", ...} - hostname : controller-0 - name : "1a462946-ccfd-46a6-8abf-9dca9eb558fb" - ... - -.. end - -For more information about both of these options, please -take a look at the `ovn-controller documentation -`_. - -These options can be set by running the following command locally on each -gateway node (note, the ``ovn-bridge-mappings`` will need to be adapted -to your environment): - -.. code-block:: bash - - $ ovs-vsctl set Open_vSwitch . external-ids:ovn-cms-options=\"enable-chassis-as-gw\" external-ids:ovn-bridge-mappings=\"public:br-ex\" - -.. end - -As mentioned in the `External ports`_ section, every time a Neutron port -with a certain VNIC is created the OVN driver will create a port of the -type ``external`` in the OVN Northbound database. These ports can be -found by issuing the following command: - -.. code-block:: bash - - $ ovn-nbctl find Logical_Switch_Port type=external - _uuid : 105e83ae-252d-401b-a1a7-8d28ec28a359 - ha_chassis_group : [43047e7b-4c78-4984-9788-6263fcc69885] - type : external - ... - -.. end - -The ``ha_chassis_group`` column indicates which HA Chassis Group that -port belongs to, to find that group do: - -.. code-block:: bash - - # The UUID is the one from the ha_chassis_group column from - # the Logical_Switch_Port table - $ ovn-nbctl list HA_Chassis_Group 43047e7b-4c78-4984-9788-6263fcc69885 - _uuid : 43047e7b-4c78-4984-9788-6263fcc69885 - external_ids : {} - ha_chassis : [3005bf84-fc95-4361-866d-bfa1c980adc8, 72c7671e-dd48-4100-9741-c47221672961] - name : neutron-4b2944ca-c7a3-4cf6-a9c8-6aa541a20535 - -.. end - -.. note:: - The external ports will be placed on a HA Chassis Group for the - network that the port belongs to. Those HA Chassis Groups are named as - ``neutron-``, as seeing in the output above. You - can also use this "name" with the ``ovn-nbctl list`` command when - searching for a specific HA Chassis Group. - -The chassis that are members of the HA Chassis Group are listed in -the ``ha_chassis`` column. Those are the gateway nodes (controller -or networker nodes) in the deployment and it's where the ``external`` -ports will be scheduled. In order to find which gateway node the external -ports are scheduled on use the following command: - -.. code-block:: bash - - # The UUIDs are the UUID members of the HA Chassis Group - # (ha_chassis column from the HA_Chassis_Group table) - $ ovn-nbctl list HA_Chassis 3005bf84-fc95-4361-866d-bfa1c980adc8 72c7671e-dd48-4100-9741-c47221672961 - _uuid : 3005bf84-fc95-4361-866d-bfa1c980adc8 - chassis_name : "1a462946-ccfd-46a6-8abf-9dca9eb558fb" - external_ids : {} - priority : 32767 - - _uuid : 72c7671e-dd48-4100-9741-c47221672961 - chassis_name : "a0cb9d55-a6da-4f84-857f-d4b674088c8c" - external_ids : {} - priority : 32766 - -.. end - -Note the ``priority`` column from the previous command, the chassis with -the highest ``priority`` from that list is the chassis that will have -the external ports scheduled on it. In our example above, the chassis -with the UUID ``1a462946-ccfd-46a6-8abf-9dca9eb558fb`` is the one. - -Whenever the chassis with the highest priority goes down, the ports will -be automatically scheduled on the next chassis with the highest priority -which is alive. So, the external ports are HA out of the box. - Known limitations ~~~~~~~~~~~~~~~~~