openshift · skopacz1 · Jul 27, 2026 · Jul 27, 2026
diff --git a/disconnected/about.adoc b/disconnected/about.adoc
@@ -6,56 +6,23 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 A disconnected environment is an environment that does not have full access to the internet.
 
 {product-title} is designed to perform many automatic functions that depend on an internet connection, such as retrieving release images from a registry or retrieving update paths and recommendations for the cluster.
 Without a direct internet connection, you must perform additional setup and configuration for your cluster to maintain full functionality in the disconnected environment.
 
-[id="glossary-disconnected_{context}"]
-== Glossary of disconnected environment terms
+//Glossary of disconnected environment terms
+include::modules/glossary-discc-env-terms.adoc[leveloffset=+1]
 
-Although it is used throughout the {product-title} documentation, _disconnected environment_ is a broad term that can refer to environments with various levels of internet connectivity.
-Other terms are sometimes used to refer to a specific level of internet connectivity, and these environments might require additional unique configurations.
+//Preferred methods for working with disconnected environments
+include::modules/pref-methods-working-discc-env.adoc[leveloffset=+1]
 
-The following table describes the different terms used to refer to environments without a full internet connection:
+[role='_additional-resources']
+[id="about-additional-resources_{context}"]
+== Additional resources
+* 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]
 
-.Disconnected environment terms
-[cols=".^2,.^4",options="header"]
-|====
-|Term |Description
+* xref:../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#installing-with-agent-based-installer[Installing a cluster with customizations]
 
-|Air-gapped network
-|An environment or network that is completely isolated from an external network.
-
-This isolation depends on a physical separation, or an "air gap", between machines on the internal network and any other part of an external network.
-Air-gapped environments are often used in industries with strict security or regulatory requirements.
-
-|Disconnected environment
-|An environment or network that has some level of isolation from an external network.
-
-This isolation could be enabled by physical or logical separation between machines on the internal network and an external network.
-Regardless of the level of isolation from the external network, a cluster in a disconnected environment does not have access to public services hosted by Red{nbsp}Hat and requires additional setup to maintain full cluster functionality.
-
-|Restricted Network
-|An environment or network with limited connection to an external network.
-
-A physical connection may exist between machines on the internal network and an external network, but network traffic is limited by additional configurations, such as with firewalls and proxies.
-|====
-
-[id="preferred-methods_{context}"]
-== Preferred methods for working with disconnected environments
-
-// Not sure about the heading above, I'm trying to find some phrasing that basically says "You should probably use these things if you don't have a strong reason to go with other options".
-
-You can choose between multiple options for most aspects of managing a cluster in a disconnected environment.
-For example, when mirroring images you can choose between using the oc-mirror {oc-first} plugin or using the `oc adm` command.
-
-However, some options provide a simpler and more convenient user experience for disconnected environments, and are the preferred method over their alternatives.
-
-Unless your organizational needs require you to choose another option, use the following methods for mirroring images, installing your cluster, and updating your cluster:
-
-* Mirror your images using the xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[oc-mirror plugin v2].
-
-* Install your cluster using the xref:../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc#installing-with-agent-based-installer[Agent-based Installer].
-
-* Update your cluster using a xref:../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[local OpenShift Update Service instance].
+* xref:../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
diff --git a/disconnected/using-olm.adoc b/disconnected/using-olm.adoc
@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 For {product-title} clusters in disconnected environments, Operator Lifecycle Manager (OLM) by default cannot access the Red{nbsp}Hat-provided software catalog sources hosted on remote registries because those remote sources require full internet connectivity.
 
 However, as a cluster administrator you can still enable your cluster to use OLM in a disconnected environment if you have a workstation that has full internet access. The workstation, which requires full internet access to pull the remote software catalog content, is used to prepare local mirrors of the remote sources, and push the content to a mirror registry.
@@ -27,52 +28,45 @@ While OLM can manage Operators from local sources, the ability for a given Opera
 * List any related images, or other container images that the Operator might require to perform their functions, in the `relatedImages` parameter of its `ClusterServiceVersion` (CSV) object.
 * Reference all specified images by a digest (SHA) and not by a tag.
 
-You can search software on the link:https://catalog.redhat.com/software/search?p=1&deployed_as=Operator&type=Containerized%20application&badges_and_features=Disconnected[Red{nbsp}Hat Ecosystem Catalog] for a list of Red{nbsp}Hat Operators that support running in disconnected mode by filtering with the following selections:
+You can search software on the Red{nbsp}Hat Ecosystem Catalog for a list of Red{nbsp}Hat Operators that support running in disconnected mode by filtering with the following selections:
 
 [horizontal]
 Type:: Containerized application
 Deployment method:: Operator
 Infrastructure features:: Disconnected
+
+For more information, see "Red{nbsp}Hat Ecosystem Catalog".
 ====
 
 [role="_additional-resources"]
 .Additional resources
+* link:https://catalog.redhat.com/software/search?p=1&deployed_as=Operator&type=Containerized%20application&badges_and_features=Disconnected[Red{nbsp}Hat Ecosystem Catalog]
 
-* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red{nbsp}Hat-provided Operator catalogs]
-
-[id="olm-restricted-network-prereqs"]
-== Prerequisites
-
-* You are logged in to your {product-title} cluster as a user with `cluster-admin` privileges.
-
-* If you are using OLM in a disconnected environment on {ibm-z-name}, you must have at least 12 GB allocated to the directory where you place your registry.
+//Prerequisites
+include::modules/prereq-olm.adoc[leveloffset=+1]
 
