Add installation guide for kuryr-libnetwork

This patch proposes an installation guide that covers step-by-step
deployment of kuryr-libnetwork for new users of OpenStack with
sufficient Linux experience.

The instruction is to install kuryr-libnetwork from source since
there is no distro package for kuryr-libnetwork for now. This guide
covers installation in Ubunut as the first stpe. The support of
other OS is future work.

TODO: Configure the CI to publish this guide to:
https://docs.openstack.org/pike/install/

Change-Id: Id4f234068600564fa18e73aba08f6e43893456ee
This commit is contained in:
Hongbin Lu 2017-10-04 21:59:22 +00:00
parent 6fa464d38c
commit d0cec045ca
8 changed files with 267 additions and 0 deletions

View File

@ -21,6 +21,13 @@ Design and Developer Docs
devref/index
Installation Guide
==================
.. toctree::
:maxdepth: 1
install/index
Indices and tables
==================

View File

@ -0,0 +1,116 @@
Install and configure a compute node for Ubuntu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Kuryr-libnetwork
for Ubuntu 16.04 (LTS).
Prerequisites
-------------
This guide assumes Docker is already installed. Refer `Get Docker
<https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/>`_
for Docker installation.
Install and configure components
--------------------------------
#. Create kuryr user and necessary directories:
* Create user:
.. code-block:: console
# groupadd --system kuryr
# useradd --home-dir "/var/lib/kuryr" \
--create-home \
--system \
--shell /bin/false \
-g kuryr \
kuryr
* Create directories:
.. code-block:: console
# mkdir -p /etc/kuryr
# chown kuryr:kuryr /etc/kuryr
#. Clone and install kuryr-libnetwork:
.. code-block:: console
# apt-get install python-pip
# cd /var/lib/kuryr
# git clone https://git.openstack.org/openstack/kuryr-libnetwork.git
# chown -R kuryr:kuryr kuryr-libnetwork
# cd kuryr-libnetwork
# pip install -r requirements.txt
# python setup.py install
#. Generate a sample configuration file:
.. code-block:: console
# su -s /bin/sh -c "./tools/generate_config_file_samples.sh" kuryr
# su -s /bin/sh -c "cp etc/kuryr.conf.sample \
/etc/kuryr/kuryr.conf" kuryr
#. Edit the ``/etc/kuryr/kuryr.conf``:
* In the ``[DEFAULT]`` section, configure the path for the Kuryr
vif binding executables:
.. code-block:: ini
[DEFAULT]
...
bindir = /usr/local/libexec/kuryr
* In the ``[neutron]`` section, configure Identity service access:
.. code-block:: ini
[neutron]
...
auth_uri = http://controller:5000
auth_url = http://controller:35357
username = kuryr
user_domain_name = default
password = KURYR_PASSWORD
project_name = service
project_domain_name = default
auth_type = password
Replace KURYR_PASSWORD with the password you chose for the kuryr user in the
Identity service.
#. Create an upstart config, it could be named as
``/etc/systemd/system/kuryr-libnetwork.service``:
.. code-block:: ini
[Unit]
Description = Kuryr-libnetwork - Docker network plugin for Neutron
[Service]
ExecStart = /usr/local/bin/kuryr-server --config-file /etc/kuryr/kuryr.conf
CapabilityBoundingSet = CAP_NET_ADMIN
[Install]
WantedBy = multi-user.target
Finalize installation
---------------------
#. Enable and start the kuryr-libnetwork service:
.. code-block:: console
# systemctl enable kuryr-libnetwork
# systemctl start kuryr-libnetwork
#. After Kuryr starts, please restart your Docker service:
.. code-block:: console
# systemctl restart docker

View File

@ -0,0 +1,19 @@
Install and configure a compute node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the
Kuryr-libnetwork on the compute node.
This section assumes that you already have a working OpenStack
environment with at least the following components installed:
Network, Identity.
.. note::
The supported platforms are Ubuntu, openSUSE and SUSE Linux Enterprise,
and Red Hat Enterprise Linux and CentOS. This guide currently provides
installation stpes for Ubuntu. Other platforms will be introduced later.
.. toctree::
compute-install-ubuntu.rst

View File

@ -0,0 +1,41 @@
Install and configure controller node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure kuryr-libnetwork
on the controller node.
.. note::
The installation steps for Ubuntu, openSUSE and SUSE Linux Enterprise,
and Red Hat Enterprise Linux and CentOS are all the same.
#. Source the ``admin`` credentials to gain access to
admin-only CLI commands:
.. code-block:: console
$ . admin-openrc
#. To create the service credentials, complete these steps:
* Create the ``kuryr`` user:
.. code-block:: console
$ openstack user create --domain default --password-prompt kuryr
User Password:
Repeat User Password:
+-----------+----------------------------------+
| Field | Value |
+-----------+----------------------------------+
| domain_id | e0353a670a9e496da891347c589539e9 |
| enabled | True |
| id | ca2e175b851943349be29a328cc5e360 |
| name | kuryr |
+-----------+----------------------------------+
* Add the ``admin`` role to the ``kuryr`` user:
.. code-block:: console
$ openstack role add --project service --user kuryr admin

View File

@ -0,0 +1,24 @@
=========================
Kuryr-libnetwork overview
=========================
Kuryr-libnetwork is Kuryr's Docker libnetwork driver that uses Neutron to
provide networking services. It provides containerised images for the common
Neutron plugins.
Features
--------
* Docker libnetwork remote driver
* Docker libnetwork IPAM driver
* Support both IPv4 and IPv6
* Support for Linux Bridge, Open vSwitch, Midonet, and IOvisor port bindings
* Support for using existing Neutron networks.
* Support for using existing Neutron ports.
* Support for the Docker "expose" option.

View File

@ -0,0 +1,14 @@
===================================
Kuryr-libnetwork Installation Guide
===================================
.. toctree::
get_started.rst
controller-install.rst
compute-install.rst
verify.rst
next-steps.rst
This chapter assumes a working setup of OpenStack following the
`OpenStack Installation Tutorial <https://docs.openstack.org/install-guide/>`_.

View File

@ -0,0 +1,12 @@
.. _next-steps:
Next steps
~~~~~~~~~~
Your kuryr-libnetwork is now running.
To add more services, see the
`additional documentation on installing OpenStack <http://docs.openstack.org/#install-guides>`_ .
To learn more about the kuryr-libnetwork, read the `Kuryr-libnetwork documentation
<https://docs.openstack.org/kuryr-libnetwork/latest/>`__.

View File

@ -0,0 +1,34 @@
.. _verify:
Verify operation
~~~~~~~~~~~~~~~~
Verify operation of the kuryr-libnetwork.
#. Create a IPv4 network:
.. code-block:: console
# docker network create --driver kuryr --ipam-driver kuryr \
--subnet 10.10.0.0/16 --gateway=10.10.0.1 test_net
785f8c1b5ae480c4ebcb54c1c48ab875754e4680d915b270279e4f6a1aa52283
# docker network ls
NETWORK ID NAME DRIVER SCOPE
...
e13c98aa096b test_net kuryr local
# docker run --net test_net cirros ifconfig
eth0 Link encap:Ethernet HWaddr FA:16:3E:D5:BB:5F
inet addr:10.10.0.9 Bcast:0.0.0.0 Mask:255.255.0.0
UP BROADCAST RUNNING MULTICAST MTU:1450 Metric:1
RX packets:9 errors:0 dropped:0 overruns:0 frame:0
TX packets:2 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:894 (894.0 B) TX bytes:188 (188.0 B)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)