Install the Container Infrastructure Management service from source

updated: 2019-03-25 10:52

Install the Container Infrastructure Management service from source¶

Install and configure¶

This section describes how to install and configure the Container Infrastructure Management service, code-named magnum, on the controller node.

This section assumes that you already have a working OpenStack environment with at least the following components installed: Identity service, Image service, Compute service, Networking service, Block Storage service and Orchestration service. See OpenStack Install Guides.

To provide access to Docker Swarm or Kubernetes using the native clients (docker or kubectl respectively) magnum uses TLS certificates. To store the certificates, it is recommended to use the Key Manager service, code-named barbican, or you can save them in magnum’s database.

Optionally, you can install the following components:

Load Balancer as a Service (LBaaS v2) to create clusters with multiple masters
Bare Metal service to create baremetal clusters
Object Storage service to make private Docker registries available to users
Telemetry Data Collection service to periodically send magnum-related metrics

Important

Magnum creates clusters of compute instances on the Compute service (nova). These instances must have basic Internet connectivity and must be able to reach magnum’s API server. Make sure that the Compute and Network services are configured accordingly.

Prerequisites¶

Before you install and configure the Container Infrastructure Management service, 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:
```
$ mysql -u root -p
```
- Create the magnum database:
```
CREATE DATABASE magnum;
```
- Grant proper access to the magnum database:
```
GRANT ALL PRIVILEGES ON magnum.* TO 'magnum'@'controller' \
  IDENTIFIED BY 'MAGNUM_DBPASS';
GRANT ALL PRIVILEGES ON magnum.* TO 'magnum'@'%' \
  IDENTIFIED BY 'MAGNUM_DBPASS';
```
  Replace MAGNUM_DBPASS with a suitable password.
- Exit the database access client.
Source the admin credentials to gain access to admin-only CLI commands:
```
$ . admin-openrc
```

To create the service credentials, complete these steps:

Create the magnum user:

$ openstack user create --domain default \
  --password-prompt magnum
User Password:
Repeat User Password:
+-----------+----------------------------------+
| Field     | Value                            |
+-----------+----------------------------------+
| domain_id | default                          |
| enabled   | True                             |
| id        | a8ebafc275c54d389dfc1bff8b4fe286 |
| name      | magnum                           |
+-----------+----------------------------------+

Add the admin role to the magnum user:
```
$ openstack role add --project service --user magnum admin
```
Note

This command provides no output.

Create the magnum service entity:

$ openstack service create --name magnum \
  --description "OpenStack Container Infrastructure Management Service" \
  container-infra
+-------------+-------------------------------------------------------+
| Field       | Value                                                 |
+-------------+-------------------------------------------------------+
| description | OpenStack Container Infrastructure Management Service |
| enabled     | True                                                  |
| id          | 194faf83e8fd4e028e5ff75d3d8d0df2                      |
| name        | magnum                                                |
| type        | container-infra                                       |
+-------------+-------------------------------------------------------+

Create the Container Infrastructure Management service API endpoints:

$ openstack endpoint create --region RegionOne \
  container-infra public http://CONTROLLER_IP:9511/v1
+--------------+----------------------------------+
| Field        | Value                            |
+--------------+----------------------------------+
| enabled      | True                             |
| id           | cb137e6366ad495bb521cfe92d8b8858 |
| interface    | public                           |
| region       | RegionOne                        |
| region_id    | RegionOne                        |
| service_id   | 0f7f62a1f1a247d2a4cb237642814d0e |
| service_name | magnum                           |
| service_type | container-infra                  |
| url          | http://CONTROLLER_IP:9511/v1     |
+--------------+----------------------------------+

$ openstack endpoint create --region RegionOne \
  container-infra internal http://CONTROLLER_IP:9511/v1
+--------------+----------------------------------+
| Field        | Value                            |
+--------------+----------------------------------+
| enabled      | True                             |
| id           | 17cbc3b6f51449a0a818118d6d62868d |
| interface    | internal                         |
| region       | RegionOne                        |
| region_id    | RegionOne                        |
| service_id   | 0f7f62a1f1a247d2a4cb237642814d0e |
| service_name | magnum                           |
| service_type | container-infra                  |
| url          | http://CONTROLLER_IP:9511/v1     |
+--------------+----------------------------------+

$ openstack endpoint create --region RegionOne \
  container-infra admin http://CONTROLLER_IP:9511/v1
+--------------+----------------------------------+
| Field        | Value                            |
+--------------+----------------------------------+
| enabled      | True                             |
| id           | 30f8888e6b6646d7b5cd14354c95a684 |
| interface    | admin                            |
| region       | RegionOne                        |
| region_id    | RegionOne                        |
| service_id   | 0f7f62a1f1a247d2a4cb237642814d0e |
| service_name | magnum                           |
| service_type | container-infra                  |
| url          | http://CONTROLLER_IP:9511/v1     |
+--------------+----------------------------------+

