Introduction

Our Private Cloud Core deployments provide workload orchestration through the use of Kolla Ansible which deploys OpenStack services and infrastructure components in Docker containers. Should you want to make a change to an OpenStack service’s configuration, add a new OpenStack service, or even repair your OpenStack cluster, you can do so using Kolla Ansible. In this guide, we explain how to prepare a Kolla Ansible environment, from which configuration changes can be made.

Prerequisites

Before following this guide, you should generally be comfortable with using Ansible.

Using Kolla Ansible Quick Start

To get an idea of what is required, here is a high-level overview of the steps:

# Copy Kolla Ansible configuration from fm-deploy docker container
$ docker cp fm-deploy:/opt/kolla-ansible /opt/kolla-ansible

# Navigate to /opt/kolla-ansible
$ cd /opt/kolla-ansible

# Initialize a Python virtual environment
$ virtualenv .venv

# Activate the virtual environment
$ source .venv/bin/activate

# Update pip
pip install --upgrade pip

# Install Kolla Ansible using requirements.txt
$ pip install -r requirements.txt

Once prepared, make the needed changes and perform the Kolla Ansible run where <subcommand> is one in the list of available Kolla Ansible commands:

$ kolla-ansible -i /etc/fm-deploy/kolla-ansible-inventory <subcommand>

These steps are explained in more detail below.

Prepare Kolla Ansible for Use

To start using Kolla Ansible, an environment needs to be created. This section explains the steps needed to create that environment.

Warning! — Making changes using Kolla Ansible can potentially cause degradation of services or the cloud to be inoperable. Be careful!

In this section we explain how to prepare Kolla Ansible for use.

Relevant files

These files are used when preparing Kolla Ansible.

  • Globals file: /etc/kolla/globals.yml
  • Inventory file: /etc/fm-deploy/kolla-ansible-inventory

Note! — The above files may not be present on each host. Inspect each host until you find the above, and perform the Kolla Ansible run from this host.

Before Making Changes

Before any changes are made to the Kolla Ansible configuration, the following variables in /etc/kolla/globals.yml should not be modified, otherwise they will be overwritten:

api_interface
cluster_interface
dns_interface
docker_registry_insecure
kolla_enable_tls_external
kolla_external_fqdn
kolla_external_vip_address
kolla_internal_vip_address
migration_interface
network_interface
neutron_external_interface
openstack_region_name
storage_interface
tunnel_interface

Prepare Kolla Ansible Environment

Step 1 – Prepare environment

From the Docker container called fm-deploy, copy /opt/kolla-ansible to the local file system:

$ docker cp fm-deploy:/opt/kolla-ansible /opt/kolla-ansible

 

Step 2 — Prepare Python virtual environment

Create a Python virtual environment from which Kolla Ansible will be used:

$ cd /opt/kolla-ansible
$ virtualenv .venv
$ source .venv/bin/activate

 

Step 3 — Update pip

If pip is not up to date, packages may not install.

Pip can be updated using:

pip install --upgrade pip

 

Step 4 — Install Kolla Ansible using requirements.txt

A requirements.txt file is used to install Kolla Ansible. The release of OpenStack your cloud is running will determine the version of Kolla Ansible to install. This means you need to inspect requirements.txt and ensure the right version of Kolla Ansible is installed.

At the time of writing this guide, the OpenStack release used in Private Cloud Core is Victoria.

To determine the release your cloud is using, as root from a hardware node, run docker ps to get a list of all Docker containers running. In that output is shown each OpenStack service’s image, appended with the OpenStack version.

For example:

$ docker ps
cf9e23cef540   harbor.imhadmin.net/kolla/centos-binary-mariadb-clustercheck:victoria        "dumb-init --single-…"   8 days ago    Up 8 days                                 mariadb_clustercheck
c19964a28b4e   harbor.imhadmin.net/kolla/centos-binary-mariadb-server:victoria              "dumb-init -- kolla_…"   8 days ago    Up 8 days                                 mariadb

In this output, the second column represents a Kolla Ansible image and there are two entries. The output has been truncated and you should see many more Docker containers running than two. At the end of the image name the version of OpenStack for which that image is built can be seen following the colon:

