Local IP internal documentation and release note

Closes-Bug: #1930200
Change-Id: I6745afad159270c5ccd9be2e68f96d8dafc1dc04

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

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 <net-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 <local_ip_id> <fixed_port_id>
+    +------------------+--------------------------------------+
+    | 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

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 <local_ips>`.
+
+
 Further Reading
 ---------------
 

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``