From d0cec045cab34ec3882038fbe45c0b3b44f61564 Mon Sep 17 00:00:00 2001 From: Hongbin Lu Date: Wed, 4 Oct 2017 21:59:22 +0000 Subject: [PATCH] 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 --- doc/source/index.rst | 7 ++ doc/source/install/compute-install-ubuntu.rst | 116 ++++++++++++++++++ doc/source/install/compute-install.rst | 19 +++ doc/source/install/controller-install.rst | 41 +++++++ doc/source/install/get_started.rst | 24 ++++ doc/source/install/index.rst | 14 +++ doc/source/install/next-steps.rst | 12 ++ doc/source/install/verify.rst | 34 +++++ 8 files changed, 267 insertions(+) create mode 100644 doc/source/install/compute-install-ubuntu.rst create mode 100644 doc/source/install/compute-install.rst create mode 100644 doc/source/install/controller-install.rst create mode 100644 doc/source/install/get_started.rst create mode 100644 doc/source/install/index.rst create mode 100644 doc/source/install/next-steps.rst create mode 100644 doc/source/install/verify.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index ca6e279f..f58e8211 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -21,6 +21,13 @@ Design and Developer Docs devref/index +Installation Guide +================== +.. toctree:: + :maxdepth: 1 + + install/index + Indices and tables ================== diff --git a/doc/source/install/compute-install-ubuntu.rst b/doc/source/install/compute-install-ubuntu.rst new file mode 100644 index 00000000..2c00847c --- /dev/null +++ b/doc/source/install/compute-install-ubuntu.rst @@ -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 +`_ +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 diff --git a/doc/source/install/compute-install.rst b/doc/source/install/compute-install.rst new file mode 100644 index 00000000..6df2d6c7 --- /dev/null +++ b/doc/source/install/compute-install.rst @@ -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 diff --git a/doc/source/install/controller-install.rst b/doc/source/install/controller-install.rst new file mode 100644 index 00000000..b313099c --- /dev/null +++ b/doc/source/install/controller-install.rst @@ -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 diff --git a/doc/source/install/get_started.rst b/doc/source/install/get_started.rst new file mode 100644 index 00000000..869601ec --- /dev/null +++ b/doc/source/install/get_started.rst @@ -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. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..3fd83827 --- /dev/null +++ b/doc/source/install/index.rst @@ -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 `_. diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst new file mode 100644 index 00000000..d6ca0eac --- /dev/null +++ b/doc/source/install/next-steps.rst @@ -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 `_ . + +To learn more about the kuryr-libnetwork, read the `Kuryr-libnetwork documentation +`__. diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst new file mode 100644 index 00000000..1af01ae6 --- /dev/null +++ b/doc/source/install/verify.rst @@ -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)