openstack/zun
Code Issues Proposed changes

Add installation guide for Zun

Browse Source 
Depends-On: Id4f234068600564fa18e73aba08f6e43893456ee
Implements: blueprint zun-installation-guide
Change-Id: If987b7034c98eeee3c69f65d9e0b047d26ec0dc4
This commit is contained in:
Hongbin Lu 2017-09-15 18:56:48 -04:00 committed by Hongbin Lu
parent 5133328103
commit 3c462b9dd1
10 changed files with 751 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
doc/source/install/compute-install-ubuntu.rst Normal file
View File

@ -0,0 +1,173 @@
Install and configure a compute node for Ubuntu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Container service on a
compute node for Ubuntu 16.04 (LTS).
Prerequisites
-------------
Before you install and configure Zun, you must have Docker and
Kuryr-libnetwork installed properly in the compute node. Refer `Get Docker
<https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/>`_
for Docker installation and `Kuryr libnetwork installation guide
<https://docs.openstack.org/kuryr-libnetwork/latest/install>`_
Install and configure components
--------------------------------
#. Create zun user and necessary directories:
* Create user:
.. code-block:: console
# groupadd --system zun
# useradd --home-dir "/var/lib/zun" \
--create-home \
--system \
--shell /bin/false \
-g zun \
zun
* Create directories:
.. code-block:: console
# mkdir -p /etc/zun
# chown zun:zun /etc/zun
#. Clone and install zun:
.. code-block:: console
# cd /var/lib/zun
# git clone https://git.openstack.org/openstack/zun.git
# chown -R zun:zun zun
# cd zun
# pip install -r requirements.txt
# python setup.py install
#. Generate a sample configuration file:
.. code-block:: console
# su -s /bin/sh -c "oslo-config-generator \
--config-file etc/zun/zun-config-generator.conf" zun
# su -s /bin/sh -c "cp etc/zun/zun.conf.sample \
/etc/zun/zun.conf" zun
#. Edit the ``/etc/zun/zun.conf``:
* In the ``[DEFAULT]`` section,
configure ``RabbitMQ`` message queue access:
.. code-block:: ini
[DEFAULT]
...
transport_url = rabbit://openstack:RABBIT_PASS@controller
Replace ``RABBIT_PASS`` with the password you chose for the
``openstack`` account in ``RabbitMQ``.
* In the ``[database]`` section, configure database access:
.. code-block:: ini
[database]
...
connection = mysql+pymysql://zun:ZUN_DBPASS@controller/zun
Replace ``ZUN_DBPASS`` with the password you chose for
the zun database.
* In the ``[keystone_authtoken]`` section, configure
Identity service access:
.. code-block:: ini
[keystone_authtoken]
...
memcached_servers = controller:11211
auth_uri = http://controller:5000
project_domain_name = default
project_name = service
user_domain_name = default
password = ZUN_PASS
username = zun
auth_url = http://controller:35357
auth_type = password
Replace ZUN_PASS with the password you chose for the zun user in the
Identity service.
* In the ``[oslo_concurrency]`` section, configure the ``lock_path``:
.. code-block:: ini
[oslo_concurrency]
...
lock_path = /var/lib/zun/tmp
.. note::
Make sure that ``/etc/zun/zun.conf`` still have the correct
permissions. You can set the permissions again with:
# chown zun:zun /etc/zun/zun.conf
#. Configure Docker:
* Create the directory ``/etc/systemd/system/docker.service.d``
.. code-block:: console
# mkdir -p /etc/systemd/system/docker.service.d
* Create the file ``/etc/systemd/system/docker.service.d/docker.conf``.
Configure docker to listen to port 2375 as well as the the default
unix socket. Also, configure docker to use etcd3 as storage backend:
.. code-block:: ini
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd --group zun -H tcp://compute1:2375 -H unix:///var/run/docker.sock --cluster-store etcd://controller:2379
* Restart Docker:
.. code-block:: console
# systemctl daemon-reload
# systemctl restart docker
Finalize installation
---------------------
#. Create an upstart config, it could be named as
``/etc/systemd/system/zun-compute.service``:
.. code-block:: bash
[Unit]
Description = OpenStack Container Service Compute Agent
[Service]
ExecStart = /usr/local/bin/zun-compute
User = zun
[Install]
WantedBy = multi-user.target
#. Enable and start zun-compute:
.. code-block:: console
# systemctl enable zun-compute
# systemctl start zun-compute
#. Verify that zun-compute services are running:
.. code-block:: console
# systemctl status zun-compute

