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/nfn-operator (Network Function Networking operator)
  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 ovn4nfvk8s Plugin
  67 -----------------
  68
  69 This 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/ NFN-Operator 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/
  93 nfn-operator is created. It assumes that it will be used in
  94 conjuction with Multus_or other similar CNI which allows for the
  95 co-existance of multipleCNI plugins in runtime. This plugin assumes
  96 that the first interface in a Pod is provided by some other Plugin/CNI
  97 like Flannel or even OVN-Kubernetes. It is only responsible to add
  98 multiple interfacesbased on the Pod annotations. The code is based on
  99 ovn-kubernetes_.
 100
 101 NFN-Operator has following functionalities:
 102 1) It watches pods for annotations (see below)
 103 2) It is a CRD Controller for dynamic networks, provider networks and
 104    dynamic route creation.
 105 3) It is a gRPC server for nfn-agent running on all nodes in the cluster
 106
 107 nfn-operator uses operator-sdk and controller runtime for watching for
 108 pods and also other CR's. For creating dynamic logical networks Network
 109 CRD controller creates OVN logical switch as defined in CR. For provider
 110 network creation Provider Network CRD controller works with nfn-agent
 111 running on nodes to create provider network. nfn-operator communicates
 112 with nfn agent using gRPC. Currently only VLAN based provider networks
 113 are supported.
 114
 115 .. note::
 116
 117  This plugin is currently tested to work with Multus and Flannel
 118  providing the first network interface.
 119
 120 To meet the requirement of multiple interfaces and IP's per pod,
 121 a Pod annotation like below is required when working with Multus:
 122
 123
 124 .. code-block:: yaml
 125
 126
 127   annotations:
 128      k8s.v1.cni.cncf.io/networks: '[{ "name": "ovn-networkobj"}]'
 129      k8s.plugin.opnfv.org/nfn-network: '{ "type": "ovn4nfv", "interface": [
 130          { "name": <name of OVN Logical Switch>, "interfaceRequest": "eth1" },
 131          { "name":  <name of OVN Logical Switch>, "interfaceRequest": "eth2" }
 132   ]}'
 133
 134 Based on these annotations watcher service in OVN4NFVK8s plugin/
 135 nfn-operator assumes logical switch is already present. Dynamic IP
 136 addresses are assigned (static IP's also supported) and annotations
 137 are updated.
 138
 139 When the Pod is initialized on a node, OVN4NFVK8s CNI creates multiple
 140 interfaces and assigns IP addresses for the pod based on the annotations.
 141
 142 **Multus Configuration**
 143 Multus CRD definition for OVN:
 144
 145 .. code-block:: yaml
 146
 147   apiVersion: "k8s.cni.cncf.io/v1"
 148   kind: NetworkAttachmentDefinition
 149   metadata:
 150     name: ovn-networkobj
 151   spec:
 152     config: '{
 153         "cniVersion": "0.3.1",
 154         "name": "ovn4nfv-k8s-plugin",
 155         "type": "ovn4nfvk8s-cni"
 156       }'
 157
 158 Please refer to Multus_ for details about how this configuration is used
 159
 160 CNI configuration file for Multus with Flannel:
 161
 162 .. code-block:: yaml
 163
 164  {
 165   "type": "multus",
 166   "name": "multus-cni",
 167   "cniVersion": "0.3.1",
 168   "kubeconfig": "/etc/kubernetes/admin.conf",
 169   "delegates": [
 170     {
 171       "type": "flannel",
 172       "cniVersion": "0.3.1",
 173       "masterplugin": true,
 174       "delegate": {
 175         "isDefaultGateway": false
 176       }
 177     }
 178   ]
 179  }
 180
 181 Refer Kubernetes_ documentation for the order in which CNI configurations
 182 are applied.
 183
 184
 185 **Build**
 186
 187 For building the project:
 188
 189 .. code-block:: bash
 190
 191   cd ovn4nfv-k8s-plugin
 192   make
 193
 194
 195 This will output two files nfn-operator, nfn-agent and ovn4nfvk8s-cni which are the plugin/
 196  operator, gRPC client and CNI binaries respectively.
 197
 198 ovn4nfvk8s-cni requires some configuration at start up.
 199
 200 Example configuration file (default location/etc/openvswitch/ovn4nfv_k8s.conf)
 201
 202 .. code-block:: yaml
 203
 204   [logging]
 205   loglevel=5
 206   logfile=/var/log/openvswitch/ovn4k8s.log
 207
 208   [cni]
 209   conf-dir=/etc/cni/net.d
 210   plugin=ovn4nfvk8s-cni
 211
 212   [kubernetes]
 213   kubeconfig=/etc/kubernetes/admin.conf
 214
 215
 216
 217 **CRD Controllers**
 218
 219
 220 nfn-operator includes controllers for 3 types of CRDs:
 221
 222 1) Network CRD - To create logical networks.
 223
 224 2) Provider Network CRD - To Create Provider networks. This works along with nfn-agent
 225    to create provider networks on nodes in cluster as needed.
 226
 227 3) Chaining operator - To provision routes in Pods as per CR definition.
 228
 229
 230
 231 **Network CR Example**
 232
 233
 234 .. code-block:: yaml
 235
 236   apiVersion: k8s.plugin.opnfv.org/v1alpha1
 237   kind: Network
 238   metadata:
 239     name: example-network
 240   spec:
 241     # Add fields here
 242     cniType: ovn4nfv
 243     ipv4Subnets:
 244     - subnet: 172.16.44.0/24
 245       name: subnet1
 246       gateway: 172.16.44.1/24
 247       excludeIps: 172.16.44.2 172.16.44.5..172.16.44.10
 248
 249
 250
 251 **Provider Network CR Example**
 252
 253
 254 .. code-block:: yaml
 255
 256   apiVersion: k8s.plugin.opnfv.org/v1alpha1
 257   kind: ProviderNetwork
 258   metadata:
 259     name: pnetwork
 260   spec:
 261     cniType: ovn4nfv
 262     ipv4Subnets:
 263     - subnet: 172.16.33.0/24
 264       name: subnet1
 265       excludeIps: 172.16.33.2 172.16.33.5..172.16.33.10
 266     providerNetType: VLAN
 267     vlan:
 268       vlanId: "100"
 269       providerInterfaceName: eth1
 270       logicalInterfaceName: eth1.100
 271       vlanNodeSelector: specific
 272       nodeLabelList:
 273       - kubernetes.io/hostname=testnode1
 274
 275 **Chaining CR Example**
 276
 277 TODO
 278
 279
 280 **Figure**
 281
 282
 283 .. code-block:: raw
 284
 285     +-----------------+
 286     |                 |
 287     |                 |   Program OVN Switch
 288     |ovn4nfvk8s Plugin|                      +------------------+
 289     |                 +--------------------->|                  |
 290     |                 |                      | OVN Switch       |
 291     |                 |                      |                  |
 292     |                 |                      +------------------+
 293     +----+----------+-+
 294          ^          |
 295          |          |
 296          |On Event  |Annotate Pod
 297          |          |
 298          |          v
 299     +----+--------------+        +------------------+           +-----------+
 300     |                   |        |                  |           | Pod       |
 301     |  Kube API         +-------->  Kube Scheduler  +---------->|           |
 302     |                   |        |                  |           +--------+--+
 303     |                   |        +--------+---------+                    |
 304     +-------------------+                 |                              |
 305                                           |                              |
 306                                           |                              |Assign IP & MAC
 307                                  +--------v-----------+                  |
 308                                  |                    |                  |
 309                                  | ovn4nfvk8s-cni     |                  |
 310                                  |                    +------------------+
 311                                  +--------------------+
 312
 313
 314
 315
 316 **References**
 317
 318 .. _ovn-kubernetes: https://github.com/openvswitch/ovn-kubernetes
 319 .. _Multus: https://github.com/intel/multus-cni
 320 .. _Kubernetes: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/
 321
 322 **Authors/Contributors**
 323
 324 Addepalli, Srinivasa R <srinivasa.r.addepalli@intel.com>
 325 Sood, Ritu <ritu.sood@intel.com>
 326