OSDOCS-17918: configuring external registry

_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:

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]

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)]
+* 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]

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
+----

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".