17
doc/source/install/compute-install.rst Normal file
View File

@ -0,0 +1,17 @@
Install and configure a compute node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Compute service on a
compute node.
.. note::
This section assumes that you are following the instructions in this guide
step-by-step to configure the first compute node. If you want to configure
additional compute nodes, prepare them in a similar fashion. Each additional
compute node requires a unique IP address.
.. toctree::
:glob:
compute-install-ubuntu.rst

345
doc/source/install/controller-install-ubuntu.rst Normal file
View File

@ -0,0 +1,345 @@
Install and configure controller node for Ubuntu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Container
service for Ubuntu 16.04 (LTS).
Prerequisites
-------------
Before you install and configure Zun, you must create a database,
service credentials, and API endpoints.
#. To create the database, complete these steps:
* Use the database access client to connect to the database
server as the ``root`` user:
.. code-block:: console
# mysql
* Create the ``zun`` database:
.. code-block:: console
MariaDB [(none)] CREATE DATABASE zun;
* Grant proper access to the ``zun`` database:
.. code-block:: console
MariaDB [(none)]> GRANT ALL PRIVILEGES ON zun.* TO 'zun'@'localhost' \
IDENTIFIED BY 'ZUN_DBPASS';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON zun.* TO 'zun'@'%' \
IDENTIFIED BY 'ZUN_DBPASS';
Replace ``ZUN_DBPASS`` with a suitable password.
* Exit the database access client.
#. 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 ``zun`` user:
.. code-block:: console
$ openstack user create --domain default --password-prompt zun
User Password:
Repeat User Password:
+-----------+----------------------------------+
| Field | Value |
+-----------+----------------------------------+
| domain_id | e0353a670a9e496da891347c589539e9 |
| enabled | True |
| id | ca2e175b851943349be29a328cc5e360 |
| name | zun |
+-----------+----------------------------------+
* Add the ``admin`` role to the ``zun`` user:
.. code-block:: console
$ openstack role add --project service --user zun admin
.. note::
This command provides no output.
* Create the ``zun`` service entities:
.. code-block:: console
$ openstack service create --name zun \
--description "Container Service" container
+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | Container Service |
| enabled | True |
| id | 727841c6f5df4773baa4e8a5ae7d72eb |
| name | zun |
| type | container |
+-------------+----------------------------------+
#. Create the Container service API endpoints:
.. code-block:: console
$ openstack endpoint create --region RegionOne \
container public http://controller:9517/v1
+--------------+-----------------------------------------+
| Field | Value |
+--------------+-----------------------------------------+
| enabled | True |
| id | 3f4dab34624e4be7b000265f25049609 |
| interface | public |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 727841c6f5df4773baa4e8a5ae7d72eb |
| service_name | zun |
| service_type | container |
| url | http://controller:9517/v1 |
+--------------+-----------------------------------------+
$ openstack endpoint create --region RegionOne \
container internal http://controller:9517/v1
+--------------+-----------------------------------------+
| Field | Value |
+--------------+-----------------------------------------+
| enabled | True |
| id | 9489f78e958e45cc85570fec7e836d98 |
| interface | internal |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 727841c6f5df4773baa4e8a5ae7d72eb |
| service_name | zun |
| service_type | container |
| url | http://controller:9517/v1 |
+--------------+-----------------------------------------+
$ openstack endpoint create --region RegionOne \
container admin http://controller:9517/v1
+--------------+-----------------------------------------+
| Field | Value |
+--------------+-----------------------------------------+
| enabled | True |
| id | 76091559514b40c6b7b38dde790efe99 |
| interface | admin |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 727841c6f5df4773baa4e8a5ae7d72eb |
| service_name | zun |
| service_type | container |
| url | http://controller:9517/v1 |
+--------------+-----------------------------------------+
Install and configure components
--------------------------------
#. Create zun user and necessary directories:
* Create user:
.. code-block:: console
# groupadd --system zun
# useradd --home-dir "/var/lib/zun" \
--create-home \
--system \
--shell /bin/false \
-g zun \
zun
* Create directories:
.. code-block:: console
# mkdir -p /etc/zun
# chown zun:zun /etc/zun
#. Clone and install zun:
.. code-block:: console
# apt-get install python-pip
# cd /var/lib/zun
# git clone https://git.openstack.org/openstack/zun.git
# chown -R zun:zun zun
# cd zun
# pip install -r requirements.txt
# python setup.py install
#. Generate a sample configuration file:
.. code-block:: console
# su -s /bin/sh -c "oslo-config-generator \
--config-file etc/zun/zun-config-generator.conf" zun
# su -s /bin/sh -c "cp etc/zun/zun.conf.sample \
/etc/zun/zun.conf" zun
#. Copy api-paste.ini:
.. code-block:: console
# su -s /bin/sh -c "cp etc/zun/api-paste.ini /etc/zun" zun
#. Edit the ``/etc/zun/zun.conf``:
* In the ``[DEFAULT]`` section,
configure ``RabbitMQ`` message queue access:
.. code-block:: ini
[DEFAULT]
...
transport_url = rabbit://openstack:RABBIT_PASS@controller
Replace ``RABBIT_PASS`` with the password you chose for the
``openstack`` account in ``RabbitMQ``.
* In the ``[api]`` section, configure the IP address that Zun API
server is going to listen:
.. code-block:: ini
[api]
...
host_ip = 10.0.0.11
port = 9517
Replace ``10.0.0.11`` with the management interface IP address
of the controller node if different.
* In the ``[database]`` section, configure database access:
.. code-block:: ini
[database]
...
connection = mysql+pymysql://zun:ZUN_DBPASS@controller/zun
Replace ``ZUN_DBPASS`` with the password you chose for
the zun database.
* In the ``[keystone_authtoken]`` section, configure
Identity service access:
.. code-block:: ini
[keystone_authtoken]
...
memcached_servers = controller:11211
auth_uri = http://controller:5000
project_domain_name = default
project_name = service
user_domain_name = default
password = ZUN_PASS
username = zun
auth_url = http://controller:35357
auth_type = password
Replace ZUN_PASS with the password you chose for the zun user in the
Identity service.
* In the ``[oslo_concurrency]`` section, configure the ``lock_path``:
.. code-block:: ini
[oslo_concurrency]
...
lock_path = /var/lib/zun/tmp
* In the ``[oslo_messaging_notifications]`` section, configure the
``driver``:
.. code-block:: ini
[oslo_messaging_notifications]
...
driver = messaging
* In the ``[websocket_proxy]`` section, configure the IP address that
the websocket proxy is going to listen to:
.. code-block:: ini
[websocket_proxy]
...
wsproxy_host = 10.0.0.11
Replace ``10.0.0.11`` with the management interface IP address
of the controller node if different.
.. note::
Make sure that ``/etc/zun/zun.conf`` still have the correct
permissions. You can set the permissions again with:
# chown zun:zun /etc/zun/zun.conf
#. Populate Zun database:
.. code-block:: console
# su -s /bin/sh -c "zun-db-manage upgrade" zun
Finalize installation
---------------------
#. Create an upstart config, it could be named as
``/etc/systemd/system/zun-api.service``:
.. code-block:: bash
[Unit]
Description = OpenStack Container Service API
[Service]
ExecStart = /usr/local/bin/zun-api
User = zun
[Install]
WantedBy = multi-user.target
#. Create an upstart config, it could be named as
``/etc/systemd/system/zun-wsproxy.service``:
.. code-block:: bash
[Unit]
Description = OpenStack Container Service Websocket Proxy
[Service]
ExecStart = /usr/local/bin/zun-wsproxy
User = zun
[Install]
WantedBy = multi-user.target
#. Enable and start zun-api and zun-wsproxy:
.. code-block:: console
# systemctl enable zun-api
# systemctl enable zun-wsproxy
.. code-block:: console
# systemctl start zun-api
# systemctl start zun-wsproxy
#. Verify that zun-api and zun-wsproxy services are running:
.. code-block:: console
# systemctl status zun-api
# systemctl status zun-wsproxy

9
doc/source/install/controller-install.rst Normal file
View File

@ -0,0 +1,9 @@
Install and configure controller node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Container service
on the controller node.
.. toctree::
controller-install-ubuntu.rst

30
doc/source/install/get_started.rst Normal file
View File

@ -0,0 +1,30 @@
==========================
Container service overview
==========================
The Container service consists of the following components:
``zun-api``
An OpenStack-native REST API that processes API requests by sending
them to the ``zun-compute`` over Remote Procedure Call (RPC).
``zun-compute``
A worker daemon that creates and terminates containers through Docker API
Manage containers and compute resources in local host.
``zun-wsproxy``
Provides a proxy for accessing running containers through a websocket
connection.
Optionally, one may wish to utilize the following associated projects for
additional functionality:
python-zunclient_
A command-line interface (CLI) and python bindings for interacting with the
Container service.
zun-ui_
The Horizon plugin for providing Web UI for Zun.
.. _python-zunclient: https://docs.openstack.org/python-zunclient/latest/
.. _zun-ui: https://docs.openstack.org/zun-ui/latest/

14
doc/source/install/index.rst
View File

@ -2,5 +2,15 @@
Zun Installation Guide
======================
TODO: There is currently no installation guide for Zun. The work will be
tracked here: https://blueprints.launchpad.net/zun/+spec/zun-installation-guide
.. toctree::
overview.rst
get_started.rst
controller-install.rst
compute-install.rst
verify.rst
launch-container.rst
next-steps.rst
This chapter assumes a working setup of OpenStack following the
`OpenStack Installation Tutorial <https://docs.openstack.org/install-guide/>`_.