harbor.imhadmin.net/kolla/centos-binary-mariadb-clustercheck:victoria

The above indicates this OpenStack cloud is on the Victoria release.

Next, in a text editor load requirements.txt and uncomment the appropriate version for Kolla Ansible.

The contents of this file appears this way:

ansible>=2.9,<2.10,!=2.9.10

# Use one of the following supported OpenStack versions:
#git+https://github.com/openstack/kolla-ansible@stable/train
#git+https://github.com/openstack/kolla-ansible@stable/ussuri
#git+https://github.com/openstack/kolla-ansible@stable/victoria

For the purpose of this demonstration, the OpenStack release is Victoria, so the #git+https://github.com/openstack/kolla-ansible@stable/victoria line within this file needs to be uncommented, or, in other words, remove the prepended #.

The file should now appear this way:

ansible>=2.9,<2.10,!=2.9.10

# Use one of the following supported OpenStack versions:
#git+https://github.com/openstack/kolla-ansible@stable/train
#git+https://github.com/openstack/kolla-ansible@stable/ussuri
git+https://github.com/openstack/kolla-ansible@stable/victoria

Now, requirements.txt is prepared and can be used to install Kolla Ansible:

(.venv) $ pip install -r requirements.txt

 

Step 5 — Make needed configuration changes

This step is where you make the needed configuration change. Configuration changes are made within the file /etc/kolla/globals.yml.

Warning! — What you change is up to you, however know that some of the values in this file should not be changed. See Before Making Changes for more information.

An example configuration change made at this step is to enable TLS for Horizon. Enabling TLS falls outside the scope of this guide and for instruction on how to do so, see How to Enable TLS for OpenStack.

 

Step 6 — Perform the Kolla Ansible action

At this step, you have everything prepared in order to use Kolla Ansible. Before proceeding, familiarize yourself with the available Kolla Ansible commands by running kolla-ansible --help and look for the Commands section.

For example:

$ kolla-ansible --help
[...previous output truncated...]
Commands:
    prechecks            Do pre-deployment checks for hosts
    check                Do post-deployment smoke tests
    mariadb_recovery     Recover a completely stopped mariadb cluster
    mariadb_backup       Take a backup of MariaDB databases
                             --full (default)
                             --incremental
    bootstrap-servers    Bootstrap servers with kolla deploy dependencies
    destroy              Destroy Kolla containers, volumes and host configuration
                             --include-images to also destroy Kolla images
                             --include-dev to also destroy dev mode repos
    deploy               Deploy and start all kolla containers
    deploy-bifrost       Deploy and start bifrost container
    deploy-servers       Enroll and deploy servers with bifrost
    deploy-containers    Only deploy and start containers (no config updates or bootstrapping)
    post-deploy          Do post deploy on deploy node
    pull                 Pull all images for containers (only pulls, no running container changes)
    reconfigure          Reconfigure OpenStack service
    stop                 Stop Kolla containers
    certificates         Generate self-signed certificate for TLS *For Development Only*
    octavia-certificates Generate certificates for octavia deployment
    upgrade              Upgrades existing OpenStack Environment
    upgrade-bifrost      Upgrades an existing bifrost container
    genconfig            Generate configuration files for enabled OpenStack services
    prune-images         Prune orphaned Kolla images

For complete documentation regarding available Kolla Ansible commands, see Operating Kolla.

Note there are a number of commands to choose from. When making a configuration change in /etc/kolla/globals.yml, for that to apply, use the reconfigure command.

The base Kolla Ansible command takes this form:

kolla-ansible -i <path-to-inventory> <command>
  • <path-to-inventory> — This is /etc/fm-deploy/kolla-ansible-inventory
  • <command> — When making configuration changes, reconfigure will be used.

To reconfigure services using Kolla Ansible, use:

$ kolla-ansible -i /etc/fm-deploy/kolla-ansible-inventory reconfigure

Next Steps

This concludes the steps needed to have a base understanding of how to use Kolla Ansible.

The following guides go into detail about specific things you can configure using Kolla Ansible, such enabling TLS for Horizon or enabling Central Logging: