OSDOCS-17918: configuring external registry by skopacz1 · Pull Request #107199 · openshift/openshift-docs

skopacz1 · 2026-02-24T17:37:00Z

OSDOCS-17918

Version(s): 4.21+

This PR adds a doc for converting your cluster to use an external image registry

QE review:

QE has approved this change.

Preview: Configuring your cluster to use an external registry

openshift-ci-robot · 2026-02-24T17:37:04Z

@skopacz1: This pull request references OSDOCS-17918 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

Details

In response to this:

OSDOCS-17918

Version(s): 4.21+

This PR adds a doc for converting your cluster to use an external image registry

QE review:

QE has approved this change.

Preview:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

skopacz1 · 2026-02-24T17:38:12Z

+  - Name: Configuring your cluster to use an external registry
+    File: configuring-registry-external
+    Distros: openshift-enterprise


Now that I think about it, perhaps this doc would belong more in the disconnected environment docs. After all, all of the prereq tasks i link to are in this section already

@skopacz1 will this page must appear under the OVE docs? It's about on how to step-out from the feature and use your own images (note that the use of an external registry is required mostly in disconnected environments, but potentially it couldn't be in connected ones).

It would be tough to place them directly alongside the install docs for OVE because that procedure exists in the Agent install docs right now, and this is technically a post-install task. If we wanted all of these docs to exist together, we would want to talk with Michal and my content strategist about creating a new location for all the docs related to this feature suite.

The key point here is that this is not a "general" procedure potentially valid for any cluster, but only for those ones that have been installed thanks to the "I don't want to use an external registry" feature - and currently the only valid case is OVE.

That's a valid point. I have an admonition here warning users about that, but I can also add it to the prerequisites in the procedure itself.

Let me know if you think we need to make that point more clear some other way as well

It still looks a little bit weird, because by default a (connected) cluster installation does not require an external registry managed by the user (the customer can use quay.io).
The current article is valid only in the scope of the (let me use a tech term) NoRegistryClusterInstall feature - which in turn is meant to be used for disconnected baremetal clusters.

I can move this doc to the disconnected environment docs in that case. That was the other candidate for where to place this document, and your confirmation that this content is not applicable to connected use cases makes it seem like a better location that this section for registries in general

ocpdocs-previewbot · 2026-02-24T17:44:06Z

🤖 Mon Mar 02 21:37:31 - Prow CI generated the docs preview:

https://107199--ocpdocs-pr.netlify.app/openshift-enterprise/latest/disconnected/configuring-registry-external.html
https://107199--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_with_agent_based_installer/installing-ove.html

ocpdocs-vale-bot · 2026-02-24T17:44:57Z

+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 utilize a mirroring workflow for your image management.


🤖 [error] RedHat.TermsErrors: Use 'use' rather than 'utilize'. For more information, see RedHat.TermsErrors.

openshift-ci-robot · 2026-02-24T19:12:06Z

@skopacz1: This pull request references OSDOCS-17918 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

Details

In response to this:

OSDOCS-17918

Version(s): 4.21+

This PR adds a doc for converting your cluster to use an external image registry

QE review:

QE has approved this change.

Preview: Configuring your cluster to use an external registry

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

andfasano · 2026-02-25T14:23:26Z

+
+.Prerequisites
+
+* You have successfully performed a cluster update using images mirrored to your external image registry.


It may be worth noting, as an additional check, to ensure that the current clusterversion version resource is pointing to the new upgraded version. Not sure if it's too obvious, given the previous phrase

What would the command for that be? oc get clusterversion? I can add a statement here about using that command to double check

Yes. And the returned installed version must not be listed in the IRI status releases list.

andfasano · 2026-02-25T14:24:09Z

+
+.Procedure
+
+* Delete the by `InternalImageRegistry` custom resource running the following command:


Suggested change

* Delete the by `InternalImageRegistry` custom resource running the following command:

* Delete the singleton `InternalReleaseImage` resource by running the following command:

andfasano · 2026-02-25T14:25:44Z

+[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 `InternalImageRegistry` custom resource without first having completed the following tasks:


Suggested change

To prevent the accidental deletion of the cluster's internal image registry, you cannot delete the `InternalImageRegistry` custom resource without first having completed the following tasks:

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:

Thanks for catching this, idk where the first name came from to be honest 😅

andfasano · 2026-02-25T14:27:04Z

+
+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 `InternalImageRegistry` custom resource, which maintains an internal image registry in the cluster.


Suggested change

To do this, you must set up an external registry, successfully complete an update using images from the external registry, and finally delete `InternalImageRegistry` custom resource, which maintains an internal image registry in the cluster.

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.

andfasano · 2026-02-25T14:31:00Z

+  - Name: Configuring your cluster to use an external registry
+    File: configuring-registry-external
+    Distros: openshift-enterprise


@skopacz1 will this page must appear under the OVE docs? It's about on how to step-out from the feature and use your own images (note that the use of an external registry is required mostly in disconnected environments, but potentially it couldn't be in connected ones).

openshift-ci · 2026-03-02T21:38:59Z

