From 1fd432f6552f626e4b38ac3d5f99dfc3e3aeefe0 Mon Sep 17 00:00:00 2001 From: Sebastian Kopacz Date: Tue, 24 Feb 2026 12:35:55 -0500 Subject: [PATCH] OSDOCS-17918: configuring external registry --- _topic_maps/_topic_map.yml | 3 ++ .../configuring-registry-external.adoc | 38 +++++++++++++++++++ .../installing-ove.adoc | 3 +- .../converting-external-registry-delete.adoc | 27 +++++++++++++ .../converting-external-registry-prereqs.adoc | 17 +++++++++ 5 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 disconnected/configuring-registry-external.adoc create mode 100644 modules/converting-external-registry-delete.adoc create mode 100644 modules/converting-external-registry-prereqs.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index cbde95719de1..2184c31c828b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -141,6 +141,9 @@ Topics: - Name: Using OLM in disconnected environments File: using-olm Distros: openshift-origin,openshift-enterprise +- Name: Configuring your cluster to use an external registry + File: configuring-registry-external + Distros: openshift-enterprise - Name: Updating a cluster in a disconnected environment Dir: updating Topics: diff --git a/disconnected/configuring-registry-external.adoc b/disconnected/configuring-registry-external.adoc new file mode 100644 index 000000000000..16fedb3302b8 --- /dev/null +++ b/disconnected/configuring-registry-external.adoc @@ -0,0 +1,38 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configuring-registry-external"] += Configuring your cluster to use an external registry +include::_attributes/common-attributes.adoc[] +:context: configuring-registry-external + +toc::[] + +[role="_abstract"] +If your cluster was installed without an external registry, you can configure the cluster to use an external registry as a postinstallation task in order to use a mirroring workflow for your image management. + +[IMPORTANT] +==== +This configuration is applicable only to clusters installed using the method described in xref:../installing/installing_with_agent_based_installer/installing-ove.adoc#installing-ove[Installing a cluster without an external registry]. +==== + +When you install a cluster using the method described in "Installing a cluster without an external registry", the cluster relies on images contained in the downloaded ISO for its lifecycle management. +However, you might want to configure your cluster to use an external image registry and mirror images to the registry instead. +To do this, you must set up an external registry, successfully complete an update using images from the external registry, and finally delete `InternalReleaseImage` custom resource, which maintains an internal image registry in the cluster. + +:FeatureName: Configuring your cluster to use an external registry +include::snippets/technology-preview.adoc[] + +// Pre-configuration tasks +include::modules/converting-external-registry-prereqs.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../disconnected/installing-mirroring-creating-registry.adoc#installing-mirroring-creating-registry[Creating a mirror registry with mirror registry for Red{nbsp}Hat OpenShift] +* xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[Mirroring images for a disconnected installation by using the oc-mirror plugin v2] +* xref:../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service] + +// Deleting the internal image registry +include::modules/converting-external-registry-delete.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../installing/installing_with_agent_based_installer/installing-ove.adoc#installing-ove[Installing a cluster without an external registry] \ No newline at end of file diff --git a/installing/installing_with_agent_based_installer/installing-ove.adoc b/installing/installing_with_agent_based_installer/installing-ove.adoc index fd5280448798..db215112c1ec 100644 --- a/installing/installing_with_agent_based_installer/installing-ove.adoc +++ b/installing/installing_with_agent_based_installer/installing-ove.adoc @@ -39,4 +39,5 @@ include::modules/installing-ove-console-final.adoc[leveloffset=+1] * xref:../../virt/creating_vm/virt-creating-vms-from-instance-types.adoc#virt-creating-vms-from-instance-types[Creating virtual machines from instance types] * xref:../../virt/creating_vm/virt-creating-vms-from-templates.adoc#virt-creating-vms-from-templates[Creating virtual machines from templates] * link:https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.8/html/installing_and_using_the_migration_toolkit_for_virtualization/migrating-vmware[Migrating virtual machines from VMware vSphere (Migration Toolkit for Virtualization documentation)] -* link:https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.8/html/installing_and_using_the_migration_toolkit_for_virtualization/migrating-rhv_rhv[Migrating virtual machines from Red{nbsp}Hat Virtualization (Migration Toolkit for Virtualization documentation)] \ No newline at end of file +* link:https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/2.8/html/installing_and_using_the_migration_toolkit_for_virtualization/migrating-rhv_rhv[Migrating virtual machines from Red{nbsp}Hat Virtualization (Migration Toolkit for Virtualization documentation)] +* xref:../../disconnected/configuring-registry-external.adoc#configuring-registry-external[Configuring your cluster to use an external registry] \ No newline at end of file diff --git a/modules/converting-external-registry-delete.adoc b/modules/converting-external-registry-delete.adoc new file mode 100644 index 000000000000..7d933549beb6 --- /dev/null +++ b/modules/converting-external-registry-delete.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: PROCEDURE +[id="converting-external-registry-delete_{context}"] += Deleting the internal image registry + +[role="_abstract"] +You can complete configuring your cluster to use an external image registry by deleting the resource responsible for maintaining the internal image registry that was installed on your cluster. + +.Prerequisites + +* You installed your cluster using the method described in "Installing a cluster without an external registry". +* You have successfully performed a cluster update using images mirrored to your external image registry. +You can ensure that your cluster has been updated to this new version by running the `oc get clusterversion` command. ++ +[IMPORTANT] +==== +The version you updated your cluster to must not be listed in the `status.releases` field of the `InternalReleaseImage` custom resource (CR). +You can check the contents of the CR by running the `oc get InternalReleaseImage -o yaml` command. +==== + +.Procedure + +* Delete the singleton `InternalReleaseImage` CR by running the following command: ++ +[source,terminal] +---- +$ oc delete internalreleaseimages cluster +---- \ No newline at end of file diff --git a/modules/converting-external-registry-prereqs.adoc b/modules/converting-external-registry-prereqs.adoc new file mode 100644 index 000000000000..251ebdb16032 --- /dev/null +++ b/modules/converting-external-registry-prereqs.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: CONCEPT +[id="converting-external-registry-prereqs_{context}"] += Pre-configuration tasks + +[role="_abstract"] +Before you can configure your cluster to use an external registry, you must prepare your environment with an image registry and perform an update using images on the registry. + +To prevent the accidental deletion of the cluster's internal image registry, you cannot delete the `InternalReleaseImage` custom resource without first having completed the following tasks: + +* You have created a mirror registry in your environment. +For more information, see "Creating a mirror registry with mirror registry for Red{nbsp}Hat OpenShift". + +* You have mirrored images to the mirror registry. +For more information, see "Mirroring images for a disconnected installation by using the oc-mirror plugin v2". + +* You have updated your cluster using the images you mirrored to your registry. +For more information, see "Updating a cluster in a disconnected environment using the OpenShift Update Service". \ No newline at end of file