+//Disabling the default software catalog sources
 include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+1]
 
-[id="olm-mirror-catalog_olm-restricted-networks"]
-== Mirroring an Operator catalog
-
-For instructions about mirroring Operator catalogs for use with disconnected clusters, see xref:../disconnected/installing-mirroring-installation-images.adoc#olm-mirror-catalog_installing-mirroring-installation-images[Mirroring Operator catalogs for use with disconnected clusters].
-
-[IMPORTANT]
-====
-As of {product-title} 4.11, the default Red{nbsp}Hat-provided Operator catalog releases in the file-based catalog format. The default Red{nbsp}Hat-provided Operator catalogs for {product-title} 4.6 through 4.10 released in the deprecated SQLite database format.
+//Mirroring an Operator catalog
+include::modules/mirroring-operator-catalog.adoc[leveloffset=+1]
 
-The `opm` subcommands, flags, and functionality related to the SQLite database format are also deprecated and will be removed in a future release. The features are still supported and must be used for catalogs that use the deprecated SQLite database format.
-
-Many of the `opm` subcommands and flags for working with the SQLite database format, such as `opm index prune`, do not work with the file-based catalog format. For more information about working with file-based catalogs, see xref:../operators/understanding/olm-packaging-format.adoc#olm-file-based-catalogs_olm-packaging-format[Operator Framework packaging format], xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-fb[Managing custom catalogs], and 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].
-====
+[role="_additional-resources"]
+.Additional resources
+* xref:../disconnected/installing-mirroring-installation-images.adoc#olm-mirror-catalog_installing-mirroring-installation-images[Mirroring Operator catalogs for use with disconnected clusters]
+* xref:../operators/understanding/olm-packaging-format.adoc#olm-file-based-catalogs_olm-packaging-format[Operator Framework packaging format]
+* xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-fb[Managing custom catalogs]
+* 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]
 
+//Adding a catalog source to a cluster
 include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
-.Additional resources
+[id="using-olm-additional-resources_{context}"]
+== Additional resources
 
+* xref:../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red{nbsp}Hat-provided Operator catalogs]
 * xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]
 * xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource-image-template_olm-understanding-olm[Image template for custom catalog sources]
 * xref:../openshift_images/managing_images/image-pull-policy.adoc#image-pull-policy[Image pull policy]
-
-[id="next-steps_olm-restricted-networks"]
-== Next steps
-
-* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators]
+* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Update installed Operators]
diff --git a/modules/glossary-discc-env-terms.adoc b/modules/glossary-discc-env-terms.adoc
@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// * disconnected/mirroring/about.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="glossary-disconnected_{context}"]
+= Glossary of disconnected environment terms
+
+[role="_abstract"]
+Although it is used throughout the {product-title} documentation, _disconnected environment_ is a broad term that can refer to environments with various levels of internet connectivity.
+Other terms are sometimes used to refer to a specific level of internet connectivity, and these environments might require additional unique configurations.
+
+The following table describes the different terms used to refer to environments without a full internet connection:
+
+.Disconnected environment terms
+[cols=".^2,.^4",options="header"]
+|====
+|Term |Description
+
+|Air-gapped network
+|An environment or network that is completely isolated from an external network.
+
+This isolation depends on a physical separation, or an "air gap", between machines on the internal network and any other part of an external network.
+Air-gapped environments are often used in industries with strict security or regulatory requirements.
+
+|Disconnected environment
+|An environment or network that has some level of isolation from an external network.
+
+This isolation could be enabled by physical or logical separation between machines on the internal network and an external network.
+Regardless of the level of isolation from the external network, a cluster in a disconnected environment does not have access to public services hosted by Red{nbsp}Hat and requires additional setup to maintain full cluster functionality.
+
+|Restricted Network
+|An environment or network with limited connection to an external network.
+
+A physical connection may exist between machines on the internal network and an external network, but network traffic is limited by additional configurations, such as with firewalls and proxies.
+|====
diff --git a/modules/mirroring-operator-catalog.adoc b/modules/mirroring-operator-catalog.adoc
@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * disconnected/mirroring/using-olm.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="olm-mirror-catalog_{context}"]
+= Mirroring an Operator catalog
+
+[role="_abstract"]
+For instructions about mirroring Operator catalogs for use with disconnected clusters, see "Mirroring Operator catalogs for use with disconnected clusters".
+
+[IMPORTANT]
+====
+As of {product-title} 4.11, the default Red{nbsp}Hat-provided Operator catalog releases in the file-based catalog format. The default Red{nbsp}Hat-provided Operator catalogs for {product-title} 4.6 through 4.10 released in the deprecated SQLite database format.
+
+The `opm` subcommands, flags, and functionality related to the SQLite database format are also deprecated and will be removed in a future release. The features are still supported and must be used for catalogs that use the deprecated SQLite database format.
+
+Many of the `opm` subcommands and flags for working with the SQLite database format, such as `opm index prune`, do not work with the file-based catalog format. For more information about working with file-based catalogs, see "Operator Framework packaging format", "Managing custom catalogs", and "Mirroring images for a disconnected installation by using the oc-mirror plugin v2".
+====