Merge pull request #701 from slagle/hotfix-process

Document hotfix process

docs/assemblies/creating-the-data-plane.adoc

@@ -54,3 +54,5 @@ include::interacting_with_ansible.adoc[leveloffset=+1]
 include::hashes.adoc[leveloffset=+1]
 
 include::ipam.adoc[leveloffset=+1]
+
+include::hotfixing-the-data-plane.adoc[leveloffset=+1]

docs/assemblies/hotfixing-the-data-plane.adoc

@@ -0,0 +1,26 @@
+[id="assembly_hotfixing-the-data-plane"]
+= Hotfixing the data plane
+
+:context: dataplane
+
+[role="_abstract"]
+You can update the OpenStack data plane when hotfix content is available. Hotfix content
+can be delivered as RPM packages or container images.
+
+You apply a container hotfix to the data plane nodes by updating any running
+containers to run from container images where the hotfix content has been
+applied. Container hotfix content can be delivered as either RPM’s or already
+updated container images.
+
+How the software is installed on the data plane nodes determines which of the
+following methods you need to use to apply the hotfix content:
+
+* Node software was installed by using RPMs: Apply the hotfix to the RPM content.
+* Node software was installed by using container images: Apply the hotfix to the container content with either RPMs or container images.
+
+
+include::proc_hotfixing-the-data-plane-rpm-content.adoc[leveloffset=+1]
+
+include::proc_hotfixing-the-data-plane-container-content-rpms.adoc[leveloffset=+1]
+
+include::proc_hotfixing-the-data-plane-container-content-images.adoc[leveloffset=+1]

docs/assemblies/proc_hotfixing-the-data-plane-container-content-images.adoc

@@ -0,0 +1,30 @@
+[id="proc_hotfixing-the-data-plane-container-content-images-{context}"]
+= Hotfixing the data plane container content with images
+
+[role="_abstract"]
+
+When container hotfix content is delivered as images, the container processes need to be restarted to use the new images. This will be accomplished by creating a new `OpenStackDataPlaneDeployment`.
+
+.Procedure
+
+. Optional: Prepare the container hotfix image in a container registry where the image can be pulled by affected data plane nodes:
++
+----
+$ podman pull <container_registry>/<container_project>/<container_image>:<container_tag>
+$ podman tag <container_registry>/<container_project>/<container_image>:<container_tag> <updated_container_registry>/<updated_container_project>/<container_image>:<container_tag>
+$ podman push <updated_container_registry>/<updated_container_project>/<container_image>:<container_tag>
+----
++
+* Replace `<container_registry>` with the source registry for the hotfixed container image.
+* Replace `<container_project>` with the source project for the hotfixed container image.
+* Replace `<container_image>` with the hotfixed container image.
+* Replace `<container_tag>` with the tag for the hotfixed container image.
+* Replace `<updated_container_registry>` with a container registry to serve the hotfixed container image. You can use the OpenShift internal container image registry.
+* Replace `<updated_container_project>` with a container project to use for the hotfixed container image.
+
+. Update the affected `OpenStackDataPlaneNodeSet` resources by customizing the container locations to the hotfixed container locations. For more information about how to set the hotfixed container locations, see <<_customizing_container_image_locations>>.
+
+. Create a new `OpenStackDataPlaneDeployment` resource that deploys the affected `OpenStackDataPlaneNodeSet` resources. For more information about how to create `OpenStackDataPlaneDeployment` resources, see <<proc_deploying-the-data-plane_{context}>>.
++
+[NOTE]
+You can restrict the list of services for the `OpenStackDataPlaneDeployment` to only those affected by the hotfix by using the `servicesOverride` field. For more information, see <<_overriding_services_for_the_deployment>>.

docs/assemblies/proc_hotfixing-the-data-plane-container-content-rpms.adoc