Replace CONTROLLER_IP with the IP magnum listens to. Alternatively, you can use a hostname which is reachable by the Compute instances.

Magnum requires additional information in the Identity service to manage clusters. To add this information, complete these steps:

Create the magnum domain that contains projects and users:

$ openstack domain create --description "Owns users and projects \
  created by magnum" magnum
  +-------------+-------------------------------------------+
  | Field       | Value                                     |
  +-------------+-------------------------------------------+
  | description | Owns users and projects created by magnum |
  | enabled     | True                                      |
  | id          | 66e0469de9c04eda9bc368e001676d20          |
  | name        | magnum                                    |
  +-------------+-------------------------------------------+

Create the magnum_domain_admin user to manage projects and users in the magnum domain:

$ openstack user create --domain magnum --password-prompt \
  magnum_domain_admin
  User Password:
  Repeat User Password:
  +-----------+----------------------------------+
  | Field     | Value                            |
  +-----------+----------------------------------+
  | domain_id | 66e0469de9c04eda9bc368e001676d20 |
  | enabled   | True                             |
  | id        | 529b81cf35094beb9784c6d06c090c2b |
  | name      | magnum_domain_admin              |
  +-----------+----------------------------------+

Add the admin role to the magnum_domain_admin user in the magnum domain to enable administrative management privileges by the magnum_domain_admin user:
```
$ openstack role add --domain magnum --user-domain magnum \
  --user magnum_domain_admin admin
```
Note

This command provides no output.

Install and configure components¶

Install OS-specific prerequisites:

Ubuntu 14.04 (trusty) or higher, Debian 8:

# apt-get update
# apt-get install python-dev libssl-dev libxml2-dev \
                  libmysqlclient-dev libxslt-dev libpq-dev git \
                  libffi-dev gettext build-essential

Fedora 21 / Centos 7 / RHEL 7

# yum install python-devel openssl-devel mysql-devel \
              libxml2-devel libxslt-devel postgresql-devel git \
              libffi-devel gettext gcc

Fedora 22 or higher

# dnf install python-devel openssl-devel mysql-devel \
              libxml2-devel libxslt-devel postgresql-devel git \
              libffi-devel gettext gcc

openSUSE Leap 42.1

# zypper install git libffi-devel libmysqlclient-devel \
                 libopenssl-devel libxml2-devel libxslt-devel \
                 postgresql-devel python-devel gettext-runtime gcc

Create magnum user and necessary directories:

Create user:

# groupadd --system magnum
# useradd --home-dir "/var/lib/magnum" \
      --create-home \
      --system \
      --shell /bin/false \
      -g magnum \
      magnum

Create directories:

# mkdir -p /var/log/magnum
# mkdir -p /etc/magnum

Set ownership to directories:

# chown magnum:magnum /var/log/magnum
# chown magnum:magnum /var/lib/magnum
# chown magnum:magnum /etc/magnum

Install virtualenv and python prerequisites:

Install virtualenv and create one for magnum’s installation:

# easy_install -U virtualenv
# su -s /bin/sh -c "virtualenv /var/lib/magnum/env" magnum

Install python prerequisites:

# su -s /bin/sh -c "/var/lib/magnum/env/bin/pip install tox pymysql \
  python-memcached" magnum

Clone and install magnum:

# cd /var/lib/magnum
# git clone https://git.openstack.org/openstack/magnum.git
# chown -R magnum:magnum magnum
# cd magnum
# su -s /bin/sh -c "/var/lib/magnum/env/bin/pip install -r requirements.txt" magnum
# su -s /bin/sh -c "/var/lib/magnum/env/bin/python setup.py install" magnum

Copy policy.json and api-paste.ini:

# su -s /bin/sh -c "cp etc/magnum/policy.json /etc/magnum" magnum
# su -s /bin/sh -c "cp etc/magnum/api-paste.ini /etc/magnum" magnum

Generate a sample configuration file:

# su -s /bin/sh -c "/var/lib/magnum/env/bin/tox -e genconfig" magnum
# su -s /bin/sh -c "cp etc/magnum/magnum.conf.sample \
  /etc/magnum/magnum.conf" magnum

