Document the usage of the --reproduce-command option to obtain a reproducer file with the Ansible command used to re-run the very same deployment playbooks. Depends-On: https://review.opendev.org/c/openstack/python-tripleoclient/+/827494 Change-Id: Id136969eaef3a1a911c1132bdc696181039e787c
12 KiB
Undercloud Installation
This section contains instructions on how to install the undercloud. For update or upgrade to a deployed undercloud see undercloud_upgrade.
Installing the Undercloud
Note
Instack-undercloud was deprecated in Rocky cycle. Containerized
undercloud should be installed instead. See undercloud
for backward
compatibility related information.
Note
Please ensure all your nodes (undercloud, compute, controllers, etc) have their internal clock set to UTC in order to prevent any issue with possible file future-dated timestamp if hwclock is synced before any timezone offset is applied.
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. Installations with the permissive/disabled SELinux are not recommended. The
undercloud_enable_selinux
config option controls that setting.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
Enable needed repositories:
RHEL
Enable optional repo for RHEL7:
sudo yum install -y yum-utils sudo yum-config-manager --enable rhelosp-rhel-7-server-opt
Install the TripleO CLI, which will pull in all other necessary packages as dependencies:
sudo dnf install -y python*-tripleoclient
RHEL7 / CentOS
For RHEL or CentOS 7 the command would be:
sudo yum install -y python-tripleoclient
Ceph
If you intend to deploy Ceph in the overcloud, or configure the overcloud to use an external Ceph cluster, and are running Pike or newer, then install ceph-ansible on the undercloud:
sudo dnf install -y ceph-ansible
TLS
If you intend to deploy TLS-everywhere in the overcloud and are deploying Train with python3 or Ussuri+, install the following packages:
sudo yum install -y python3-ipalib python3-ipaclient krb5-devel
If you're deploying Train with python2, install the corresponding python2 version of the above packages:
sudo yum install -y python-ipalib python-ipaclient krb5-devel
if you intend to use Novajoin to implement TLS-everywhere install the following package:
sudo yum install -y python-novajoin
You can find more information about deploying with TLS in the
../features/tls-introduction
documentation.Prepare the configuration file:
cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf
It is backwards compatible with non-containerized instack underclouds.
Stable Branch
For a non-containerized undercloud, 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.(OPTIONAL) Generate configuration for preparing container images
As part of the undercloud install, an image registry is configured on port 8787. This is used to increase reliability of overcloud image pulls, and minimise overall network transfers. The undercloud registry will be populated with images required by the undercloud by generating the following containers-prepare-parameter.yaml file and including it in
undercloud.conf: container_images_file=$HOME/containers-prepare-parameter.yaml
:openstack tripleo container image prepare default \ --local-push-destination \ --output-env-file ~/containers-prepare-parameter.yaml
Note
This command is available since Rocky.
See
prepare-environment-containers
for details on using containers-prepare-parameter.yaml to control what can be done during the container images prepare phase of an undercloud install.Additionally,
docker_insecure_registries
anddocker_registry_mirror
parameters allow to customize container registries via theundercloud.conf
file.(OPTIONAL) Override heat parameters and environment files used for undercloud deployment.
Similarly to overcloud deployments, see
override-heat-templates
andcustom-template-location
, theundercloud.conf: custom_env_files
andundercloud.conf: templates
configuration parameters allow to use a custom heat templates location and override or specify additional information for Heat resources used for undercloud deployment.Additionally, the
undercloud.conf: roles_file
parameter brings in the ultimate flexibility ofcustom_roles
andcomposable_services
. This allows you to deploy an undercloud composed of highly customized containerized services, with the same workflow that TripleO uses for overcloud deployments.Note
The CLI and configuration interface used to deploy a containerized undercloud is the same as that used by 'legacy' non-containerized underclouds. As noted above however mechanism by which the undercloud is actually deployed is completely changed and what is more, for the first time aligns with the overcloud deployment. See the command
openstack tripleo deploy --standalone
help for details. It normally should not be used directly for undercloud installations.Run the command to install the undercloud:
SSL
To deploy an undercloud with SSL, see
../features/ssl
.Validations
../post_deployment/validations/index
will be installed and configured during undercloud installation. You can setenable_validations = false
inundercloud.conf
to prevent that.To deploy an undercloud:
openstack undercloud install
Note
The undercloud is containerized by default as of Rocky.
Note
It's possible to enable verbose logging with --verbose
option.
Note
To install a deprecated instack undercloud, you'll need to deploy
with --use-heat=False
option.
Since Rocky, we will run all the OpenStack services in a moby container runtime 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 executed by tripleoclient 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).
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. The
undercloud-passwords.conf
file 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
Heat installer configuration, logs and state is ephemeral for
undercloud deployments. Generated artifacts for consequent deployments
get overwritten or removed (when
undercloud.conf: cleanup = true
). Although, you can still
find them stored in compressed files.
Miscellaneous undercloud deployment artifacts, like processed heat
templates and compressed files, can be found in
undercloud.conf: output_dir
locations like
~/tripleo-heat-installer-templates
.
There is also a compressed file created and placed into the output
dir, named as undercloud-install-<TS>.tar.bzip2
,
where TS represents a timestamp.
Downloaded ansible playbooks and inventory files (see config_download
) used for
undercloud deployment are stored in the tempdir
~/undercloud-ansible-<XXXX>
by default.
Note
In order to obtain the ansible command used for the installation of
the Undercloud in the artifacts directory, it is necessary to pass the
option --reproduce-command
in the Undercloud deployment
command.
Note
Any passwords set in undercloud.conf
will take
precedence over the ones in undercloud-passwords.conf
.
Note
The undercloud installation command can be rerun to reapply changes
from undercloud.conf
to the undercloud. Note that this
should be done with caution if an overcloud has already been deployed or
is in progress as some configuration changes could affect the overcloud.
These changes include but are not limited to:
- Package repository changes on the undercloud, followed by running the installation command could update the undercloud such that further management operations are not possible on the overcloud until the overcloud update or upgrade procedure is followed.
- Reconfiguration of the undercloud container registry if the overcloud is using the undercloud as the source for container images.
- Networking configuration changes on the undercloud which may affect the overcloud's ability to connect to the undercloud for instance metadata services.
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.
Cleaning the Undercloud
This procedure isn't cleaning everything that TripleO generates, but enough so an Undercloud could be re-deployed.
Note
This procedure has been tested on Train and onward. There is no guarantee that it works before this version, due to container commands and new directories.
Log in to your machine (baremetal or VM) where you want to cleanup the undercloud as a non-root user (such as the stack user):
ssh <non-root-user>@<undercloud-machine>
Cleanup the containers and their images:
sudo podman rm -af sudo podman rmi -af
Remove directories generated by TripleO:
sudo rm -rf \ /var/lib/tripleo-config \ /var/lib/config-data \ /var/lib/container-config-scripts \ /var/lib/container-puppet \ /var/lib/heat-config \ /var/lib/image-service \ /var/lib/mysql
Cleanup systemd:
sudo rm -rf /etc/systemd/system/tripleo* sudo systemctl daemon-reload