Undercloud Installation

This section contains instructions on how to install the undercloud and how to update components after installation.

Installing the Undercloud

  1. Log in to your machine (baremetal or VM) where you want to install the undercloud as a non-root user (such as the stack user):

    ssh <non-root-user>@<undercloud-machine>
    

    Note

    If you don’t have a non-root user created yet, log in as root and create one with following commands:

    sudo useradd stack
    sudo passwd stack  # specify a password
    
    echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
    sudo chmod 0440 /etc/sudoers.d/stack
    
    su - stack
    

    Note

    The undercloud is intended to work correctly with SELinux enforcing, and cannot be installed to a system with SELinux disabled. If SELinux enforcement must be turned off for some reason, it should instead be set to permissive.

    Note

    vlan tagged interfaces must follow the if_name.vlan_id convention, like for example: eth0.vlan100 or bond0.vlan120.

    Baremetal

    Ensure that there is a FQDN hostname set and that the $HOSTNAME environment variable matches that value. The easiest way to do this is to set the undercloud_hostname option in undercloud.conf before running the install. This will allow the installer to configure all of the hostname- related settings appropriately.

    Alternatively the hostname settings can be configured manually, but this is strongly discouraged. The manual steps are as follows:

    sudo hostnamectl set-hostname myhost.mydomain
    sudo hostnamectl set-hostname --transient myhost.mydomain
    

    An entry for the system’s FQDN hostname is also needed in /etc/hosts. For example, if the system is named myhost.mydomain, /etc/hosts should have an entry like:

    127.0.0.1   myhost.mydomain myhost
    
  2. Enable needed repositories:

    RHEL

    Enable optional repo:

    sudo yum install -y yum-utils
    sudo yum-config-manager --enable rhelosp-rhel-7-server-opt
    

    Download and install the python2-tripleo-repos RPM from the current RDO repository. For example:

    sudo yum install -y https://trunk.rdoproject.org/centos7/current/python2-tripleo-repos-<version>.el7.centos.noarch.rpm
    

    Note

    tripleo-repos removes any repositories that it manages before each run. This means all repositories must be specified in a single tripleo-repos call. As an example, the correct way to install the current and ceph repos is to run tripleo-repos current ceph, not two separate calls.

    Stable Branch

    Enable the appropriate repos for the desired release, as indicated below. Do not enable any other repos not explicitly marked for that release.

    Newton

    Enable the current Newton repositories:

    sudo tripleo-repos -b newton current
    

    Ceph

    Include the Ceph repo in the tripleo-repos call:

    sudo tripleo-repos -b newton current ceph
    

    Ocata

    Enable the current Ocata repositories:

    sudo tripleo-repos -b ocata current
    

    Ceph

    Include the Ceph repo in the tripleo-repos call:

    sudo tripleo-repos -b ocata current ceph
    

    Pike

    Enable the current Pike repositories:

    sudo tripleo-repos -b pike current
    

    Ceph

    Include the Ceph repo in the tripleo-repos call:

    sudo tripleo-repos -b pike current ceph
    

    Warning

    The remaining repositories configuration steps below should not be done for stable releases!

    Run tripleo-repos to install the appropriate repositories. The option below will enable the latest master TripleO packages and the latest promoted packages for all other OpenStack services and dependencies. There are other repository configurations available in tripleo-repos, see its –help output for details.

    sudo tripleo-repos current-tripleo-dev
    

    Ceph

    Include the Ceph repository in the tripleo-repos command:

    sudo tripleo-repos current-tripleo-dev ceph
    
  1. Install the TripleO CLI, which will pull in all other necessary packages as dependencies:

    sudo yum install -y python-tripleoclient
    

    Ceph

    If you intend to deploy Ceph in the overcloud and are running Pike or newer, then install ceph-ansible on the undercloud:

    sudo yum install -y ceph-ansible
    
  2. Copy in the sample configuration file and edit it to reflect your environment:

    cp /usr/share/instack-undercloud/undercloud.conf.sample ~/undercloud.conf
    

    Note

    There is a tool available that can help with writing a basic undercloud.conf: Undercloud Configuration Wizard It takes some basic information about the intended overcloud environment and generates sane values for a number of the important options.

  3. Run the command to install the undercloud:

    SSL

    To deploy an undercloud with SSL, see Deploying with SSL.

    Validations

    Validations will be installed and configured during undercloud installation. You can set enable_validations = false in undercloud.conf to prevent that.

    Install the undercloud:

    openstack undercloud install
    

Once the install has completed, you should take note of the files stackrc and undercloud-passwords.conf. You can source stackrc to interact with the undercloud via the OpenStack command-line client. undercloud-passwords.conf contains the passwords used for each service in the undercloud. These passwords will be automatically reused if the undercloud is reinstalled on the same system, so it is not necessary to copy them to undercloud.conf.

Note

Any passwords set in undercloud.conf will take precedence over the ones in undercloud-passwords.conf.

Note

openstack undercloud install can be rerun to reapply changes from undercloud.conf to the undercloud. Note that this should not be done if an overcloud has already been deployed or is in progress.

Note

If running docker commands as a stack user after an undercloud install fail with a permission error, log out and log in again. The stack user does get added to the docker group during install, but that change gets reflected only after a new login.

Updating Undercloud Components

You can upgrade any packages that are installed on the undercloud machine.

  1. Remove all Delorean repositories:

    Note

    You may wish to backup your current repos before disabling them:

    mkdir /home/stack/REPOBACKUP
    sudo mv /etc/yum.repos.d/delorean* /home/stack/REPOBACKUP
    
    sudo rm /etc/yum.repos.d/delorean*
    
  2. Enable new Delorean repositories:

    Download and install the python2-tripleo-repos RPM from the current RDO repository. For example:

    sudo yum install -y https://trunk.rdoproject.org/centos7/current/python2-tripleo-repos-<version>.el7.centos.noarch.rpm
    

    Note

    tripleo-repos removes any repositories that it manages before each run. This means all repositories must be specified in a single tripleo-repos call. As an example, the correct way to install the current and ceph repos is to run tripleo-repos current ceph, not two separate calls.

    Stable Branch

    Enable the appropriate repos for the desired release, as indicated below. Do not enable any other repos not explicitly marked for that release.

    Newton

    Enable the current Newton repositories:

    sudo tripleo-repos -b newton current
    

    Ceph

    Include the Ceph repo in the tripleo-repos call:

    sudo tripleo-repos -b newton current ceph
    

    Ocata

    Enable the current Ocata repositories:

    sudo tripleo-repos -b ocata current
    

    Ceph

    Include the Ceph repo in the tripleo-repos call:

    sudo tripleo-repos -b ocata current ceph
    

    Pike

    Enable the current Pike repositories:

    sudo tripleo-repos -b pike current
    

    Ceph

    Include the Ceph repo in the tripleo-repos call:

    sudo tripleo-repos -b pike current ceph
    

    Warning

    The remaining repositories configuration steps below should not be done for stable releases!

    Run tripleo-repos to install the appropriate repositories. The option below will enable the latest master TripleO packages and the latest promoted packages for all other OpenStack services and dependencies. There are other repository configurations available in tripleo-repos, see its –help output for details.

    sudo tripleo-repos current-tripleo-dev
    

    Ceph

    Include the Ceph repository in the tripleo-repos command:

    sudo tripleo-repos current-tripleo-dev ceph
    
  1. Clean the yum cache to ensure only the new repos are used:

    sudo yum clean all
    
  2. Update required package:

    Validations

    It is strongly recommended that you validate the state of your undercloud before starting any upgrade operations. The tripleo-validations repo has some ‘pre-upgrade’ validations that you can execute by following the instructions at validations to execute the “pre-upgrade” group:

    mistral execution-get-output $(openstack workflow execution create -f value -c ID tripleo.validations.v1.run_groups '{"group_names": ["pre-upgrade"]}')
    

    Newton to Ocata

    The following commands need to be run before the undercloud upgrade:

    sudo systemctl stop openstack-*
    sudo systemctl stop neutron-*
    sudo systemctl stop openvswitch
    sudo systemctl stop httpd
    sudo yum -y update instack-undercloud openstack-puppet-modules openstack-tripleo-common
    

    Ocata to Pike

    Ceph

    Prior to Pike, TripleO deployed Ceph with puppet-ceph. With the Pike release it is possible to use TripleO to deploy Ceph with either ceph-ansible or puppet-ceph, though puppet-ceph is deprecated. To use ceph-ansible, the CentOS Storage SIG Ceph repository must be enabled on the undercloud and the ceph-ansible package must then be installed:

    sudo yum -y install --enablerepo=extras centos-release-ceph-jewel
    sudo yum -y install ceph-ansible
    

    Update TripleO CLI package:

    sudo yum -y update python-tripleoclient
    
  3. Run the undercloud upgrade command. This command will upgrade all packages and use puppet to apply new configuration and restart all OpenStack services:

    openstack undercloud upgrade
    

    Note

    You may wish to use time and capture the output to a file for any debug:

    time openstack undercloud upgrade 2>&1 | tee undercloud_upgrade.log
    

    Note

    If you added custom OVS ports to the undercloud (e.g. in a virtual testing environment) you may need to re-add them at this point.

  4. Proceed with Updating Packages on Overcloud Nodes