Red Hat Training
A Red Hat training course is available for Red Hat OpenStack Platform
Chapter 3. Preparing for director installation
3.1. Preparing the undercloud
The director installation requires the following:
- A non-root user to execute commands.
- Directories to organize images and templates
- A resolvable hostname
- A Red Hat subscription
- The command line tools for image preparation and director installation
This procedure shows how to create these items.
Procedure
-
Log into your undercloud as the
root
user. Create the
stack
user:[root@director ~]# useradd stack
Set a password for the user:
[root@director ~]# passwd stack
Disable password requirements when using
sudo
:[root@director ~]# echo "stack ALL=(root) NOPASSWD:ALL" | tee -a /etc/sudoers.d/stack [root@director ~]# chmod 0440 /etc/sudoers.d/stack
Switch to the new
stack
user:[root@director ~]# su - stack [stack@director ~]$
Create directories for system images and Heat templates.
[stack@director ~]$ mkdir ~/images [stack@director ~]$ mkdir ~/templates
The director uses system images and Heat templates to create the overcloud environment. Red Hat recommends creating these directories to help you organize your local file system.
Check the base and full hostname of the undercloud:
[stack@director ~]$ hostname [stack@director ~]$ hostname -f
If either of the previous commands do not report the correct fully-qualified hostname or report an error, use
hostnamectl
to set a hostname:[stack@director ~]$ sudo hostnamectl set-hostname manager.example.com [stack@director ~]$ sudo hostnamectl set-hostname --transient manager.example.com
Edit the
/etc/hosts
to include an entry for the system’s hostname. The IP address in/etc/hosts
must match the address that you plan to use for your undercloud public API. For example, if the system is namedmanager.example.com
and uses10.0.0.1
for its IP address, then/etc/hosts
requires an entry like:10.0.0.1 manager.example.com manager
Register your system either with the Red Hat Content Delivery Network or with a Red Hat Satellite. For example, run the following command to register the system to the Content Delivery Network. Enter your Customer Portal user name and password when prompted:
[stack@director ~]$ sudo subscription-manager register
Find the entitlement pool ID for Red Hat OpenStack Platform director. For example:
[stack@director ~]$ sudo subscription-manager list --available --all --matches="Red Hat OpenStack" Subscription Name: Name of SKU Provides: Red Hat Single Sign-On Red Hat Enterprise Linux Workstation Red Hat CloudForms Red Hat OpenStack Red Hat Software Collections (for RHEL Workstation) Red Hat Virtualization SKU: SKU-Number Contract: Contract-Number Pool ID: Valid-Pool-Number-123456 Provides Management: Yes Available: 1 Suggested: 1 Service Level: Support-level Service Type: Service-Type Subscription Type: Sub-type Ends: End-date System Type: Physical
Locate the
Pool ID
value and attach the Red Hat OpenStack Platform 14 entitlement:[stack@director ~]$ sudo subscription-manager attach --pool=Valid-Pool-Number-123456
Disable all default repositories, and then enable the required Red Hat Enterprise Linux repositories:
[stack@director ~]$ sudo subscription-manager repos --disable=* [stack@director ~]$ sudo subscription-manager repos --enable=rhel-7-server-rpms --enable=rhel-7-server-extras-rpms --enable=rhel-7-server-rh-common-rpms --enable=rhel-ha-for-rhel-7-server-rpms --enable=rhel-7-server-openstack-14-rpms
These repositories contain packages the director installation requires.
Perform an update on your system to ensure you have the latest base system packages:
[stack@director ~]$ sudo yum update -y [stack@director ~]$ sudo reboot
Install the command line tools for director installation and configuration:
[stack@director ~]$ sudo yum install -y python-tripleoclient
3.2. Configuring an undercloud proxy
If your environment uses a proxy, you can pre-configure the undercloud to use the proxy details. This procedure is optional and only applies to users requiring proxy configuration.
Procedure
-
Log into the undercloud host as the
root
user. Edit the
/etc/environment
file:# vi /etc/environment
Add the following parameters to the
/etc/environment
.:- http_proxy
- The proxy to use for standard HTTP requests.
- https_proxy
- The proxy to use for HTTPs requests.
- no_proxy
- A comma-separated list of IP addresses and domains excluded from proxy communications. Include all IP addresses and domains relevant to the undercloud.
http_proxy=https://10.0.0.1:8080/ https_proxy=https://10.0.0.1:8080/ no_proxy=127.0.0.1,192.168.24.1,192.168.24.2,192.168.24.3
- Restart your shell session. For example, logout and re-login to the undercloud.
3.3. Installing ceph-ansible
The following procedure installs the ceph-ansible
package if you plan to create an overcloud with Ceph Storage nodes. If you do not plan to create Ceph Storage nodes in your overcloud, you do not need this package.
Procedure
Enable the Ceph Tools repository:
[stack@director ~]$ sudo subscription-manager repos --enable=rhel-7-server-rhceph-3-tools-rpms
Install the
ceph-ansible
package:[stack@director ~]$ sudo yum install -y ceph-ansible
3.4. Preparing container images
The undercloud configuration requires initial registry configuration to determine where to obtain images and how to store them. Complete the following steps to generate and customize an environment file for preparing your container images.
Procedure
- Log in to your undercloud host as the stack user.
Generate the default container image preparation file:
$ openstack tripleo container image prepare default \ --local-push-destination \ --output-env-file containers-prepare-parameter.yaml
This command includes the following additional options:
-
--local-push-destination
sets the registry on the undercloud as the location for container images. This means the director pulls the necessary images from the Red Hat Container Catalog and pushes them to the registry on the undercloud. The director uses this registry as the container image source. To pull directly from the Red Hat Container Catalog, omit this option. --output-env-file
is an environment file name. The contents of this file include the parameters for preparing your container images. In this case, the name of the file iscontainers-prepare-parameter.yaml
.NoteYou can also use the same
containers-prepare-parameter.yaml
file to define a container image source for both the undercloud and the overcloud.
-
-
Edit the
containers-prepare-parameter.yaml
and make the modifications to suit your requirements.
3.5. Container image preparation parameters
The default file for preparing your containers (containers-prepare-parameter.yaml
) contains the ContainerImagePrepare
Heat parameter. This parameter defines a list of strategies for preparing a set of images:
parameter_defaults: ContainerImagePrepare: - (strategy one) - (strategy two) - (strategy three) ...
Each strategy accepts a set of sub-parameters that define which images to use and what to do with them. The following table contains information about the sub-parameters you can use with each ContainerImagePrepare
strategy:
Parameter | Description |
---|---|
| List of image name substrings to exclude from a strategy. |
|
List of image name substrings to include in a strategy. At least one image name must match an existing image. All |
|
String to append to the tag for the destination image. For example, if you pull an image with the tag |
| A dictionary of image labels that filter the images to modify. If an image matches the labels defined, the director includes the image in the modification process. |
| String of ansible role names to run during upload but before pushing the image to the destination registry. |
|
Dictionary of variables to pass to |
|
The namespace of the registry to push images during the upload process. When you specify a namespace for this parameter, all image parameters use this namespace too. If set to |
| The source registry from where to pull the original container images. |
|
A dictionary of |
|
Defines the label pattern to tag the resulting images. Usually sets to |
The set
parameter accepts a set of key: value
definitions. The following table contains information about the keys:
Key | Description |
---|---|
| The name of the Ceph Storage container image. |
| The namespace of the Ceph Storage container image. |
| The tag of the Ceph Storage container image. |
| A prefix for each OpenStack service image. |
| A suffix for each OpenStack service image. |
| The namespace for each OpenStack service image. |
|
The driver to use to determine which OpenStack Networking (neutron) container to use. Use a null value to set to the standard |
|
The tag that the director uses to identify the images to pull from the source registry. You usually keep this key set to |
The set
section might contains several parameters that begin with openshift_
. These parameters are for various scenarios involving OpenShift-on-OpenStack.
3.6. Layering image preparation entries
The value of the ContainerImagePrepare
parameter is a YAML list. This means you can specify multiple entries. The following example demonstrates two entries where the director uses the latest version of all images except for the nova-api
image, which uses the version tagged with 14.0-44
:
ContainerImagePrepare: - tag_from_label: "{version}-{release}" push_destination: true excludes: - nova-api set: namespace: registry.access.redhat.com/rhosp14 name_prefix: openstack- name_suffix: '' tag: latest - push_destination: true includes: - nova-api set: namespace: registry.access.redhat.com/rhosp14 tag: 14.0-44
The includes
and excludes
entries control image filtering for each entry. The images that match the includes
strategy take precedence over excludes
matches. The image name must include the includes
or excludes
value to be considered a match.
3.7. Modifying images during preparation
It is possible to modify images during image preparation, then immediately deploy with modified images. Scenarios for modifying images include:
- As part of a continuous integration pipeline where images are modified with the changes being tested before deployment.
- As part of a development workflow where local changes need to be deployed for testing and development.
- When changes need to be deployed but are not available through an image build pipeline. For example, adding proprietry add-ons or emergency fixes.
To modify an image during preparation, invoke an Ansible role on each image that you want to modify. The role takes a source image, makes the requested changes, and tags the result. The prepare command can push the image to the destination registry and set the Heat parameters to refer to the modified image.
The Ansible role tripleo-modify-image
conforms with the required role interface, and provides the behaviour necessary for the modify use-cases. Modification is controlled using modify-specific keys in the ContainerImagePrepare
parameter:
-
modify_role
specifies the Ansible role to invoke for each image to modify. -
modify_append_tag
appends a string to the end of the source image tag. This makes it obvious that the resulting image has been modified. Use this parameter to skip modification if thepush_destination
registry already contains the modified image. It is recommended to changemodify_append_tag
whenever you modify the image. -
modify_vars
is a dictionary of Ansible variables to pass to the role.
To select a use-case that the tripleo-modify-image
role handles, set the tasks_from
variable to the required file in that role.
While developing and testing the ContainerImagePrepare
entries that modify images, it is recommended to run the image prepare command without any additional options to confirm the image is modified as expected:
sudo openstack tripleo container image prepare \ -e ~/containers-prepare-parameter.yaml
3.8. Updating existing packages on container images
The following example ContainerImagePrepare
entry updates in all packages on the images using the undercloud host’s yum repository configuration:
ContainerImagePrepare: - push_destination: true ... modify_role: tripleo-modify-image modify_append_tag: "-updated" modify_vars: tasks_from: yum_update.yml compare_host_packages: true yum_repos_dir_path: /etc/yum.repos.d ...
3.9. Installing additional RPM files to container images
You can install a directory of RPM files in your container images. This is useful for installing hotfixes, local package builds, or any package not available through a package repository. For example, the following ContainerImagePrepare
entry installs some hotfix packages only on the nova-compute
image:
ContainerImagePrepare: - push_destination: true ... includes: - nova-compute modify_role: tripleo-modify-image modify_append_tag: "-hotfix" modify_vars: tasks_from: rpm_install.yml rpms_path: /home/stack/nova-hotfix-pkgs ...
3.10. Modifying container images with a custom Dockerfile
For maximum flexibility, you can specify a directory containing a Dockerfile to make the required changes. When you invoke the tripleo-modify-image
role, the role generates a Dockerfile.modified
file that changes the FROM
directive and adds extra LABEL
directives. The following example runs the custom Dockerfile on the nova-compute
image:
ContainerImagePrepare: - push_destination: true ... includes: - nova-compute modify_role: tripleo-modify-image modify_append_tag: "-hotfix" modify_vars: tasks_from: modify_image.yml modify_dir_path: /home/stack/nova-custom ...
An example /home/stack/nova-custom/Dockerfile` follows. After running any USER
root directives, you must switch back to the original image default user:
FROM registry.access.redhat.com/rhosp14/openstack-nova-compute:latest USER "root" COPY customize.sh /tmp/ RUN /tmp/customize.sh USER "nova"
3.11. Preparing a Satellite server for container images
Red Hat Satellite 6 offers registry synchronization capabilities. This provides a method to pull multiple images into a Satellite server and manage them as part of an application life cycle. The Satellite also acts as a registry for other container-enabled systems to use. For more details information on managing container images, see "Managing Container Images" in the Red Hat Satellite 6 Content Management Guide.
The examples in this procedure use the hammer
command line tool for Red Hat Satellite 6 and an example organization called ACME
. Substitute this organization for your own Satellite 6 organization.
Procedure
Create a list of all container images, including the Ceph images:
$ sudo docker search "registry.access.redhat.com/rhosp14" | awk '{ print $2 }' | grep -v beta | sed "s/registry.access.redhat.com\///g" | tail -n+2 > satellite_images $ echo "rhceph/rhceph-3-rhel7" >> satellite_images_names
-
Copy the
satellite_images_names
file to a system that contains the Satellite 6hammer
tool. Alternatively, use the instructions in the Hammer CLI Guide to install thehammer
tool to the undercloud. Run the following
hammer
command to create a new product (OSP14 Containers
) in your Satellite organization:$ hammer product create \ --organization "ACME" \ --name "OSP14 Containers"
This custom product will contain our images.
Add the base container image to the product:
$ hammer repository create \ --organization "ACME" \ --product "OSP14 Containers" \ --content-type docker \ --url https://registry.access.redhat.com \ --docker-upstream-name rhosp14/openstack-base \ --name base
Add the overcloud container images from the
satellite_images
file.$ while read IMAGE; do \ IMAGENAME=$(echo $IMAGE | cut -d"/" -f2 | sed "s/openstack-//g" | sed "s/:.*//g") ; \ hammer repository create \ --organization "ACME" \ --product "OSP14 Containers" \ --content-type docker \ --url https://registry.access.redhat.com \ --docker-upstream-name $IMAGE \ --name $IMAGENAME ; done < satellite_images_names
Synchronize the container images:
$ hammer product synchronize \ --organization "ACME" \ --name "OSP14 Containers"
Wait for the Satellite server to complete synchronization.
NoteDepending on your configuration,
hammer
might ask for your Satellite server username and password. You can configurehammer
to automatically login using a configuration file. For more information, see the "Authentication" section in the Hammer CLI Guide.-
If your Satellite 6 server uses content views, create a new content view version to incorporate the images and promote it along environments in your application life cycle. This largely depends on how you structure your application lifecycle. For example, if you have an environment called
production
in your lifecycle and you want the container images available in that environment, create a content view that includes the container images and promote that content view to theproduction
environment. For more information, see "Managing Container Images with Content Views". Check the available tags for the
base
image:$ hammer docker tag list --repository "base" \ --organization "ACME" \ --environment "production" \ --content-view "myosp14" \ --product "OSP14 Containers"
This command displays tags for the OpenStack Platform container images within a content view for an particular environment.
Return to the undercloud and generate a default environment file for preparing images using your Satellite server as a source. Run the following example command to generate the environment file:
(undercloud) $ openstack tripleo container image prepare default \ --output-env-file containers-prepare-parameter.yaml
-
--output-env-file
is an environment file name. The contents of this file will include the parameters for preparing your container images for the undercloud. In this case, the name of the file iscontainers-prepare-parameter.yaml
.
-
Edit the
containers-prepare-parameter.yaml
file and modify the following parameters:-
namespace
- The URL and port of the registry on the Satellite server. The default registry port on Red Hat Satellite is 5000. name_prefix
- The prefix is based on a Satellite 6 convention. This differs depending on whether you use content views:-
If you use content views, the structure is
[org]-[environment]-[content view]-[product]-
. For example:acme-production-myosp14-osp14_containers-
. -
If you do not use content views, the structure is
[org]-[product]-
. For example:acme-osp14_containers-
.
-
If you use content views, the structure is
-
ceph_namespace
,ceph_image
,ceph_tag
- If using Ceph Storage, include the additional parameters to define the Ceph Storage container image location. Note thatceph_image
now includes a Satellite-specific prefix. This prefix is the same value as thename_prefix
option.
-
The following example environment file contains Satellite-specific parameters:
parameter_defaults: ContainerImagePrepare: - push_destination: true set: ceph_image: acme-production-myosp14-osp14_containers-rhceph-3-rhel7 ceph_namespace: satellite.example.com:5000 ceph_tag: latest name_prefix: acme-production-myosp14-osp14_containers- name_suffix: '' namespace: satellite.example.com:5000 neutron_driver: null tag: latest ... tag_from_label: '{version}-{release}'
Use this environment file when creating both your undercloud and overcloud.