Containers based Undercloud Deployment


The TripleO containers support is still under heavy development. Things documented here may change during the Pike cycle.

This documentation explains how to deploy a fully containerized undercloud on Docker. This feature is supported starting with Pike.

The requirements for a containerized undercloud are the same as for any other undercloud deployment. The real difference is in where the undercloud services will be deployed (containers vs base OS).


The docker based undercloud architecture is not very different from the baremetal/VM based one. The services deployed in the traditional baremetal undercloud are also deployed in the docker based one.

One obvious difference between these 2 types of deployments is that the openstack services are deployed as containers in a container runtime rather than in the host operating system. This reduces the required packages in the host to the bare minimum for running the container runtime and managing the base network layer.

Manual undercloud deployment

This section explains how to deploy a containerized undercloud manually. For an automated undercloud deployment, please follow the steps in the Using TripleO Quickstart section below.

Preparing the environment

Prepare a host (either baremetal or VM) following the normal undercloud provisioning steps and stop right before the undercloud install command. This should leave you with an updated base operating system with no openstack packages installed.

Make sure these packages are installed before proceeding with the undercloud installation:

  • python-tripleoclient >= Pike
  • python-openstackclient >= Pike
  • openstack-heat-agents >= Pike
  • docker >= 1.12.5
  • openvswitch (minimum version supported by neutron)

Verify that your docker environment is up and that your user can use sudo:

$ sudo docker ps -a


Check the Debugging container failures section for more tips and tricks for debugging containers.

The above should show no containers running. If it shows running containers, please refer to the Cleaning up section below.

Configuring the undercloud

The containers based undercloud uses the same heat templates that are used for an overcloud deployment. Therefore, controlling the undercloud configuration can be done by modifying the existing environment files or creating new ones.

A basic custom.yaml file would look like this:

  NeutronServicePlugins: ""

The above configuration file overwrites the default nameserver and sets the service plugins for neutron. If your undercloud node has a single nic and you don’t want to create a new one, it’s possible to set the network configuration to noop by changing the custom.yaml file to (substitute $THT_ROOT with the right path):

  OS::TripleO::Undercloud::Net::SoftwareConfig: $THT_ROOT/net-config-noop.yaml

  NeutronServicePlugins: ""

Deploying the undercloud

The following command will install an undercloud with ironic, mistral and zaqar (substitute $THT_ROOT with the right path):

$ sudo openstack undercloud deploy \
  --templates=$THT_ROOT \
  --local-ip=$YOUR_SERVER_IP \
  --keep-running \
  -e $THT_ROOT/environments/services-docker/ironic.yaml \
  -e $THT_ROOT/environments/services-docker/mistral.yaml \
  -e $THT_ROOT/environments/services-docker/zaqar.yaml \
  -e $THT_ROOT/environments/docker.yaml \
  -e $THT_ROOT/environments/mongodb-nojournal.yaml \
  -e $HOME/custom.yaml

The keep-running flag will keep the openstack undercloud deploy process running on failures, which allows for debugging the current execution. A minimal stackrc file will be required to query both, the keystone and the heat, APIs:

export OS_NO_CACHE=True
export OS_CLOUDNAME=overcloud
export OS_AUTH_URL=
export NOVA_VERSION=1.1
export OS_USERNAME=foo
export OS_PROJECT_NAME=foo
export OS_PASSWORD=bar

Cleaning up

The following commands will help cleaning up your undercloud environment to start the deployment from scratch:

To stop and remove all running containers:

$ sudo docker ps -qa --filter label=managed_by=docker-cmd | xargs sudo docker rm -f

To remove the existing named volumes (bear in mind this will remove your database files too):

$ sudo docker volume rm $(sudo docker volume ls -q)

Configuration files are generated and overwritten on every run. However, you can also remove them by running:

$ sudo rm -Rf /var/lib/docker-puppet
$ sudo rm -Rf /var/lib/config-data
$ sudo rm -Rf /var/lib/kolla

Using TripleO Quickstart


How does the undercloud deploy work?

The undercloud deploy command as written in the Deploying the undercloud section will run all the OpenStack services in a container runtime (docker) unless the default settings are overwritten.

This command requires 2 services to be running at all times. The first one is a basic keystone service, which is currently mocked by tripleclient itself, the second one is heat-all which executes the templates and installs the services. The latter can be run on baremetal or in a container (tripleoclient will run it in a container by default).

Checkout the TripleO Containers Architecture for more detailed info on how TripleO builds, creates and runs containers.