diff --git a/doc/source/install/compute-install-ubuntu.rst b/doc/source/install/compute-install-ubuntu.rst new file mode 100644 index 000000000..eaad8a431 --- /dev/null +++ b/doc/source/install/compute-install-ubuntu.rst @@ -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 +`_ +for Docker installation and `Kuryr libnetwork installation guide +`_ + +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 diff --git a/doc/source/install/compute-install.rst b/doc/source/install/compute-install.rst new file mode 100644 index 000000000..d457df3a3 --- /dev/null +++ b/doc/source/install/compute-install.rst @@ -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 diff --git a/doc/source/install/controller-install-ubuntu.rst b/doc/source/install/controller-install-ubuntu.rst new file mode 100644 index 000000000..56e315309 --- /dev/null +++ b/doc/source/install/controller-install-ubuntu.rst @@ -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 diff --git a/doc/source/install/controller-install.rst b/doc/source/install/controller-install.rst new file mode 100644 index 000000000..17c2d5083 --- /dev/null +++ b/doc/source/install/controller-install.rst @@ -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 diff --git a/doc/source/install/get_started.rst b/doc/source/install/get_started.rst new file mode 100644 index 000000000..ff48d1a0f --- /dev/null +++ b/doc/source/install/get_started.rst @@ -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/ diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 119bb1943..167681acd 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -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 `_. diff --git a/doc/source/install/launch-container.rst b/doc/source/install/launch-container.rst new file mode 100644 index 000000000..5022f23db --- /dev/null +++ b/doc/source/install/launch-container.rst @@ -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 diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst new file mode 100644 index 000000000..8027b35a8 --- /dev/null +++ b/doc/source/install/next-steps.rst @@ -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 `_ . + +To learn more about the zun service, read the `Zun developer documentation +`__. diff --git a/doc/source/install/overview.rst b/doc/source/install/overview.rst new file mode 100644 index 000000000..935e16234 --- /dev/null +++ b/doc/source/install/overview.rst @@ -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. diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst new file mode 100644 index 000000000..3c273cf2a --- /dev/null +++ b/doc/source/install/verify.rst @@ -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 | + +----+-----------------------+-------------+-------+----------+-----------------+---------------------------+---------------------------+