openstack/kuryr
Code Issues Proposed changes

Add design and devref section in documentation

Browse Source 
1. Move design doc to the new section and enhance it with
   changes made on the spec (neutron side in the process)
2. Add goals document from the spec

This section will now be used to hold the specific designs
for all the various parts and integration with magnum/kolla

Change-Id: I9ab00408553c4aed8a07ad0f7f656e6dd9d1fa3c
This commit is contained in:
Gal Sagie 2015-09-03 10:11:02 +03:00
parent 6272cd2586
commit d5cd2d0abb
4 changed files with 212 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
doc/source/devref/goals_and_use_cases.rst Normal file
View File

@ -0,0 +1,64 @@
=====================
Goals And Use Cases
=====================
Kuryr provides networking to Docker containers by leveraging the Neutron APIs and services.
It also provides containerized images for common Neutron plugins
Kuryr implements a `libnetwork remote driver`_ and maps its calls to OpenStack
`Neutron`_. It works as a translator between libnetwork's
`Container Network Model`_ (CNM) and `Neutron's networking model`_
and provides container-host or container-vm (nested VM) binding.
Using Kuryr any Neutron plugin can be used as a libnetwork remote driver explicitly.
Neutron APIs are vendor agnostic and thus all Neutron plugins will have the capability of
providing the networking backend of Docker with a common lightweight plugging snippet
as they have in nova.
Kuryr takes care of binding the container namespace to the networking infrastructure
by providing a generic layer for `VIF binding`_ depending on the port type
for example Linux bridge port, Open vSwitch port, Midonet port and so on.
Kuryr should be the gateway between containers networking API and use cases and
Neutron APIs and services and should bridge the gaps between the two in both
domains.
It will map the missing parts in Neutron and drive changes to adjust it.
Kuryr should address `Magnum`_ project use cases in terms of containers networking and
serve as a unified interface for Magnum or any other OpenStack project that needs to leverage
containers networking through Neutron API.
In that regard, Kuryr aims at leveraging Neutron plugins that support VM nested container's use
cases and enhancing Neutron APIs to support these cases (for example `OVN`_).
An etherpad regarding `Magnum Kuryr Integration`_ describes the various use cases Kuryr
needs to support.
Kuryr should provide containerized Neutron plugins for easy deployment and must be
compatible with OpenStack `Kolla`_ project and its deployment tools.
The containerized plugins have the common Kuryr binding layer which binds
the container to the network infrastructure.
Kuryr should leverage Neutron sub-projects and services (in particular LBaaS, FWaaS, VPNaaS) to
provide to support advanced containers networking use cases and to be consumed
by containers orchestration management systems (for example Kubernetes , or even OpenStack Magnum)
Kuryr also support pre-allocating of networks, ports and subnets, and binding
them to Docker networks/endpoints upon creation depending on specific
labels that are passed during Docker creation.
There is a patch being merged in Docker to support providing user labels
upon network creation. you can look at this `User labels in docker patch`_.
References
----------
.. _libnetwork remote driver: https://github.com/docker/libnetwork/blob/master/docs/remote.md
.. _Neutron: https://wiki.openstack.org/wiki/Neutron
.. _Container Network Model: https://github.com/docker/libnetwork/blob/master/docs/design.md#the-container-network-model
.. _Neutron's networking model: https://wiki.openstack.org/wiki/Neutron/APIv2-specification
.. _VIF binding: https://blueprints.launchpad.net/kuryr/+spec/vif-binding-and-unbinding-mechanism
.. _Magnum: https://wiki.openstack.org/wiki/Magnum
.. _OVN: https://launchpad.net/networking-ovn
.. _Kolla: https://wiki.openstack.org/wiki/Kolla
.. _APIs: https://github.com/docker/libnetwork/blob/master/docs/design.md#api
.. _User labels in docker patch: https://github.com/docker/libnetwork/pull/222/files#diff-2b9501381623bc063b38733c35a1d254
.. _Magnum Kuryr Integration: https://etherpad.openstack.org/p/magnum-kuryr

46
doc/source/devref/index.rst Normal file
View File

@ -0,0 +1,46 @@
..
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.)
Design and Developer Docs
==========================
Kuryr goal is to bring containers networking to Neutron core API
and advanced networking services.
This section contains detailed designs / project integration plans and low level
use cases for the various parts inside Kuryr.
Programming HowTos and Tutorials
--------------------------------
.. toctree::
:maxdepth: 3
goals_and_use_cases
libnetwork_remote_driver_design
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