@@ -0,0 +1,47 @@
+[id="proc_hotfixing-the-data-plane-container-content-rpms-{context}"]
+= Hotfixing the data plane container content with RPM's
+
+[role="_abstract"]
+
+When container hotfix content is delivered as RPM's, you must update the container images manually.
+
+.Procedure
+
+. From a RHEL workstation, server, or virtual machine, ensure the following packages are installed:
++
+* buildah
+* podman
+
+. From a RHEL workstation, server, or virtual machine, collect the hotfix RPMs into a new directory:
++
+----
+$ mkdir -p <hotfix_id>/rpms
+$ cp /path/to/hotfix/*.rpm <hotfix_id>/rpms
+----
++
+* Replace `<hotfix_id>` with a hotfix identifier such as a Jira issue, for example `osprh-0000`.
+
+. Create a container image tagged with your registry account details and a hotfix identifier:
++
+----
+$ updated_container="<updated_container_registry>/<updated_container_project>/<container_image>:<hotfix_id>"
+$ container=$(buildah from <container_registry>/<container_project>/<container_image>:<container_tag>)
+$ buildah run --user root $container mkdir -p /<hotfix_id>/rpms
+$ buildah copy --user root $container <hotfix_id>/rpms/*.rpm /hotfix_id/rpms
+$ buildah run --user root rpm -F /<hotfix_id/rpms/*.rpm
+$ buildah commit $container $updated_container
+$ buildah push $updated_container
+----
++
+* Replace `<hotfix_id>` with a hotfix identifier such as a Jira issue, for example `osprh-0000`.
+* Replace `<updated_container_registry>` with a container registry to serve the updated container image. The OCP internal container image registry can be used.
+* Replace `<updated_container_project>` with a container project to use for the updated container image.
+* Replace `<container_project>` with the container project for the container being updated.
+* Replace `<container_registry>` with the container registry for the container being updated.
+* Replace `<container_image>` with the container image being updated.
+* Replace `<container_tag>` with the container tag being updated.
++
+[NOTE]
+The values for `<updated_container_registry>` and `<container_registry>` can be the same. The values for `<updated_container_project>` and `<container_project>` can be the same. The container images will be differentiated based on the value of their tags.
+
+. Hotfix the updated container image on the affected data plane nodes. Use the <<proc_hotfixing-the-data-plane-container-content-images,Hotfixing the data plane container content with images>> procedure to apply the hotfixed container image.

docs/assemblies/proc_hotfixing-the-data-plane-rpm-content.adoc

@@ -0,0 +1,45 @@
+[id="proc_hotfixing-the-data-plane-rpm-content-{context}"]
+= Hotfixing the data plane RPM content
+
+[role="_abstract"]
+
+You install RPM hotfix content directly on to the data plane nodes.
+
+.Procedure
+
+. Obtain the RPM hotfix content from the source and store it locally:
++
+----
+$ mkdir -p <hotfix_id>/rpms
+$ cp /path/to/hotfix/*.rpm <hotfix_id>/rpms
+----
++
+* Replace `<hotfix_id>` with a hotfix identifier such as a Jira issue, for example `osprh-0000`.
+
+. Copy the RPM hotfix content to the affected data plane nodes:
++
+----
+$ ssh <ssh_user>@<data_plane_node> mkdir -p /tmp/<hotfix_id>/rpms
+$ scp <hotfix_id>/rpms/*.rpm <ssh_user>@<data_plane_node>:/tmp/<hotfix_id>/rpms
+----
++
+* Replace `<ssh_user>` with the SSH user name.
+* Replace `<data_plane_node>` with the hostname or IP for the data plane node.
+* Replace `<hotfix_id>` with a hotfix identifier such as a Jira issue, for example `osprh-0000`.
+
++
+Repeat this step for each data plane node that the hotfix must be applied to.
+
+. Update the RPM hotfix content on the affected data plane nodes.
++
+----
+$ ssh <ssh_user>@<data_plane_node>
+$ sudo rpm -F /tmp/<hotfix_id>/rpms/*.rpm
+----
++
+* The `-F` (`--freshen`) `rpm` command option updates the RPM content if earlier versions are already installed.
+* Replace `<ssh_user>` with the SSH user name.
+* Replace `<data_plane_node>` with the hostname or IP for the data plane node.
+* Replace `<hotfix_id>` with a hotfix identifier such as a Jira issue, for example `osprh-0000`.
+
+. Perform any additional custom steps that are detailed in the hotfix instructions to complete the application of the RPM hotfix content.