docs/specs/oxygen/coe-integration.rst

   1 .. contents:: Table of Contents
   2       :depth: 5
   3
   4 =======================
   5 Netvirt COE Integration
   6 =======================
   7
   8 https://git.opendaylight.org/gerrit/#/q/topic:coe_integration
   9
  10 This spec proposes how to integrate COE and Netvirt projects for enabling
  11 networking(L2 and L3 support) for containers.
  12
  13 COE(Container Orchestration Engine) project aims at developing a framework for integrating
  14 Container Orchestration Engine (like Kubernetes) and OpenDaylight. Netvirt will serve as
  15 the backend for COE, as Netvirt provides generic enough constructs which will work
  16 for VMs as well as Containers.
  17
  18 Problem Description
  19 ===================
  20
  21 Current Netvirt project does not have a driver that will work with Kubernetes baremetal cluster.
  22 COE project aims at enabling the same, and will require a plugin in Netvirt project
  23 to convert the events from Kubernetes to the required constructs in Netvirt.
  24
  25 Network Requirements
  26 ====================
  27 k8s imposes some fundamental requirements on the networking implementation:
  28
  29 * All containers can communicate without NAT.
  30
  31 * All nodes can communicate with containers without NAT.
  32
  33 * The IP the container sees itself is the same IP that others see.
  34
  35 The Kubernetes model is for each pod to have an IP in a flat shared namespace
  36 that allows full communication with physical computers and containers across
  37 the network.
  38
  39 High-Level Components:
  40 ======================
  41
  42 The high level view of the end to end solution is given in the below picture :
  43
  44 .. image:: images/coe-netvirt-integration-components.PNG
  45
  46
  47 Proposed change
  48 ===============
  49
  50 A new module called `coe` will be added in Netvirt which will serve as the watcher
  51 for all the container orchestration related events. This module will be responsible for
  52 converting the COE related constructs to Netvirt constructs.
  53
  54 Netvirt Changes
  55 ---------------
  56
  57 DHCP Module
  58 ^^^^^^^^^^^
  59
  60 COE will be using DHCP dynamic allocation feature in Netvirt, which has some missing parts
  61 for the integration to work. DHCP module's bind service logic so far works only for neutron ports.
  62 This has to be enhanced to work for k8s pods as well.
  63
  64 ARP Responder
  65 ^^^^^^^^^^^^^
  66
  67 ARP responder logic of Netvirt works only for neutron ports, this needs enhancements to work with
  68 k8s ports, so that ARP responses can be sent from OVS directly, without the need for sending the same
  69 to ODL.
  70
  71 Genius changes
  72 --------------
  73
  74 InterfaceManager
  75 ^^^^^^^^^^^^^^^^
  76
  77 IntefaceManager currently treats only nova port patterns(tap/vhu) as well as tunnel port patterns as
  78 unique. For any other portnames datapath-node-id will be prefixed to the port-name. CNI plugin
  79 creates unique ports which starts with "veth" prefix, and this needs to be added to the set of unique
  80 port patterns in Genius.
  81
  82 Use Cases
  83 ---------
  84
  85 Use Case 1:
  86 ^^^^^^^^^^^
  87 This will enable default Kubernetes behavior to allow all
  88 traffic from all sources inside or outside the cluster to all pods within the
  89 cluster. This use case does not add multi-tenancy support.
  90
  91 Use Case 2:
  92 ^^^^^^^^^^^
  93 Network isolation policy will impose limitations on the connectivity from an optional set of
  94 traffic sources to an optional set of destination TCP/UDP ports.
  95 Regardless of network policy, pods should be accessible by the host on which
  96 they are running to allow local health checks. This use case does not address
  97 multi-tenancy.
  98
  99 More enhanced use cases can be added in the future, that will allow to add
 100 extra functionality
 101
 102
 103 Model Mapping
 104 -------------
 105
 106 In order to support Kubernetes networking via Netvirt, we should define how
 107 COE model maps into Netvirt model.
 108
 109
 110 +-----------------+-------------------+---------------------------------------+
 111 | **COE entity**  | **Netvirt entity**| **notes**                             |
 112 +=================+===================+=======================================+
 113 |node + namespace | elan-instance     |  Whenever the first pod under         |
 114 |                 |                   |  a namespace in a node is created,an  |
 115 |                 |                   |  elan-instance has to be created.     |
 116 +-----------------+-------------------+---------------------------------------+
 117 |namespace        | vpn-instance      |  Whenever the first pod under a       |
 118 |                 |                   |  namespace is created, a vpn-instance |
 119 |                 |                   |  has to be created.                   |
 120 +-----------------+-------------------+---------------------------------------+
 121 |pod              | elan-interface    | For each pod created, an              |
 122 |                 |                   | elan-interface has to be created,     |
 123 |                 |                   | based on its node and namespace       |
 124 +-----------------+-------------------+---------------------------------------+
 125 |pod              | vpn-interface     | For each pod created, a               |
 126 |                 |                   | vpn-interface has to be created,      |
 127 |                 |                   | based on its namespace                |
 128 +-----------------+-------------------+---------------------------------------+
 129
 130 Pipeline Changes
 131 ----------------
 132
 133 No pipeline changes will be introduced as part of this feature.
 134
 135 Workflow
 136 --------
 137
 138 Configure DHCP Pool(Optional)
 139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 140 #. netvirt/dhcpmanager: For an immediate solution, a flat dhcp pool will be precreated
 141    manually, and IPs will be allocated for PODs from this pool.
 142 #. netvirt/dhcpmanager: For an immediate solution, a flat service pool will be precreated
 143    manually, and IPs will be allocated for SERVICEs from this pool.
 144
 145 Create Pod
 146 ^^^^^^^^^^
 147 #. coe/coe-northbound: User created a POD
 148 #. netvirt/coe: When the first POD is created under a namespace in a node, coe module in Netvirt will
 149    create an elan-instance with node-ip:namespace as the name. Also, for each POD, an ietf-interface
 150    as well as an elan-interface objects will be created in the MD-SAL datastore, with name
 151    set as "namespace:pod-name".
 152 #. netvirt/coe: When the first POD is created under a namespace, coe module in Netvirt will
 153    create a vpn-instance with namespace as the name. Also, for each POD, a vpn-interface object
 154    will be created in the MD-SAL datastore with name set as "namespace:pod-name".
 155 #. coe/cni-plugin:  The cni plugin in k8s will create the tap port on the OVS with external-id
 156    set to the "namespace:pod-name".
 157 #. genius/interfacemanager: Whenever the tapport is created, interfacemanager will take care of
 158    programming table0(Lport Ingress Table) and table220(Egress Dispatcher Table) programming,
 159    and population of interface-state.
 160 #. netvirt/elanmanager: Whenever interface-state is created, elanmanager will take care of
 161    populating all L2 related flows in OVS.
 162 #. netvirt/vpnmanager: Whenever interface-state is created, vpnmanager will take care of
 163    populating all L3 related flows in OVS.
 164
 165 Create Service
 166 ^^^^^^^^^^^^^^
 167
 168 #. netvirt/coe: When a pod is attached to a service, floating-ip-info has to be populated
 169 #. netvirt/natmanager: Listens on floating-ip-changes and do the NATing as it is done currently.
 170
 171 Delete Service
 172 ^^^^^^^^^^^^^^
 173
 174 #. netvirt/coe: When a pod is removed from a service, corresponding floating-ip-info will be removed.
 175 #. netvirt/natmanager: Listens on floating-ip-changes and remove the NAT rules approporiately.
 176
 177 Delete Pod
 178 ^^^^^^^^^^
 179
 180 #. coe/coe-northbound: User deleted a POD
 181 #. netvirt/coe: When the last POD is deleted under a namespace in a node, coe module in Netvirt will
 182    delete the elan-instance with namespace as the name. Also, for each POD, the corresponding ietf-interface
 183    as well as an elan-interface and vpn-interface objects will be deleted in the MD-SAL datastore.
 184 #. coe/cni-plugin:  The cni plugin in k8s will delete the tap port on the OVS.
 185 #. genius/interfacemanager: Whenever the tapport is deleted, interfacemanager will take care of
 186    deleting table0(Lport Ingress Table) and table220(Egress Dispatcher Table)
 187    flows on OVS, and deletion of interface-state.
 188 #. netvirt/elanmanager: Whenever interface-state is deleted, elanmanager will take care of
 189    removing all L2 related flows in OVS.
 190 #. netvirt/vpnmanager: Whenever interface-state is deleted, vpnmanager will take care of
 191    removing all L3 related flows in OVS.
 192
 193 Assumptions
 194 -----------
 195
 196
 197 Reboot Scenarios
 198 ----------------
 199 This feature support all the following Reboot Scenarios for EVPN:
 200     *  Entire Cluster Reboot
 201     *  Leader PL reboot
 202     *  Candidate PL reboot
 203     *  OVS Datapath reboots
 204     *  Multiple PL reboots
 205     *  Multiple Cluster reboots
 206     *  Multiple reboots of the same OVS Datapath.
 207     *  Openstack Controller reboots
 208
 209 Clustering considerations
 210 -------------------------
 211 The feature should operate in ODL Clustered environment reliably.
 212
 213 Other Infra considerations
 214 --------------------------
 215 N.A.
 216
 217 Security considerations
 218 -----------------------
 219 N.A.
 220
 221 Scale and Performance Impact
 222 ----------------------------
 223 Not covered by this Design Document.
 224
 225 Targeted Release
 226 ----------------
 227 Oxygen
 228
 229 Alternatives
 230 ------------
 231 An alternative for container networking is to use kuryr-kubernetes which will
 232 work with ODL as backend. However the same will not work in an environement where Openstack
 233 is not present. There are scenarios where Baremetal Kubernetes clusters have to work without
 234 Openstack, and this feature comes into picture there.
 235
 236 Usage
 237 =====
 238
 239 Features to Install
 240 -------------------
 241 This feature add the below new feature :
 242
 243     * odl-netvirt-coe
 244
 245 REST API
 246 --------
 247
 248 Creating DHCP Pool
 249 ^^^^^^^^^^^^^^^^^^
 250
 251 **URL:** restconf/config/dhcp_allocation_pool:dhcp_allocation_pool/
 252
 253 **Sample JSON data**
 254
 255 .. code-block:: json
 256
 257   {
 258     "dhcp_allocation_pool:network": [
 259      {
 260         "dhcp_allocation_pool:allocation-pool": [
 261           {
 262             "dhcp_allocation_pool:subnet": "192.168.10.0/24",
 263             "dhcp_allocation_pool:allocate-to": "192.168.10.50",
 264             "dhcp_allocation_pool:gateway": "192.168.10.2",
 265             "dhcp_allocation_pool:allocate-from": "192.168.10.3"
 266            }
 267         ],
 268         "dhcp_allocation_pool:network-id": "pod-namespace"
 269       }
 270     ]
 271   }
 272
 273 Creating POD directly in COE
 274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 275
 276 **URL:** restconf/config/pod:coe
 277
 278 **Sample JSON data**
 279
 280 .. code-block:: json
 281
 282   {
 283     "pod:pods": [
 284       {
 285         "pod:version": "Some version",
 286         "pod:uid": "AC092D9B-E9Eb-BAE2-eEd8-74Aca2B7Fa9C",
 287         "pod:interface": [
 288           {
 289             "pod:uid": "7bA91A3A-f17E-2eBB-eDec-3BBBEa27DCa7",
 290             "pod:ip-address": "0.147.0.7",
 291             "pod:network-id": "fBAD80df-B0B4-0580-8D14-11FcaCED2ac6",
 292             "pod:network-type": "FLAT",
 293             "pod:segmentation-id": "0"
 294           }
 295         ]
 296       }
 297     ]
 298   }
 299
 300 Creating SERVICE directly in COE
 301 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 302
 303 **URL:** restconf/config/service:service-information
 304
 305 **Sample JSON data**
 306
 307 .. code-block:: json
 308
 309   {
 310     "service:service-information": {
 311       "service:services": [
 312         {
 313           "service:uid": "EeafFFB7-D9Fc-aAeD-FBc9-8Af8BFaacDD9",
 314           "service:cluster-ip-address": "5.21.5.0",
 315           "service:endpoints": [
 316             "AFbcF0EB-Fc3f-acea-A438-5CFDfCEfbcb0"
 317           ]
 318         }
 319       ]
 320     }
 321   }
 322
 323 Assignee(s)
 324 -----------
 325
 326 Primary assignee:
 327   Faseela K <faseela.k@ericsson.com>
 328
 329 Other contributors:
 330    Frederick Kautz <fkautz@redhat.com>
 331
 332    Mohamed El-serngawy <m.elserngawy@gmail.com>
 333
 334 Work Items
 335 ----------
 336
 337 Dependencies
 338 ============
 339
 340 Testing
 341 =======
 342
 343 Junits
 344 ------
 345
 346 This feature will support following use cases:
 347
 348 * TC 1: Create a POD within a node under a namespace
 349 * TC 2: Attach a POD to service
 350 * TC 3: Remove a POD from service
 351 * TC 4: Delete a POD from a namespace
 352
 353 CSIT
 354 ----
 355 CSIT will be enhanced to cover this feature by providing new CSIT tests.
 356
 357 Documentation Impact
 358 ====================
 359 This will require changes to User Guide and Developer Guide.
 360
 361 References
 362 ==========
 363
 364 * OpenStack Spec  - https://review.openstack.org/#/c/453160
 365 * kuryr k8s integration - https://review.openstack.org/#/c/281132/14/doc/source/specs/mitaka/kuryr_k8s_integration.rst
 366 * cni plugin proposal - https://docs.google.com/presentation/d/1-gBGZ1zQQ1d9-ZLPuBbWx5PTb9MgxduRoAl2Z7gL2Zo/edit#slide=id.g29f465fad4_0_86
 367 * coe cni specification - https://docs.google.com/presentation/d/1DPfRSc11CzTa_qzvzQ-P7wQH0dPylag4eYT9sH06ajg/edit#slide=id.p