Documentation/howto/openstack-containers.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ================================================
  25 Integration of Containers with OVN and OpenStack
  26 ================================================
  27
  28 Isolation between containers is weaker than isolation between VMs, so some
  29 environments deploy containers for different tenants in separate VMs as an
  30 additional security measure.  This document describes creation of containers
  31 inside VMs and how they can be made part of the logical networks securely.  The
  32 created logical network can include VMs, containers and physical machines as
  33 endpoints.  To better understand the proposed integration of containers with
  34 OVN and OpenStack, this document describes the end to end workflow with an
  35 example.
  36
  37 * A OpenStack tenant creates a VM (say VM-A) with a single network interface
  38   that belongs to a management logical network.  The VM is meant to host
  39   containers.  OpenStack Nova chooses the hypervisor on which VM-A is created.
  40
  41 * A Neutron port may have been created in advance and passed in to Nova with
  42   the request to create a new VM.  If not, Nova will issue a request to Neutron
  43   to create a new port.  The ID of the logical port from Neutron will also be
  44   used as the vif-id for the virtual network interface (VIF) of VM-A.
  45
  46 * When VM-A is created on a hypervisor, its VIF gets added to the Open vSwitch
  47   integration bridge.  This creates a row in the Interface table of the
  48   ``Open_vSwitch`` database.  As explained in the :doc:`integration guide
  49   </topics/integration>`, the vif-id associated with the VM network interface
  50   gets added in the ``external_ids:iface-id`` column of the newly created row
  51   in the Interface table.
  52
  53 * Since VM-A belongs to a logical network, it gets an IP address.  This IP
  54   address is used to spawn containers (either manually or through container
  55   orchestration systems) inside that VM and to monitor the health of the
  56   created containers.
  57
  58 * The vif-id associated with the VM's network interface can be obtained by
  59   making a call to Neutron using tenant credentials.
  60
  61 * This flow assumes a component called a "container network plugin".  If you
  62   take Docker as an example for containers, you could envision the plugin to be
  63   either a wrapper around Docker or a feature of Docker itself that understands
  64   how to perform part of this workflow to get a container connected to a
  65   logical network managed by Neutron.  The rest of the flow refers to this
  66   logical component that does not yet exist as the "container network plugin".
  67
  68 * All the calls to Neutron will need tenant credentials.  These calls can
  69   either be made from inside the tenant VM as part of a container network
  70   plugin or from outside the tenant VM (if the tenant is not comfortable using
  71   temporary Keystone tokens from inside the tenant VMs).  For simplicity, this
  72   document explains the work flow using the former method.
  73
  74 * The container hosting VM will need Open vSwitch installed in it.  The only
  75   work for Open vSwitch inside the VM is to tag network traffic coming from
  76   containers.
  77
  78 * When a container needs to be created inside the VM with a container network
  79   interface that is expected to be attached to a particular logical switch, the
  80   network plugin in that VM chooses any unused VLAN (This VLAN tag only needs
  81   to be unique inside that VM.  This limits the number of container interfaces
  82   to 4096 inside a single VM).  This VLAN tag is stripped out in the hypervisor
  83   by OVN and is only useful as a context (or metadata) for OVN.
  84
  85 * The container network plugin then makes a call to Neutron to create a logical
  86   port.  In addition to all the inputs that a call to create a port in Neutron
  87   that are currently needed, it sends the vif-id and the VLAN tag as inputs.
  88
  89 * Neutron in turn will verify that the vif-id belongs to the tenant in question
  90   and then uses the OVN specific plugin to create a new row in the
  91   Logical_Switch_Port table of the OVN Northbound Database.  Neutron responds
  92   back with an IP address and MAC address for that network interface.  So
  93   Neutron becomes the IPAM system and provides unique IP and MAC addresses
  94   across VMs and containers in the same logical network.
  95
  96 * The Neutron API call above to create a logical port for the container could
  97   add a relatively significant amount of time to container creation.  However,
  98   an optimization is possible here.  Logical ports could be created in advance
  99   and reused by the container system doing container orchestration.  Additional
 100   Neutron API calls would only be needed if the port needs to be attached to a
 101   different logical network.
 102
 103 * When a container is eventually deleted, the network plugin in that VM may
 104   make a call to Neutron to delete that port.  Neutron in turn will delete the
 105   entry in the ``Logical_Switch_Port`` table of the OVN Northbound Database.
 106
 107 As an example, consider Docker containers.  Since Docker currently does not
 108 have a network plugin feature, this example uses a hypothetical wrapper around
 109 Docker to make calls to Neutron.
 110
 111 * Create a Logical switch::
 112
 113       $ ovn-docker --cred=cca86bd13a564ac2a63ddf14bf45d37f create network LS1
 114
 115   The above command will make a call to Neutron with the credentials to create
 116   a logical switch.  The above is optional if the logical switch has already
 117   been created from outside the VM.
 118
 119 * List networks available to the tenant::
 120
 121       $ ovn-docker --cred=cca86bd13a564ac2a63ddf14bf45d37f list networks
 122
 123 * Create a container and attach a interface to the previously created switch as
 124   a logical port::
 125
 126       $ ovn-docker --cred=cca86bd13a564ac2a63ddf14bf45d37f --vif-id=$VIF_ID \
 127           --network=LS1 run -d --net=none ubuntu:14.04 /bin/sh -c \
 128           "while true; do echo hello world; sleep 1; done"
 129
 130   The above command will make a call to Neutron with all the inputs it
 131   currently needs to create a logical port.  In addition, it passes the $VIF_ID
 132   and a unused VLAN.  Neutron will add that information in OVN and return back
 133   a MAC address and IP address for that interface.  ovn-docker will then create
 134   a veth pair, insert one end inside the container as 'eth0' and the other end
 135   as a port of a local OVS bridge as an access port of the chosen VLAN.