Edit the /etc/magnum/magnum.conf:
- In the [DEFAULT] section, configure RabbitMQ message queue access:
```
[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 host:
```
[api]
...
host = CONTROLLER_IP
```
  Replace CONTROLLER_IP with the IP address on which you wish magnum api should listen.
- In the [certificates] section, select barbican (or local if you don’t have barbican installed):
  - Use barbican to store certificates:
    [certificates] ... cert_manager_type = barbican
  Important
  
  Barbican is recommended for production environments, local store should be used for evaluation purposes.
  - To use local store for certificates, you have to create and specify the directory to use:
    # su -s /bin/sh -c "mkdir -p /var/lib/magnum/certificates/" magnum
    [certificates] ... cert_manager_type = local storage_path = /var/lib/magnum/certificates/
- In the [cinder_client] section, configure the region name:
```
[cinder_client]
...
region_name = RegionOne
```
- In the [database] section, configure database access:
```
[database]
...
connection = mysql+pymysql://magnum:MAGNUM_DBPASS@controller/magnum
```
  Replace MAGNUM_DBPASS with the password you chose for the magnum database.
- In the [keystone_authtoken] and trust sections, configure Identity service access:
```
[keystone_authtoken]
...
memcached_servers = controller:11211
auth_version = v3
auth_uri = http://controller:5000/v3
project_domain_name = default
project_name = service
user_domain_name = default
password = MAGNUM_PASS
username = magnum
auth_url = http://controller:35357
auth_type = password
admin_user = magnum
admin_password = MAGNUM_PASS
admin_tenant_name = service

[trust]
...
trustee_domain_name = magnum
trustee_domain_admin_name = magnum_domain_admin
trustee_domain_admin_password = DOMAIN_ADMIN_PASS
```
  trustee_domain_name is the name of the magnum domain and trustee_domain_admin_name is the name of the magnum_domain_admin user. Replace MAGNUM_PASS with the password you chose for the magnum user in the Identity service and DOMAIN_ADMIN_PASS with the password you chose for the magnum_domain_admin user.
- In the [oslo_concurrency] section, configure the lock_path:
```
[oslo_concurrency]
...
lock_path = /var/lib/magnum/tmp
```
- In the [oslo_messaging_notifications] section, configure the driver:
```
[oslo_messaging_notifications]
...
driver = messaging
```
Note

Make sure that /etc/magnum/magnum.conf still have the correct permissions. You can set the permissions again with:

# chown magnum:magnum /etc/magnum/magnum.conf

Populate Magnum database:

# su -s /bin/sh -c "/var/lib/magnum/env/bin/magnum-db-manage upgrade" magnum

Set magnum for log rotation:

# cd /var/lib/magnum/magnum
# cp doc/examples/etc/logrotate.d/magnum.logrotate /etc/logrotate.d/magnum

Finalize installation¶

Create init scripts and services:

Ubuntu 14.04 (trusty):

# cd /var/lib/magnum/magnum
# cp doc/examples/etc/init/magnum-api.conf \
  /etc/init/magnum-api.conf
# cp doc/examples/etc/init/magnum-conductor.conf \
  /etc/init/magnum-conductor.conf

Ubuntu 14.10 or higher, Fedora 21 or higher/RHEL 7/CentOS 7, openSUSE Leap 42.1 or Debian 8:

# cd /var/lib/magnum/magnum
# cp doc/examples/etc/systemd/system/magnum-api.service \
  /etc/systemd/system/magnum-api.service
# cp doc/examples/etc/systemd/system/magnum-conductor.service \
  /etc/systemd/system/magnum-conductor.service

Start magnum-api and magnum-conductor:

Ubuntu 14.04 (trusty):

# start magnum-api
# start magnum-conductor

Ubuntu 14.10 or higher, Fedora 21 or higher/RHEL 7/CentOS 7, openSUSE Leap 42.1 or Debian 8:

# systemctl enable magnum-api
# systemctl enable magnum-conductor

# systemctl start magnum-api
# systemctl start magnum-conductor

Verify that magnum-api and magnum-conductor services are running:
- Ubuntu 14.04 (trusty):
```
# status magnum-api
# status magnum-conductor
```
- Ubuntu 14.10 or higher, Fedora 21 or higher/RHEL 7/CentOS 7, openSUSE Leap 42.1 or Debian 8:
```
# systemctl status magnum-api
# systemctl status magnum-conductor
```

Install the command-line client¶

Install OS-specific prerequisites:

Fedora 21/RHEL 7/CentOS 7

# yum install python-devel openssl-devel python-virtualenv \
              libffi-devel git gcc

Fedora 22 or higher

# dnf install python-devel openssl-devel python-virtualenv \
              libffi-devel git gcc

Ubuntu/Debian

# apt-get update
# apt-get install python-dev libssl-dev python-virtualenv \
                  libffi-dev git gcc

openSUSE Leap 42.1

# zypper install python-devel libopenssl-devel python-virtualenv \
                 libffi-devel git gcc

Install the client in a virtual environment:

$ cd ~
$ git clone https://git.openstack.org/openstack/python-magnumclient.git
$ cd python-magnumclient
$ virtualenv .magnumclient-env
$ .magnumclient-env/bin/pip install -r requirements.txt
$ .magnumclient-env/bin/python setup.py install

Now, you can export the client in your PATH:
```
$ export PATH=$PATH:${PWD}/.magnumclient-env/bin/magnum
```
Note

The command-line client can be installed on the controller node or on a different host than the service. It is good practice to install it as a non-root user.

Next Steps¶

Since you have the Container Infrastructure Management service running, you can Verify Operation and Launch an instance.

updated: 2019-03-25 10:52

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.