@skopacz1: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

openshift-ci-robot · 2026-03-05T18:53:59Z

@skopacz1: This pull request references OSDOCS-17918 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

Details

In response to this:

OSDOCS-17918

Version(s): 4.21+

This PR adds a doc for converting your cluster to use an external image registry

QE review:

QE has approved this change.

Preview: [Configuring your cluster to use an external registry](Configuring your cluster to use an external registry)

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

openshift-ci-robot · 2026-03-05T18:54:08Z

@skopacz1: This pull request references OSDOCS-17918 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

Details

In response to this:

OSDOCS-17918

Version(s): 4.21+

This PR adds a doc for converting your cluster to use an external image registry

QE review:

QE has approved this change.

Preview: Configuring your cluster to use an external registry

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

mzasepaRedHat · 2026-04-09T09:12:24Z

@skopacz1 I have only one comment/question:

Should we align terminology related to different registry? External vs local vs internal registry. Is it unified in the official documentation?

During meetings, I use:

CC: @andfasano

skopacz1 · 2026-05-14T16:44:11Z

@mzasepaRedHat I think it would be a good idea to align the terminology, yes. Even better might be to create a small section where we define the different terms being used here and in the install doc. Do you think this alignment should be done in this PR, or would it be fine to address in another PR to ensure that this doc can be released in time for the 4.21 ISO release? I am currently working on other 4.22 things that might limit my capacity these next few weeks

mzasepaRedHat · 2026-05-15T07:49:15Z

@skopacz1 Bot options (this PR or a dedicated one) are fine. Up to you.
It will be great it this alignment can come together with 4.21 ISO.
If you are busy with 4.22, it's better to do it in the dedicated PR when you are available.

CC: @andfasano @zaneb

jeana-redhat · 2026-06-08T17:06:36Z

The branch/enterprise-5.0 label has been added to this PR.

This is because your PR targets the main branch and is labeled for branch/enterprise-4.22. And any PR going into main must also target the latest version branch (branch/enterprise-5.0).

If the update in your PR does NOT apply to version 5.0 onward, please re-target this PR to go directly into the appropriate enterprise- version branch or branches instead of main.

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Feb 24, 2026

openshift-ci Bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Feb 24, 2026

skopacz1 commented Feb 24, 2026

View reviewed changes

skopacz1 added branch/enterprise-4.21 branch/enterprise-4.22 labels Feb 24, 2026

skopacz1 added this to the Continuous Release milestone Feb 24, 2026

ocpdocs-vale-bot reviewed Feb 24, 2026

View reviewed changes

andfasano reviewed Feb 25, 2026

View reviewed changes

skopacz1 force-pushed the OSDOCS-17918 branch from 1ef7766 to fe31b0f Compare March 2, 2026 20:39

openshift-ci Bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Mar 2, 2026

OSDOCS-17918: configuring external registry

1fd432f

skopacz1 force-pushed the OSDOCS-17918 branch from fe31b0f to 1fd432f Compare March 2, 2026 21:31

openshift-ci Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Mar 2, 2026

mzasepaRedHat mentioned this pull request Apr 9, 2026

OSDOCS-17917: OVE ISO preconfig #106670

Open

1 task

jeana-redhat added the branch/enterprise-5.0 label Jun 8, 2026


		.Prerequisites

		* You have successfully performed a cluster update using images mirrored to your external image registry.


		.Procedure

		* Delete the by `InternalImageRegistry` custom resource running the following command:

	* Delete the by `InternalImageRegistry` custom resource running the following command:
	* Delete the singleton `InternalReleaseImage` resource by running the following command:

	To prevent the accidental deletion of the cluster's internal image registry, you cannot delete the `InternalImageRegistry` custom resource without first having completed the following tasks:
	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:

	To do this, you must set up an external registry, successfully complete an update using images from the external registry, and finally delete `InternalImageRegistry` custom resource, which maintains an internal image registry in the cluster.
	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.

Conversation

skopacz1 commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Feb 24, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andfasano Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andfasano Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ocpdocs-previewbot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci-robot commented Feb 24, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented Mar 2, 2026

Uh oh!

openshift-ci-robot commented Mar 5, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Mar 5, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mzasepaRedHat commented Apr 9, 2026

Uh oh!

skopacz1 commented May 14, 2026

Uh oh!

mzasepaRedHat commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeana-redhat commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

skopacz1 commented Feb 24, 2026 •

edited

Loading

openshift-ci-robot commented Feb 24, 2026 •

edited by openshift-ci Bot

Loading

andfasano Feb 25, 2026 •

edited

Loading

andfasano Feb 26, 2026 •

edited

Loading

ocpdocs-previewbot commented Feb 24, 2026 •

edited

Loading

openshift-ci-robot commented Feb 24, 2026 •

edited by openshift-ci Bot

Loading

openshift-ci-robot commented Mar 5, 2026 •

edited by openshift-ci Bot

Loading

openshift-ci-robot commented Mar 5, 2026 •

edited by openshift-ci Bot

Loading

mzasepaRedHat commented May 15, 2026 •

edited

Loading