diff --git a/doc/source/contributor/internals/index.rst b/doc/source/contributor/internals/index.rst index 212e156d5d1..52776d6ae6a 100644 --- a/doc/source/contributor/internals/index.rst +++ b/doc/source/contributor/internals/index.rst @@ -47,6 +47,7 @@ Neutron Internals layer3 linuxbridge_agent live_migration + local_ips ml2_ext_manager network_ip_availability objects_usage diff --git a/doc/source/contributor/internals/local_ips.rst b/doc/source/contributor/internals/local_ips.rst new file mode 100644 index 00000000000..399b54314c8 --- /dev/null +++ b/doc/source/contributor/internals/local_ips.rst @@ -0,0 +1,146 @@ +.. + 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 Neutron devref: + ======= 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.) + + +Local IP +======== + +Local IP is a virtual IP that can be shared across multiple ports/VMs +(similar to anycast IP) and is guaranteed to only be reachable within the same +physical server/node boundaries. The feature is primarily focused on high +efficiency and performance of the networking data plane for very large scale +clouds and/or clouds with high network throughput demands. +Technically it is Neutron API/DB extension + openvswitch agent extension. + +Usage +----- + +Usage is similar to Floating IP usage. If you want to assign a virtual Local IP +to one of your VMs: + +- first create Local IP object using network_id or local_port_id input + parameter: it will be used to allocate/take IP address + + .. code-block:: console + + $ openstack local ip create --network_id + +------------------+--------------------------------------+ + | Field | Value | + +------------------+--------------------------------------+ + | created_at | 2021-12-01T13:50:24Z | + | description | | + | id | b4425e9d-f1d0-4493-a2a8-1d3c7fbe049b | + | ip_mode | translate | + | local_ip_address | 172.24.4.10 | + | local_port_id | 13181907-f258-4381-9516-ca07648ea239 | + | name | | + | network_id | be0ec407-e341-4efa-a33a-3e0160afeedc | + | project_id | b8462a1eba47462ea8c3e4e6adc22e63 | + | revision_number | 0 | + | updated_at | 2021-12-01T13:50:24Z | + +------------------+--------------------------------------+ + +- then create Local IP association object using local_ip_id and fixed_port_id + input parameters, thus assigning Local IP to the needed VM + + .. code-block:: console + + $ openstack local ip association create + +------------------+--------------------------------------+ + | Field | Value | + +------------------+--------------------------------------+ + | fixed_ip | 10.0.0.194 | + | fixed_port_id | 8cd37bb6-f7c3-4013-8d97-5c97676678a0 | + | host | | + | id | None | + | local_ip_address | 172.24.4.10 | + | name | None | + +------------------+--------------------------------------+ + +- Unlike Floating IP you can have many Local IP associations: to VMs on + different nodes. + + .. warning:: + Assigning two or more fixed ports to the same Local IP on the same node + is currently not supported. NAT could go either way or not work at all. + +All node's VMs` egress traffic targeting IP address of Local IP object will be +DNATed to local VM. + +Note: if no Local IP is assigned on a node packets will be redirected to an +underlying Neutron port IP address. + +Note: in Yoga release only ``translate`` ip_mode is supported (default) - +it means DNAT will be used for packet redirection. Support for ``passthrough`` +mode (no modifications to IP packets) will be added in next releases. + +OpenVSwitch Agent Impact +------------------------ + +Unconditional changes +~~~~~~~~~~~~~~~~~~~~~ + +- 2 new OF tables are added for br-int: + + - LOCAL_EGRESS_TABLE - to save VLANs of local ports + - LOCAL_IP_TABLE - for Local IP handling rules + +- both tables has default rule to resubmit packets to TRANSIENT_TABLE; +- the only modification to packets flow is that egress packets will first + go through empty LOCAL_EGRESS_TABLE before entering TRANSIENT_TABLE. + This should be optimized by OVS to have no impact on performance. + +If local_ip agent extension is enabled +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- LOCAL_EGRESS_TABLE will have a rule to save port's local VLAN to req6. + This is needed in order to distinguish Local IPs from different nets. + Then packets will be resubmitted to LOCAL_IP_TABLE which just has one + default rule unless some local Port is associated with any Local IP. + +If user creates Local IP Association with one of the ports owned by agent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Following rules will be added to LOCAL_SWITCHING table: + +- local gARP blocker rule to prevent undesired Local IP ARP updates + from other nodes (including real IP address owner) + +Following rules will be added to LOCAL_IP_TABLE: + +- local arp responder rule to answer local ARP requests for Local IP address +- Local IP translation flows to do actual DNAT (Local IP -> fixed IP) + + - via conntrack using ``ct`` with ``nat`` action if ``static_nat`` config + option is `False` (default) + - via static NAT rules with source/destination (ETH + IP + TCP/UDP ports) + tuples used for learning back flows - if ``static_nat`` config is `True` + +Yoga release limitations +------------------------ + +- Only IPv4 is supported. IPv6 support will be considered in future releases + +- Only 'openvswitch' ML2 mechanism driver/agent supports the feature + +- No deterministic handling of packets if a node contains multiple local ports + from same L2 segment associated with the same Local IP diff --git a/doc/source/contributor/internals/openvswitch_agent.rst b/doc/source/contributor/internals/openvswitch_agent.rst index da8a1e4f7ef..5fb35684156 100644 --- a/doc/source/contributor/internals/openvswitch_agent.rst +++ b/doc/source/contributor/internals/openvswitch_agent.rst @@ -607,6 +607,14 @@ still valid. It will delete the stale trunk and subports using the procedure spe in the previous paragraphs according to the implementation. +Local IP +-------- + +Local IP is a new feature added in Yoga release. For details on openvswitch +agent impact please see: +:doc:`Local IPs `. + + Further Reading --------------- diff --git a/releasenotes/notes/local_ip-de07013ea3e49c67.yaml b/releasenotes/notes/local_ip-de07013ea3e49c67.yaml new file mode 100644 index 00000000000..000d8c9f184 --- /dev/null +++ b/releasenotes/notes/local_ip-de07013ea3e49c67.yaml @@ -0,0 +1,12 @@ +--- +features: + - | + Local IP - a virtual IP that can be shared across multiple ports/VMs + (similar to anycast IP) and is guaranteed to only be reachable within + the same physical server/node boundaries. The feature is primarily focused + on high efficiency and performance of the networking data plane for very + large scale clouds and/or clouds with high network throughput demands. +other: + - | + New service plugin and openvswitch agent extension could be configured + in order to enable Local IP feature: ``local_ip``