README.rst

   1 .. Copyright 2018 Intel Corporation.
   2    Licensed under the Apache License, Version 2.0 (the "License");
   3    you may not use this file except in compliance with the License.
   4    You may obtain a copy of the License at
   5         http://www.apache.org/licenses/LICENSE-2.0
   6    Unless required by applicable law or agreed to in writing, software
   7    distributed under the License is distributed on an "AS IS" BASIS,
   8    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   9    See the License for the specific language governing permissions and
  10    limitations under the License.
  11
  12 =================
  13 OVN4NFVK8s Plugin
  14 =================
  15
  16 Problem statement
  17 -----------------
  18
  19 Networking applications are of three types - Management applications,
  20 Control plane applications and data plane applications. Management
  21 and control plane applications are similar to Enterprise applications,
  22 but data plane applications different in following aspects:
  23
  24 - Multiple virtual network interfaces
  25 - Multiple IP addresses
  26 - SRIOV networking support
  27 - Programmable virtual switch (for service function chaining, to tap
  28   the traffic for visibility etc..)
  29
  30 Kubernetes (Simply K8S) is the most popular container orchestrator.
  31 K8S is supported by GCE, AZURE and AWS and will be supported by
  32 Akraino Edge stack that enable edge clouds.
  33
  34 K8S has being enhanced to support VM workload types, this helps
  35 cloud providers that need to migrate legacy workloads to microservices
  36 architecture. Cloud providers may continue to support VM workload
  37 types for security reasons and hence there is need for VIM that
  38 support both VMs and containers. Since same K8S instance can
  39 orchestrate both VM and container workload types, same compute nodes
  40 can be leveraged for both VMs and containers. Telco and CSPs are
  41 seeing similar need to deploy networking applications as containers.
  42
  43 Since, both VMs and container workloads are used for networking
  44 applications, there would be need for
  45
  46 - Sharing the networks across VMs and containers.
  47 - Sharing the volumes across VMs and containers.
  48
  49 **Network Function Virtualization Requirements**
  50
  51 NFV workloads can be,
  52
  53 - Management plane workloads
  54 - Control plane work loads
  55 - User plane (data plane workloads)
  56 - User plane workloads normally have
  57 - Multiple interfaces, Multiple subnets, Multiple virtual networks
  58 - NFV workloads typically have its own management network.
  59 - Some data plane workloads require SR-IOV NIC support for data
  60   interfaces and virtual NIC for other interfaces (for performance
  61   reasons)
  62 - Need for multiple CNIs.
  63 - NFV workloads require dynamic creation of virtual networks. Dynamic
  64   configuration of subnets.
  65
  66 New Proposal
  67 ------------
  68
  69 A new plugin addresses the below requirements, for networking
  70 workloads as well typical application workloads
  71 - Multi-interface support
  72 - Multi-IP address support
  73 - Dynamic creation of virtual networks
  74 - Co-existing with SRIOV and other CNIs.
  75 - Route management across virtual networks and external networks
  76
  77 **OVN Background**
  78
  79 OVN, the Open Virtual Network, is a system to support virtual network
  80 abstraction. OVN complements the existing capabilities of OVS to add
  81 native support for virtual network abstractions, such as virtual L2
  82 and L3 overlays and security groups. Services such as DHCP are also
  83 desirable features. Just like OVS, OVN’s design goal is to have a
  84 production quality implementation that can operate at significant
  85 scale.
  86
  87 **OVN4NFVK8s Plugin development**
  88
  89 ovn-kubernetes_ plugin is part of OVN project which provides OVN
  90 integration with Kubernetes but doesn't address the requirements
  91 as given above. To meet those requirements like multiple interfaces,
  92 IPs, dynamic creation of virtual networks, etc., OVN4NFVK8s plugin is
  93 created. It assumes that it will be used in conjuction with Multus_
  94 or other similar CNI which allows for the co-existance of multiple
  95 CNI plugins in runtime. This plugin assumes that the first interface
  96 in a Pod is provided by some other Plugin/CNI like Flannel or even
  97 OVN-Kubernetes. It is only responsible to add multiple interfaces
  98 based on the Pod annotations. The code is based on ovn-kubernetes_.
  99
 100
 101 .. note::
 102
 103  This plugin is currently tested to work with Multus and Flannel
 104  providing the first network interface.
 105
 106 To meet the requirement of multiple interfaces and IP's per pod,
 107 a Pod annotation like below is required when working with Multus:
 108
 109
 110 .. code-block:: yaml
 111
 112
 113   annotations:
 114      k8s.v1.cni.cncf.io/networks: '[{ "name": "ovn-networkobj"}]'
 115      ovnNetwork '[
 116          { "name": <name of OVN Logical Switch>, "interfaceRequest": "eth1" },
 117          { "name":  <name of OVN Logical Switch>, "interfaceRequest": "eth2" }
 118   ]'
 119
 120 Based on these annotations watcher service in OVN4NFVK8s plugin assumes
 121 logical switch is already present. Dynamic IP addresses are assigned
 122 (static IP's also supported) and annotations are updated.
 123
 124 When the Pod is initialized on a node, OVN4NFVK8s CNI creates multiple
 125 interfaces and assigns IP addresses for the pod based on the annotations.
 126
 127 **Multus Configuration**
 128 Multus CRD definition for OVN:
 129
 130 .. code-block:: yaml
 131
 132   apiVersion: "k8s.cni.cncf.io/v1"
 133   kind: NetworkAttachmentDefinition
 134   metadata:
 135     name: ovn-networkobj
 136   spec:
 137     config: '{
 138         "cniVersion": "0.3.1",
 139         "name": "ovn4nfv-k8s-plugin",
 140         "type": "ovn4nfvk8s-cni"
 141       }'
 142
 143 Please refer to Multus_ for details about how this configuration is used
 144
 145 CNI configuration file for Multus with Flannel:
 146
 147 .. code-block:: yaml
 148
 149  {
 150   "type": "multus",
 151   "name": "multus-cni",
 152   "cniVersion": "0.3.1",
 153   "kubeconfig": "/etc/kubernetes/admin.conf",
 154   "delegates": [
 155     {
 156       "type": "flannel",
 157       "cniVersion": "0.3.1",
 158       "masterplugin": true,
 159       "delegate": {
 160         "isDefaultGateway": false
 161       }
 162     }
 163   ]
 164  }
 165
 166 Refer Kubernetes_ documentation for the order in which CNI configurations
 167 are applied.
 168
 169
 170 **Build**
 171
 172 For building the project:
 173
 174 .. code-block:: bash
 175
 176   cd ovn4nfv-k8s-plugin
 177   make
 178
 179
 180 This will output two files ovn4nfvk8s and ovn4nfvk8s-cni which are the plugin
 181  and CNI binaries respectively.
 182
 183 ovn4nfvk8s plugin requires some configuration at start up.
 184
 185 Example configuration file (default location/etc/openvswitch/ovn4nfv_k8s.conf)
 186
 187 .. code-block:: yaml
 188
 189   [logging]
 190   loglevel=5
 191   logfile=/var/log/openvswitch/ovn4k8s.log
 192
 193   [cni]
 194   conf-dir=/etc/cni/net.d
 195   plugin=ovn4nfvk8s-cni
 196
 197   [kubernetes]
 198   kubeconfig=/etc/kubernetes/admin.conf
 199
 200
 201
 202 **Figure**
 203
 204 .. code-block:: raw
 205
 206     +-----------------+
 207     |                 |
 208     |                 |   Program OVN Switch
 209     |ovn4nfvk8s Plugin|                      +------------------+
 210     |                 +--------------------->|                  |
 211     |                 |                      | OVN Switch       |
 212     |                 |                      |                  |
 213     |                 |                      +------------------+
 214     +----+----------+-+
 215          ^          |
 216          |          |
 217          |On Event  |Annotate Pod
 218          |          |
 219          |          v
 220     +----+--------------+        +------------------+           +-----------+
 221     |                   |        |                  |           | Pod       |
 222     |  Kube API         +-------->  Kube Scheduler  +---------->|           |
 223     |                   |        |                  |           +--------+--+
 224     |                   |        +--------+---------+                    |
 225     +-------------------+                 |                              |
 226                                           |                              |
 227                                           |                              |Assign IP & MAC
 228                                  +--------v-----------+                  |
 229                                  |                    |                  |
 230                                  | ovn4nfvk8s-cni     |                  |
 231                                  |                    +------------------+
 232                                  +--------------------+
 233
 234
 235
 236
 237 **References**
 238
 239 .. _ovn-kubernetes: https://github.com/openvswitch/ovn-kubernetes
 240 .. _Multus: https://github.com/intel/multus-cni
 241 .. _Kubernetes: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/
 242
 243 **Authors/Contributors**
 244
 245 Addepalli, Srinivasa R <srinivasa.r.addepalli@intel.com>
 246 Sood, Ritu <ritu.sood@intel.com>