119
doc/source/design.rst → doc/source/devref/libnetwork_remote_driver_design.rst
View File

@ -1,36 +1,34 @@
===============
Design of Kuryr
===============
===============================
Libnetwork Remote Driver Design
================================
What is Kuryr
~~~~~~~~~~~~~
--------------
Kuryr implements a `libnetwork remote driver`_ and maps its calls to OpenStack
`Neutron`_. It works as a translator between libnetwork's
`Container Network Model`_ (CNM) and `Neutron's networking model`_.
.. _libnetwork remote driver: https://github.com/docker/libnetwork/blob/master/docs/remote.md
.. _Neutron: https://wiki.openstack.org/wiki/Neutron
.. _Container Network Model: https://github.com/docker/libnetwork/blob/master/docs/design.md#the-container-network-model
.. _Neutron's networking model: https://wiki.openstack.org/wiki/Neutron/APIv2-specification
Goal
----
~~~~~
Through Kuryr any Neutron plugin can communicate with libnetwork. Neutron APIs
are vendor agnostic and thus all Neutron plugins will have the capability of
Through Kuryr any Neutron plugin can be used as libnetwork backend with no additional
effort.
Neutron APIs are vendor agnostic and thus all Neutron plugins will have the capability of
providing the networking backend of Docker for a similar small plugging snippet
as they have in nova.
Kuryr also takes care of binding one of a veth pair to a network interface on
the host, e.g., Linux bridge, Open vSwitch datapath and so on.
Kuryr Workflow
~~~~~~~~~~~~~~
Kuryr Workflow - Host Networking
---------------------------------
Kuryr resides in each host that runs Docker containers and serves `APIs`_
required for the libnetwork remote driver.
It is planned to use the `Adding tags to resources`_ new Neutron feature by Kuryr,
to map between Neutron resource Id's and Docker Id's (UUID's)
1. libnetwork discovers Kuryr via `plugin discovery mechanism`_
@ -38,35 +36,35 @@ required for the libnetwork remote driver.
``/Plugin.Active`` and examines if it's a network driver
2. libnetwork registers Kuryr as a remote driver
3. A user makes requests against libnetwork with the driver specifier for Kuryr
- i.e., ``--driver=kuryr`` or ``-d kuryr`` for the Docker CLI
4. libnetwork makes API calls against Kuryr
5. Kuryr receives the requests and calls Neutron APIs with `Neutron client`_
6. Kuryr receives the responses from Neutron and compose the responses for
libnetwork
7. Kuryr returns the responses to libnetwork
8. libnetwork stores the returned information to its key/value datastore
backend
- the key/value datastore is abstracted by `libkv`_
.. _APIs: https://github.com/docker/libnetwork/blob/master/docs/design.md#api
.. _plugin discovery mechanism: https://github.com/docker/docker/blob/master/docs/extend/plugin_api.md#plugin-discovery
.. _Neutron client: http://docs.openstack.org/developer/python-neutronclient/
.. _libkv: https://github.com/docker/libkv
User Workflow
~~~~~~~~~~~~~
Libnetwork User Workflow (with Kuryr as remove driver) - Host Networking
-------------------------------------------------------------------------
1. A user creates a network ``foo``
::
$ sudo docker network create --driver=kuryr foo
51c75a2515d47edecc3f720bb541e287224416fb66715eb7802011d6ffd499f1
This makes a HTTP POST call on ``/NetworkDriver.CraeteNetwork`` with the
This makes a HTTP POST call on ``/NetworkDriver.CreateNetwork`` with the
following JSON data.
::
@ -77,6 +75,11 @@ User Workflow
}
}
The Kuryr remote driver will then generate a Neutron API request to create an underlying Neutron network.
When the Neutron network has been created, the Kuryr remote driver will generate an empty success response
to the docker daemon.
Kuryr tags the Neutron network with the NetworkID from docker.
2. A user creates a service ``bar`` against network ``foo``
::
@ -98,6 +101,38 @@ User Workflow
}
}
The Kuryr remote driver then generate a Neutron API request to create a Neutron
subnet and a port with the matching fields for all interfaces in the request.
Kuryr needs to create the subnet dynamically as it has no information on
the interfaces list IP's.
the following steps are taken:
1) On the endpoint creation Kuryr examine if there's a subnet which CIDR corresponds to
Address or AddressIPv6 requested.
2) If there's a subnet, Kuryr tries to reuse it without creating a new subnet.
otherwise it create a new one with the given CIDR
3) If a CIDR is not passed, Kuryr creates a default IPv4 or IPv6 subnets from a
specific subnet pool.
more information can be found in Kuryr `IPAM blueprint`_
4) Kuryr creates a port assigning the IP address to it and associating the port with
the subnet based on it's already allocated in 2.
When the Neutron port has been created, the Kuryr remote driver will generate a response to the
docker daemon indicating the port's IPv4, IPv6, and Mac addresses as follows.
::
{
"Interfaces": [{
"ID": <port-id>,
"Address": <port-fixed-IP-address>,
"AddressIPv6": <port-fixed-IPv6-address>,
"MacAddress": <port-mac-addr>
}, ...]
}
Kuryr tags the Neutron subnet and port with Docker Interface id.
3. A user shows information of the service
::
@ -132,6 +167,18 @@ User Workflow
}
}
Kuryr connects the container to the corresponding neutron network by doing the following steps:
1) Generate a veth pair
2) Connect one end of the veth pair to the container (which is running in a namespace
that was created by Docker)
3) Perform a neutron-port-type-dependent VIF-binding to the corresponding Neutron port
using the VIF binding layer and depending on the specific port type.
After the VIF-binding is completed, the Neutron remote driver generate a response to the Docker
daemon as specified in the libnetwork documentation for a join request.
(https://github.com/docker/libnetwork/blob/master/docs/remote.md#join)
5. A user detaches the container from the service
::
@ -146,6 +193,9 @@ User Workflow
"EndpointID": "98953db3f8e6628caf4a7cad3c866cb090654e3dee3e37206ad8c0a81355f1b7"
}
Kuryr remote driver will remove the VIF binding between the container and the Neutron port,
and generate an empty response to the Docker daemon.
6. A user unpublishes the service
::
@ -160,6 +210,10 @@ User Workflow
"EndpointID": "98953db3f8e6628caf4a7cad3c866cb090654e3dee3e37206ad8c0a81355f1b7"
}
Kuryr remote driver generate a Neutron API request to delete the associated Neutron port,
in case the relevant port subnet is empty, Kuryr also deletes the subnet object using Neutron API
and generate an empty response to the Docker daemon: {}
7. A user deletes the network
::
@ -173,6 +227,10 @@ User Workflow
"NetworkID": "51c75a2515d47edecc3f720bb541e287224416fb66715eb7802011d6ffd499f1"
}
Kuryr remote driver generate a Neutron API request to delete the corresponding Neutron network.
When the Neutron network has been deleted, the Kuryr remote driver generate an empty response
to the docker daemon: {}
The workflows described in 2., 4., 5. and 6. can be done in the following
single command.::
@ -180,11 +238,11 @@ single command.::
Mapping between the CNM and the Neutron's Networking Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------------------
Kuryr communicates with Neutron via `Neutron client`_ and bridges between
libnetwork and Neutron traslating their networking models. The mapping
between them can be expressed as the following table.
libnetwork and Neutron by translating their networking models. The following
table depicts the current mapping between libnetwork and Neutron models:
===================== ======================
libnetwork Neutron
@ -199,3 +257,14 @@ however, Sandbox is invisible from users directly and Endpoint is only the
visible and editable resource entity attachable to containers from users'
perspective. Sandbox manages information exposed by Endpoint behind the scene
automatically.
.. _libnetwork remote driver: https://github.com/docker/libnetwork/blob/master/docs/remote.md
.. _Neutron: https://wiki.openstack.org/wiki/Neutron
.. _Container Network Model: https://github.com/docker/libnetwork/blob/master/docs/design.md#the-container-network-model
.. _Neutron's networking model: https://wiki.openstack.org/wiki/Neutron/APIv2-specification
.. _Neutron client: http://docs.openstack.org/developer/python-neutronclient/
.. _plugin discovery mechanism: https://github.com/docker/docker/blob/master/docs/extend/plugin_api.md#plugin-discovery
.. _Adding tags to resources: https://review.openstack.org/#/c/216021/
.. _APIs: https://github.com/docker/libnetwork/blob/master/docs/design.md#api
.. _libkv: https://github.com/docker/libkv
.. _IPAM blueprint: https://blueprints.launchpad.net/kuryr/+spec/ipam

8
doc/source/index.rst
View File

@ -17,6 +17,14 @@ Contents:
usage
contributing
Design and Developer Docs
==========================
.. toctree::
:maxdepth: 1
devref/index
Indices and tables
==================