Document "openstack tripleo container image prepare"
This documents container image prepare for the undercloud and overcloud as currently implemented. This means prepare occurs during undercloud install, but overcloud still requires calling the new command "openstack tripleo container image prepare". There will be a futher docs change when blueprint container-prepare-workflow is complete, but these docs are ready to land now. Change-Id: I88353551ac9e07484ad585ef6c17415645d13121 Blueprint: container-prepare-workflow
This commit is contained in:
Steve Baker
Emilien Macchi
parent
784afafc91
commit
241fef3167
@ -0,0 +1,222 @@
|
||||
.. _prepare-environment-containers:
|
||||
|
||||
Container Image Preperation
|
||||
===========================
|
||||
|
||||
This documentation explains how to instruct container image preparation to do
|
||||
different preparation tasks.
|
||||
|
||||
Choosing an image registry strategy
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Container images need to be pulled from an image registry which is reliably
|
||||
available to overcloud nodes. The three common options to serve images are to
|
||||
use the default registry, the registry availably on the undercloud, or an
|
||||
independently managed registry. During deployment the environment parameter
|
||||
`ContainerImagePrepare` is used to specify any desired behaviour, including:
|
||||
|
||||
- Where to pull images from
|
||||
- Optionally, which local repository to push images to
|
||||
- How to discover the lasted versioned tag for each image
|
||||
|
||||
In the following examples, the parameter `ContainerImagePrepare` will be
|
||||
specified in its own file `containers-prepare-parameter.yaml`.
|
||||
|
||||
Default registry
|
||||
................
|
||||
|
||||
By default the images will be pulled from a remote registry namespace such as
|
||||
`docker.io/tripleomaster`. This is fine for development or POC clouds but is
|
||||
not appropriate for production clouds due to the transfer of large amounts of
|
||||
duplicate image data over a potentially unreliable internet connection.
|
||||
|
||||
During deployment with this default, any heat parameters which refer to
|
||||
required container images will be populated with a value pointing at the
|
||||
default registry, with a tag representing the latest image version.
|
||||
|
||||
To generate the `containers-prepare-parameter.yaml` containing these defaults,
|
||||
run this command::
|
||||
|
||||
openstack tripleo container image prepare default \
|
||||
--output-env-file containers-prepare-parameter.yaml
|
||||
|
||||
This will generate a file containing a `ContainerImagePrepare` similar to the
|
||||
following::
|
||||
|
||||
parameter_defaults:
|
||||
ContainerImagePrepare:
|
||||
- set:
|
||||
ceph_image: daemon
|
||||
ceph_namespace: docker.io/ceph
|
||||
ceph_tag: v3.0.3-stable-3.0-luminous-centos-7-x86_64
|
||||
name_prefix: centos-binary-
|
||||
name_suffix: ''
|
||||
namespace: docker.io/tripleomaster
|
||||
neutron_driver: null
|
||||
tag: current-tripleo
|
||||
tag_from_label: rdo_version
|
||||
|
||||
During deployment, this will lookup images in `docker.io/tripleomaster` tagged
|
||||
with `current-tripleo` and discover a versioned tag by looking up the label
|
||||
`rdo_version`. This will result in the heat image parameters in the plan being
|
||||
set with appropriate values, such as::
|
||||
|
||||
DockerNeutronMetadataImage: docker.io/tripleomaster/centos-binary-neutron-metadata-agent:35414701c176a6288fc2ad141dad0f73624dcb94_43527485
|
||||
DockerNovaApiImage: docker.io/tripleomaster/centos-binary-nova-api:35414701c176a6288fc2ad141dad0f73624dcb94_43527485
|
||||
|
||||
.. note:: The tag is actually a Delorean hash. You can find out the versions
|
||||
of packages by using this tag.
|
||||
For example, `35414701c176a6288fc2ad141dad0f73624dcb94_43527485` tag,
|
||||
is in fact using this `Delorean repository`_.
|
||||
|
||||
.. _populate-local-registry-containers:
|
||||
|
||||
Undercloud registry
|
||||
...................
|
||||
|
||||
As part of the undercloud install, an image registry is configured on port
|
||||
`8787`. This can be used to increase reliability of image pulls, and minimise
|
||||
overall network transfers.
|
||||
The undercloud registry can be used by generating the following
|
||||
`containers-prepare-parameter.yaml` file::
|
||||
|
||||
openstack tripleo container image prepare default \
|
||||
--local-push-destination \
|
||||
--output-env-file containers-prepare-parameter.yaml
|
||||
|
||||
This will generate a file containing a `ContainerImagePrepare` similar to the
|
||||
following::
|
||||
|
||||
parameter_defaults:
|
||||
ContainerImagePrepare:
|
||||
- push_destination: 192.168.24.1:8787
|
||||
set:
|
||||
ceph_image: daemon
|
||||
ceph_namespace: docker.io/ceph
|
||||
ceph_tag: v3.0.3-stable-3.0-luminous-centos-7-x86_64
|
||||
name_prefix: centos-binary-
|
||||
name_suffix: ''
|
||||
namespace: docker.io/tripleomaster
|
||||
neutron_driver: null
|
||||
tag: current-tripleo
|
||||
tag_from_label: rdo_version
|
||||
|
||||
This is identical to the default registry, except for the `push_destination`
|
||||
entry which inserts the discovered address for the local undercloud registry.
|
||||
|
||||
By specifying a `push_destination`, during deployment all images will be pulled
|
||||
from the remote registry then pushed to the local undercloud registry. The
|
||||
resulting image parameters will also be modified to refer to the images in
|
||||
`push_destination` instead of `namespace`.
|
||||
|
||||
Running container image prepare
|
||||
...............................
|
||||
The prepare operations are actually run at the following times:
|
||||
|
||||
#. During ``undercloud install`` when `undercloud.conf` has
|
||||
`container_images_file=$HOME/containers-prepare-parameter.yaml` (see
|
||||
:ref:`install_undercloud`)
|
||||
#. Before overcloud deploy when ``openstack tripleo container image prepare``
|
||||
is run (see :ref:`overcloud-prepare-container-images`)
|
||||
|
||||
|
||||
Options available in heat parameter ContainerImagePrepare
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To do something different to the above two registry scenarios, your custom
|
||||
environment can set the value of the ContainerImagePrepare heat parameter to
|
||||
result in any desired registry and image scenario.
|
||||
|
||||
Discovering versioned tags with tag_from_label
|
||||
..............................................
|
||||
|
||||
If you want these parameters to have the actual tag `current-tripleo` instead of
|
||||
the discovered tag (in this case the Delorean hash,
|
||||
`35414701c176a6288fc2ad141dad0f73624dcb94_43527485` ) then the `tag_from_label`
|
||||
entry can be omitted.
|
||||
|
||||
Likewise, if all images should be deployed with a different tag, the value of
|
||||
`tag` can be set to the desired tag.
|
||||
|
||||
Some build pipelines have a versioned tag which can only be discovered via a
|
||||
combination of labels. For this case, a template format can be specified
|
||||
instead::
|
||||
|
||||
tag_from_label: {version}-{release}
|
||||
|
||||
Copying images with push_destination
|
||||
....................................
|
||||
|
||||
By specifying a `push_destination`, the required images will be copied from
|
||||
`namespace` to this registry, for example::
|
||||
|
||||
ContainerImagePrepare:
|
||||
- push_destination: 192.168.24.1:8787
|
||||
set:
|
||||
namespace: docker.io/tripleomaster
|
||||
...
|
||||
|
||||
This will result in images being copied from `docker.io/tripleomaster` to
|
||||
`192.168.24.1:8787/tripleomaster` and heat parameters set with values such as::
|
||||
|
||||
DockerNeutronMetadataImage: 192.168.24.1:8787/tripleomaster/centos-binary-neutron-metadata-agent:35414701c176a6288fc2ad141dad0f73624dcb94_43527485
|
||||
DockerNovaApiImage: 192.168.24.1:8787/tripleomaster/centos-binary-nova-api:35414701c176a6288fc2ad141dad0f73624dcb94_43527485
|
||||
|
||||
.. note:: Use the IP address of your undercloud, which you previously set with
|
||||
the `local_ip` parameter in your `undercloud.conf` file. For these example
|
||||
commands, the address is assumed to be `192.168.24.1:8787`.
|
||||
|
||||
By setting different values for `namespace` and `push_destination` any
|
||||
alternative registry strategy can be specified.
|
||||
|
||||
Ceph and other set options
|
||||
..........................
|
||||
|
||||
The options `ceph_namespace`, `ceph_image`, and `ceph_tag` are similar to
|
||||
`namespace` and `tag` but they specify the values for the ceph image. It will
|
||||
often come from a different registry, and have a different versioned tag
|
||||
policy.
|
||||
|
||||
The values in the `set` map are used when evaluating the file
|
||||
`/usr/share/openstack-tripleo-common/container-images/overcloud_containers.yaml.j2`
|
||||
as a Jinja2 template. This file contains the list of every container image and
|
||||
how it relates to TripleO services and heat parameters.
|
||||
|
||||
Layering image preparation entries
|
||||
..................................
|
||||
|
||||
Since the value of `ContainerImagePrepare` is a list, multiple entries can be
|
||||
specified, and later entries will overwrite any earlier ones. Consider the
|
||||
following::
|
||||
|
||||
ContainerImagePrepare:
|
||||
- tag_from_label: rdo_version
|
||||
push_destination: 192.168.24.1:8787
|
||||
excludes:
|
||||
- nova-api
|
||||
set:
|
||||
namespace: docker.io/tripleomaster
|
||||
name_prefix: centos-binary-
|
||||
name_suffix: ''
|
||||
tag: current-tripleo
|
||||
- push_destination: 192.168.24.1:8787
|
||||
includes:
|
||||
- nova-api
|
||||
set:
|
||||
namespace: mylocal
|
||||
tag: myhotfix
|
||||
|
||||
This will result in the following heat parameters which shows a `locally built
|
||||
<build_container_images>`
|
||||
and tagged `centos-binary-nova-api` being used for `DockerNovaApiImage`::
|
||||
|
||||
DockerNeutronMetadataImage: 192.168.24.1:8787/tripleomaster/centos-binary-neutron-metadata-agent:35414701c176a6288fc2ad141dad0f73624dcb94_43527485
|
||||
DockerNovaApiImage: 192.168.24.1:8787/mylocal/centos-binary-nova-api:myhotfix
|
||||
|
||||
The `includes` and `excludes` entries can control the resulting image list in
|
||||
addition to the filtering which is determined by roles and containerized
|
||||
services in the plan. `includes` matches take precedence over `excludes`
|
||||
matches, followed by role/service filtering. The image name must contain the
|
||||
value within it to be considered a match.
|
||||
|
||||
.. _Delorean repository: https://trunk.rdoproject.org/centos7-master/ac/82/ac82ea9271a4ae3860528eaf8a813da7209e62a6_28eeb6c7/
|
||||
@ -18,6 +18,7 @@ Documentation on how to enable and configure various features available in
|
||||
instance_ha
|
||||
oslo_messaging_config
|
||||
baremetal_overcloud
|
||||
container_image_prepare
|
||||
ovs_dpdk_config
|
||||
deployed_server
|
||||
keystone_security_compliance
|
||||
|
||||
@ -29,144 +29,53 @@ This section explains how to deploy a containerized overcloud manually. For an
|
||||
automated overcloud deployment, please follow the steps in the
|
||||
`Using TripleO Quickstart`_ section below.
|
||||
|
||||
.. _prepare-environment-containers:
|
||||
Preparing overcloud images
|
||||
..........................
|
||||
|
||||
Preparing the environment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
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 overcloud deploy by generating the following
|
||||
`containers-prepare-parameter.yaml` file and using that for the prepare call::
|
||||
|
||||
To prepare your environment, you must follow all the steps described in the
|
||||
:ref:`basic-deployment-cli` documentation. Stop right at the
|
||||
:ref:`deploy-the-overcloud` section.
|
||||
openstack tripleo container image prepare default \
|
||||
--local-push-destination \
|
||||
--output-env-file containers-prepare-parameter.yaml
|
||||
|
||||
It is necessary to generate a heat environment file which specifies the
|
||||
container image parameters.
|
||||
.. note:: The file `containers-prepare-parameter.yaml` may have already been
|
||||
created during :ref:`install_undercloud`. It is
|
||||
encouraged to share the same `containers-prepare-parameter.yaml` file
|
||||
for undercloud install and overcloud deploy.
|
||||
|
||||
The ``openstack overcloud container image prepare`` command is an easy
|
||||
way to generate these parameters. The following command will generate
|
||||
a heat environment file `~/docker_registry.yaml` to deploy an overcloud
|
||||
with container images from RDO docker registry::
|
||||
See :ref:`prepare-environment-containers` for details on using
|
||||
`containers-prepare-parameter.yaml` to control what can be done
|
||||
during container image preparation.
|
||||
|
||||
openstack overcloud container image prepare \
|
||||
--namespace docker.io/tripleomaster \
|
||||
--tag current-tripleo \
|
||||
--tag-from-label rdo_version \
|
||||
--output-env-file ~/docker_registry.yaml
|
||||
.. _overcloud-prepare-container-images:
|
||||
|
||||
A tag needs to be specified which is unique to the images being deployed. This
|
||||
makes it possible to later update the overcloud to newer image versions. It
|
||||
also makes it easier to determine what images you are running in the overcloud.
|
||||
This unique tag is discovered with the above command with the argument
|
||||
``--tag-from-label rdo_version``. This will cause every image with the tag
|
||||
``current-tripleo`` to be inspected to find the unique tag by looking at
|
||||
the value of the ``rdo_version`` label.
|
||||
Running container image prepare
|
||||
...............................
|
||||
|
||||
.. note:: The tag is actually a Delorean hash. You can find out the versions
|
||||
of packages by using this tag.
|
||||
For example, `ac82ea9271a4ae3860528eaf8a813da7209e62a6_28eeb6c7` tag,
|
||||
is in fact using this `Delorean repository`_.
|
||||
The ``openstack tripleo container image prepare`` command performs all of the
|
||||
required prepare tasks as specified by `~/containers-prepare-parameter.yaml`.
|
||||
This generates the environment file `~/containers-default-parameters.yaml`
|
||||
which contains all of the container image parameters needed for the overcloud
|
||||
deploy. The prepare is run with the command::
|
||||
|
||||
The option ``--namespace docker.io/tripleomaster``
|
||||
will typically be replaced with a value specific to the
|
||||
environment. Run with ``--help`` to see the other options available for
|
||||
controlling what is generated.
|
||||
|
||||
It is possible to limit the output to only the images that are going to be used
|
||||
in the deployment by specifying the heat environment files with the
|
||||
``--environment-file`` option and the roles file with the ``--roles-file``
|
||||
option.
|
||||
|
||||
.. _populate-local-registry-containers:
|
||||
|
||||
Populate local docker registry
|
||||
..............................
|
||||
|
||||
Serving container images from a local registry is optional, but it can make
|
||||
overcloud deployment faster and more reliable. For development purposes an
|
||||
insecure docker registry is already setup to listen on port 8787 as part of the
|
||||
undercloud install.
|
||||
|
||||
To copy the images from one registry to another, the above `prepare` command is
|
||||
modified to also generate the `overcloud_containers.yaml` file. This describes
|
||||
the source and destination image locations consumed by the `upload` command.
|
||||
|
||||
To copy the pre-built images coming from the `rdoproject` registry to
|
||||
the local repository, the following commands are run. The first sets
|
||||
up the ``overcloud_containers.yaml`` configuration file containing the
|
||||
pull and push destinations::
|
||||
|
||||
openstack overcloud container image prepare \
|
||||
--namespace docker.io/tripleomaster \
|
||||
--tag current-tripleo \
|
||||
--tag-from-label rdo_version \
|
||||
--push-destination 192.168.24.1:8787 \
|
||||
--output-env-file ~/docker_registry.yaml \
|
||||
--output-images-file overcloud_containers.yaml
|
||||
|
||||
.. note:: Use the IP address of your undercloud, which you previously set with
|
||||
the `local_ip` parameter in your `undercloud.conf` file. For these example
|
||||
commands, the address is assumed to be `192.168.24.1:8787`.
|
||||
|
||||
This creates an `~/docker_registry.yaml` environment file, which contains image
|
||||
locations on the undercloud. You include this file with your deployment.
|
||||
This also creates a file called `overcloud_containers.yaml` with your
|
||||
container image information you should use to push images into the local registry.
|
||||
|
||||
.. admonition:: Stable Branch
|
||||
:class: stable
|
||||
|
||||
If you wish to deploy a stable version, you will need to pull down the
|
||||
correct containers for the version being deployed.
|
||||
|
||||
.. admonition:: Pike
|
||||
:class: pike
|
||||
|
||||
Use the Pike containers::
|
||||
|
||||
openstack overcloud container image prepare \
|
||||
--namespace docker.io/tripleopike \
|
||||
--tag <tag> \
|
||||
--push-destination 192.168.24.1:8787 \
|
||||
--output-env-file ~/docker_registry.yaml \
|
||||
--output-images-file overcloud_containers.yaml
|
||||
|
||||
.. admonition:: Queens
|
||||
:class: queens
|
||||
|
||||
Use the Queens containers::
|
||||
|
||||
openstack overcloud container image prepare \
|
||||
--namespace docker.io/tripleoqueens \
|
||||
--tag <tag> \
|
||||
--push-destination 192.168.24.1:8787 \
|
||||
--output-env-file ~/docker_registry.yaml \
|
||||
--output-images-file overcloud_containers.yaml
|
||||
|
||||
Then upload the images to the local registry using the generated file::
|
||||
|
||||
openstack overcloud container image upload --config-file overcloud_containers.yaml
|
||||
|
||||
.. note::
|
||||
If this command fails with the following error::
|
||||
|
||||
Error while fetching server API version: ('Connection aborted.', error(13, 'Permission denied'))
|
||||
|
||||
You may need to run ``newgrp docker``. This is because the undercloud install
|
||||
adds the current user to the docker group, but that change will not
|
||||
automatically take effect in the current session.
|
||||
|
||||
Or :ref:`build and push the images <build_container_images>` yourself. This is
|
||||
useful if you wish to customize the containers or modify an existing one.
|
||||
openstack tripleo container image prepare \
|
||||
-e ~/containers-prepare-parameter.yaml
|
||||
--roles-file /usr/share/openstack-tripleo-heat-templates/roles_data.yaml \
|
||||
--output-env-file ~/containers-default-parameters.yaml
|
||||
|
||||
Deploying the containerized Overcloud
|
||||
-------------------------------------
|
||||
|
||||
A containerized overcloud deployment follows all the steps described in the
|
||||
baremetal :ref:`deploy-the-overcloud` documentation with the exception that it
|
||||
requires extra environment files to be added to the ``openstack overcloud
|
||||
requires an extra environment file to be added to the ``openstack overcloud
|
||||
deploy`` command::
|
||||
|
||||
-e /usr/share/openstack-tripleo-heat-templates/environments/docker.yaml
|
||||
-e ~/docker_registry.yaml
|
||||
-e ~/containers-default-parameters.yaml
|
||||
|
||||
If deploying with highly available controller nodes, include the
|
||||
following extra environment file in addition to the above and in place
|
||||
@ -187,4 +96,3 @@ The command below will deploy a containerized overcloud on top of a baremetal un
|
||||
bash quickstart.sh --config=~/.quickstart/config/general_config/containers_minimal.yml $VIRTHOST
|
||||
|
||||
.. _TripleO Quickstart: https://docs.openstack.org/developer/tripleo-quickstart/
|
||||
.. _Delorean repository: https://trunk.rdoproject.org/centos7-master/ac/82/ac82ea9271a4ae3860528eaf8a813da7209e62a6_28eeb6c7/
|
||||
|
||||
@ -4,6 +4,8 @@ Undercloud Installation
|
||||
This section contains instructions on how to install the undercloud and how to
|
||||
update components after installation.
|
||||
|
||||
.. _install_undercloud:
|
||||
|
||||
.. include:: installing.rst
|
||||
|
||||
.. include:: updating.rst
|
||||
|
||||
@ -108,24 +108,27 @@ Installing the Undercloud
|
||||
environment and generates sane values for a number of the important
|
||||
options.
|
||||
|
||||
#. (OPTIONAL) Set up a containers registry and prepare container images
|
||||
configuration.
|
||||
#. (OPTIONAL) Generate configuration for preparing container images
|
||||
|
||||
See :ref:`prepare-environment-containers` for details on the containers
|
||||
images preparations. The described workflow is applicable both for
|
||||
overclouds and underclouds. Additional ``docker_insecure_registries`` and
|
||||
``docker_registry_mirror`` parameters allow to customize container registries
|
||||
via the ``undercloud.conf`` file.
|
||||
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``::
|
||||
|
||||
.. note:: Local undercloud containers registry is not suitable for real
|
||||
deployments. For production use, it is highly recommended that you use an
|
||||
external container registry.
|
||||
See :ref:`populate-local-registry-containers` for details on managing
|
||||
containers images data populated into registries.
|
||||
openstack tripleo container image prepare default \
|
||||
--local-push-destination \
|
||||
--output-env-file ~/containers-prepare-parameter.yaml
|
||||
|
||||
Once you have a containers images configuration file prepared and
|
||||
containers images populated into registries, the images config file should
|
||||
be explicitly specified in ``undercloud.conf: container_images_file``.
|
||||
See :ref:`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`` and ``docker_registry_mirror``
|
||||
parameters allow to customize container registries via the
|
||||
``undercloud.conf`` file.
|
||||
|
||||
#. (OPTIONAL) Override heat parameters and environment files used for undercloud
|
||||
deployment.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user