69
doc/source/install/launch-container.rst Normal file
View File

@ -0,0 +1,69 @@
.. _launch-container:
Launch a container
~~~~~~~~~~~~~~~~~~
In environments that include the Container service, you can launch a
container.
#. Source the ``demo`` credentials to perform
the following steps as a non-administrative project:
.. code-block:: console
$ . demo-openrc
#. Determine available networks.
.. code-block:: console
$ openstack network list
+--------------------------------------+-------------+--------------------------------------+
| ID | Name | Subnets |
+--------------------------------------+-------------+--------------------------------------+
| 4716ddfe-6e60-40e7-b2a8-42e57bf3c31c | selfservice | 2112d5eb-f9d6-45fd-906e-7cabd38b7c7c |
| b5b6993c-ddf9-40e7-91d0-86806a42edb8 | provider | 310911f6-acf0-4a47-824e-3032916582ff |
+--------------------------------------+-------------+--------------------------------------+
.. note::
This output may differ from your environment.
#. Set the ``NET_ID`` environment variable to reflect the ID of a network.
For example, using the selfservice network:
.. code-block:: console
$ export NET_ID=$(openstack network list | awk '/ selfservice / { print $2 }')
#. Run a CirrOS container on the selfservice network:
.. code-block:: console
$ openstack appcontainer run --name container --net network=$NET_ID cirros ping 8.8.8.8
#. After a short time, verify successful creation of the container:
.. code-block:: console
$ openstack appcontainer list
+--------------------------------------+-----------+--------+---------+------------+-------------------------------------------------+-------+
| uuid | name | image | status | task_state | addresses | ports |
+--------------------------------------+-----------+--------+---------+------------+-------------------------------------------------+-------+
| 4ec10d48-1ed8-492a-be5a-402be0abc66a | container | cirros | Running | None | 10.0.0.11, fd13:fd51:ebe8:0:f816:3eff:fe9c:7612 | [] |
+--------------------------------------+-----------+--------+---------+------------+-------------------------------------------------+-------+
#. Access the container and verify access to the internet:
.. code-block:: console
$ openstack appcontainer exec --interactive container /bin/sh
# ping -c 4 openstack.org
# exit
#. Stop and delete the container.
.. code-block:: console
$ openstack appcontainer stop container
$ openstack appcontainer delete container

