Document hotfix process

Signed-off-by: James Slagle <[email protected]>

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,21 @@
+[id="assembly_hotfixing-the-data-plane"]
+= Hotfixing the data plane
+
+:context: dataplane
+
+[role="_abstract"]
+The OpenStack DataPlane can be updated when hotfix content is available. Hotfix content
+can be delivered as RPM packages or container images. How the software is
+installed on the data plane nodes determines how the hotfix content needs to be
+applied.
+
+include::proc_hotfixing-the-data-plane-rpm-content.adoc[leveloffset=+1]
+
+Container hotfix content needs to be applied to the data plane nodes such that
+any running containers are updated to run from container images where the
+hotfix content has been applied. Container hotfix content could be delivered as
+either RPM's or already updated container images.
+
+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 already hotfixed container image
+* Replace `<container_project>` with the source project for the already hotfixed container image
+* Replace `<container_image>` with the already hotfixed container image
+* Replace `<container_tag>` with the tag being for the already hotfixed container image
+* Replace `<updated_container_registry>` with a container registry to serve the hotfixed container image. The OCP internal container image registry can be used.
+* 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. See <<_customizing_container_image_locations>> on how to set the hotfixed container locations.
+
+. Create a new `OpenStackDataPlaneDeployment` resource that deploys the affected `OpenStackDataPlaneNodeSet` resources. See <<proc_deploying-the-data-plane_{context}>> on how to create `OpenStackDataPlaneDeployment` resources.
++
+[NOTE]
+The list of services can be restricted for the `OpenStackDataPlaneDeployment` to just those affected by the hotfix by using the `servicesOverride` field. See <<_overriding_services_for_the_deployment>>.

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

@@ -0,0 +1,46 @@
+[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, container images must be
+updated 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,42 @@
+[id="proc_hotfixing-the-data-plane-rpm-content-{context}"]
+= Hotfixing the data plane RPM content
+
+[role="_abstract"]
+
+RPM hotfix content is installed 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 `<hotfix_id>` with a hotfix identifier such as a Jira issue, for example `osprh-0000`
+* Replace `<ssh_user>` with the user name used for SSH
+* Replace `<data_plane_node>` with the hostname or IP for the data plane node.
+* Repeat the command for each affected data plane node.
+
+. Update the RPM hotfix content on the affected data plane nodes.
++
+----
+$ ssh <ssh_user>@<data_plane_node>
+$ sudo rpm -F /tmp/hotfix-rpms/*.rpm
+----
++
+* The `-F` (`--freshen`) `rpm` command option will update the RPM content if earlier versions are already installed.
+
+. Complete any remaining custom steps to apply the RPM hotfix content
++
+In some cases, custom steps may be required to complete applying the hotfix content. This may include restarting `systemd` services or other steps. Refer to the instructions that accompanied the hotifx and complete any necessary steps.