From 4d1a949323f85bdaaa88b57a2928a7c366b686b0 Mon Sep 17 00:00:00 2001 From: Steve Baker Date: Mon, 6 Aug 2018 14:15:03 +1200 Subject: [PATCH] Document prepare modify image Change-Id: Ie305103cbe79c5bf4b9f885ecbe9026e8cca9600 --- .../container_image_prepare.rst | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/doc/source/install/advanced_deployment/container_image_prepare.rst b/doc/source/install/advanced_deployment/container_image_prepare.rst index 197c5c34..f02063de 100644 --- a/doc/source/install/advanced_deployment/container_image_prepare.rst +++ b/doc/source/install/advanced_deployment/container_image_prepare.rst @@ -220,4 +220,119 @@ 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. +Modifying images during prepare +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to modify images during prepare to make any required changes, +then immediately deploy with those changes. The use-cases 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 (proprietry addons, emergency fixes) + +The modification is done by invoking an ansible role on each image which needs +to be modified. The role takes a source image, makes the requested changes, +then tags the result. The prepare can then push the image 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 required behaviour for the modify use-cases. Modification is controlled via modify-specific keys in the +`ContainerImagePrepare` parameter: + +- `modify_role` specifies what ansible role to invoke for each image to modify. +- `modify_append_tag` is used to append to the end of the + source image tag. This makes it obvious that the resulting image has been + modified. It is also used to skip modification if the `push_destination` + registry already has that image, so it is recommended to change + `modify_append_tag` whenever the image must be modified. +- `modify_vars` is a dictionary of ansible variables to pass to the role. + +The different use-cases handled by role `tripleo-modify-image`_ are selected by +setting the `tasks_from` variable to the required file in that role. For all of +the following examples, see the documentation for the role +`tripleo-modify-image`_ for the other variables supported by that `tasks_from`. + +While developing and testing the `ContainerImagePrepare` entries which modify +images, it is recommended to run prepare on its own to confirm it is being +modified as expected:: + + sudo openstack tripleo container image prepare \ + -e ~/containers-prepare-parameter.yaml + +Updating existing packages +.......................... + +The following entries will result in all packages being updated in the images, +but 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 + ... + +Install RPM files +................. + +It is possible to install a directory of RPM files, which is useful for +installing hotfixes, local package builds, or any package which is not +available through a package repository. For example the following would install +some hotfix packages only in the `centos-binary-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 + ... + +Modify with custom Dockerfile +............................. + +For maximum flexibility, it is possible to specify a directory containing a +`Dockerfile` to make the required changes. When the role is invoked, a +`Dockerfile.modified` is generated which changes the `FROM` directive and adds +extra `LABEL` directives. The following example runs the custom +`Dockerfile` on the `centos-binary-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. Note that after any +`USER root` directives have been run, it is necessary to switch back to the +original image default user:: + + FROM docker.io/tripleomaster/centos-binary-nova-compute:latest + + USER root + + COPY customize.sh /tmp/ + RUN /tmp/customize.sh + + USER "nova" + .. _Delorean repository: https://trunk.rdoproject.org/centos7-master/ac/82/ac82ea9271a4ae3860528eaf8a813da7209e62a6_28eeb6c7/ +.. _tripleo-modify-image: https://github.com/openstack/ansible-role-tripleo-modify-image