diff --git a/disconnected/updating/disconnected-update.adoc b/disconnected/updating/disconnected-update.adoc index 695739c17245..2abd27e2a839 100644 --- a/disconnected/updating/disconnected-update.adoc +++ b/disconnected/updating/disconnected-update.adoc @@ -12,24 +12,22 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] +You can update a cluster in a disconnected environment without using the OpenShift Update Service by using the CLI. + Use the following procedures to update a cluster in a disconnected environment without access to the OpenShift Update Service. -== Prerequisites - -* You must have the `oc` command-line interface (CLI) tool installed. -* You must provision a local container image registry with the container images for your update, as described in xref:../../disconnected/updating/mirroring-image-repository.adoc#mirroring-ocp-image-repository[Mirroring {product-title} images]. -* You must have access to the cluster as a user with `admin` privileges. -See xref:../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define and apply permissions]. -* You must have a recent xref:../../backup_and_restore/control_plane_backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your update fails and you must xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. -* You have updated all Operators previously installed through Operator Lifecycle Manager (OLM) to a version that is compatible with your target release. Updating the Operators ensures they have a valid update path when the default catalog sources switch from the current minor version to the next during a cluster update. See xref:../../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] for more information on how to check compatibility and, if necessary, update the installed Operators. -* You must ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. -* If your cluster uses manually maintained credentials, update the cloud provider resources for the new release. For more information, including how to determine if this is a requirement for your cluster, see xref:../../updating/preparing_for_updates/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]. -* If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the update process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain. - -[NOTE] -==== -If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the update process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain. -==== +// Prerequisites for updating a cluster in a disconnected environment +include::modules/updating-without-osus-prereqs.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../../disconnected/updating/mirroring-image-repository.adoc#mirroring-ocp-image-repository[Mirroring {product-title} images] +* xref:../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define and apply permissions] +* xref:../../backup_and_restore/control_plane_backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] +* xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state] +* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] +* xref:../../updating/preparing_for_updates/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials] // Pausing a MachineHealthCheck resource include::modules/machine-health-checks-pausing.adoc[leveloffset=+1] diff --git a/modules/generating-icsp-object-scoped-to-a-registry.adoc b/modules/generating-icsp-object-scoped-to-a-registry.adoc index 46a7228c60fc..dcc5249d20d3 100644 --- a/modules/generating-icsp-object-scoped-to-a-registry.adoc +++ b/modules/generating-icsp-object-scoped-to-a-registry.adoc @@ -6,6 +6,7 @@ [id="generating-icsp-object-scoped-to-a-registry_{context}"] = Widening the scope of the mirror image catalog to reduce the frequency of cluster node reboots +[role="_abstract"] You can scope the mirrored image catalog at the repository level or the wider registry level. A widely scoped `ImageContentSourcePolicy` resource reduces the number of times the nodes need to reboot in response to changes to the resource. To widen the scope of the mirror image catalog in the `ImageContentSourcePolicy` resource, perform the following procedure. diff --git a/modules/images-configuration-registry-mirror-convert.adoc b/modules/images-configuration-registry-mirror-convert.adoc index 92b22ba7674a..3e510b89cb87 100644 --- a/modules/images-configuration-registry-mirror-convert.adoc +++ b/modules/images-configuration-registry-mirror-convert.adoc @@ -8,6 +8,8 @@ = Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring [role="_abstract"] +You can convert existing `ImageContentSourcePolicy` (ICSP) files to `ImageDigestMirrorSet` files to configure image registry repository mirroring. + Using an `ImageContentSourcePolicy` (ICSP) object to configure repository mirroring is a deprecated feature. This functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. diff --git a/modules/images-configuration-registry-mirror.adoc b/modules/images-configuration-registry-mirror.adoc index ee70dded56ce..2f819b1b4634 100644 --- a/modules/images-configuration-registry-mirror.adoc +++ b/modules/images-configuration-registry-mirror.adoc @@ -13,6 +13,8 @@ endif::[] = Understanding image registry repository mirroring [role="_abstract"] +You must mirror images to update clusters in disconnected environments. + By setting up container registry repository mirroring, you can perform the following tasks: * Configure your {product-title} cluster to redirect requests to pull images from a repository on a source image registry and have it resolved by a repository on a mirrored image registry. diff --git a/modules/update-restricted-image-digests.adoc b/modules/update-restricted-image-digests.adoc index fb58aee26631..881dec6e34ce 100644 --- a/modules/update-restricted-image-digests.adoc +++ b/modules/update-restricted-image-digests.adoc @@ -6,6 +6,7 @@ [id="update-disconnected-image-digests_{context}"] = Retrieving a release image digest +[role="_abstract"] In order to update a cluster in a disconnected environment using the `oc adm upgrade` command with the `--to-image` option, you must reference the sha256 digest that corresponds to your targeted release image. .Procedure diff --git a/modules/update-restricted.adoc b/modules/update-restricted.adoc index c0225387eddc..31241b9c9983 100644 --- a/modules/update-restricted.adoc +++ b/modules/update-restricted.adoc @@ -6,6 +6,7 @@ [id="update-disconnected_{context}"] = Updating the disconnected cluster +[role="_abstract"] Update the disconnected cluster to the {product-title} version that you downloaded the release images for. //TODO: Add xrefs in the following note when functionality is enabled. diff --git a/modules/updating-without-osus-prereqs.adoc b/modules/updating-without-osus-prereqs.adoc new file mode 100644 index 000000000000..7f0d4185d48a --- /dev/null +++ b/modules/updating-without-osus-prereqs.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: REFERENCE +[id="updating-cli-prereqs_{context}"] += Prerequisites for a cluster update + +[role="_abstract"] +You must meet the following prerequisites before updating a cluster in a disconnected environment. + +* You must have the `oc` command-line interface (CLI) tool installed. +* You must provision a local container image registry with the container images for your update, as described in "Mirroring {product-title} images". +* You must have access to the cluster as a user with `admin` privileges. +See "Using RBAC to define and apply permissions". +* You must have a recent "etcd backup" in case your update fails and you must "restore your cluster to a previous state". +* You have updated all Operators previously installed through Operator Lifecycle Manager (OLM) to a version that is compatible with your target release. Updating the Operators ensures they have a valid update path when the default catalog sources switch from the current minor version to the next during a cluster update. See "Updating installed Operators" for more information on how to check compatibility and, if necessary, update the installed Operators. +* You must ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. +* If your cluster uses manually maintained credentials, update the cloud provider resources for the new release. For more information, including how to determine if this is a requirement for your cluster, see "Preparing to update a cluster with manually maintained credentials". +* If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the update process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain. + +[NOTE] +==== +If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the update process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain. +==== \ No newline at end of file