12
doc/source/install/next-steps.rst Normal file
View File

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

50
doc/source/install/overview.rst Normal file
View File

@ -0,0 +1,50 @@
========
Overview
========
The Container service provides OpenStack-native API for launching and managing
application containers without any virtual machine managements.
Also known as the ``zun`` project, the OpenStack Container service may,
depending upon configuration, interact with several other OpenStack services.
This includes:
- The OpenStack Identity service (``keystone``) for request authentication and
to locate other OpenStack services
- The OpenStack Networking service (``neutron``) for DHCP and network
configuration
- The OpenStack Block Storage (``cinder``) provides volumes for container
(optional).
- The OpenStack Image service (``glance``) from which to retrieve conainer
images (optional).
- The OpenStack Dashboard service (``horizon``) for providing the web UI
(optional).
- The OpenStack Orchestration service (``heat``) for providing orchestration
between containers and other OpenStack resources (optional).
Zun requires at least two nodes (Controller node and Compute node) to run
a container. Optional services such as Block Storage require additional nodes.
Controller
----------
The controller node runs the Identity service, Image service, management
portions of Zun, management portion of Networking, various Networking
agents, and the Dashboard. It also includes supporting services such as an SQL
database, message queue, and Network Time Protocol (NTP).
Optionally, the controller node runs portions of the Block Storage, Object
Storage, and Orchestration services.
The controller node requires a minimum of two network interfaces.
Compute
-------
The compute node runs the engine portion of Zun that operates containers.
By default, Zun uses Docker as container engine. The compute node also runs
a Networking service agent that connects containers to virtual networks and
provides firewalling services to instances via security groups.
You can deploy more than one compute node. Each node requires a minimum of two
network interfaces.

34
doc/source/install/verify.rst Normal file
View File

@ -0,0 +1,34 @@
.. _verify:
Verify operation
~~~~~~~~~~~~~~~~
Verify operation of the Container service.
.. note::
Perform these commands on the controller node.
#. Install python-zunclient:
.. code-block:: console
# pip install python-zunclient
#. Source the ``admin`` tenant credentials:
.. code-block:: console
$ . admin-openrc
#. List service components to verify successful launch and
registration of each process:
.. code-block:: console
$ openstack appcontainer service list
+----+-----------------------+-------------+-------+----------+-----------------+---------------------------+---------------------------+
| Id | Host | Binary | State | Disabled | Disabled Reason | Created At | Updated At |
+----+-----------------------+-------------+-------+----------+-----------------+---------------------------+---------------------------+
| 1 | localhost.localdomain | zun-compute | up | False | None | 2017-09-13 14:15:40+00:00 | 2017-09-16 22:28:47+00:00 |
+----+-----------------------+-------------+-------+----------+-----------------+---------------------------+---------------------------+