Merge pull request #60212 from adellape/mv_colocation

Author: adellape

_topic_maps/_topic_map.yml

@@ -1664,6 +1664,8 @@ Topics:
       File: olm-understanding-dependency-resolution
     - Name: Operator groups
       File: olm-understanding-operatorgroups
+    - Name: Multitenancy and Operator colocation
+      File: olm-colocation
     - Name: Operator conditions
       File: olm-operatorconditions
     - Name: Metrics

modules/olm-colocation-namespaces.adoc

@@ -1,7 +1,6 @@
 // Module included in the following assemblies:
 //
-// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc
-// * operators/understanding/olm-multitenancy.adoc
+// * operators/understanding/olm/olm-colocation.adoc
 
 :_content-type: CONCEPT
 [id="olm-colocation-namespaces_{context}"]

modules/olm-installing-global-namespaces.adoc

@@ -6,7 +6,7 @@
 [id="olm-installing-global-namespaces_{context}"]
 = Installing global Operators in custom namespaces
 
-When installing Operators with the {product-title} web console, the default behavior installs Operators that support the *All namespaces* install mode into the default `openshift-operators` global namespace. This can cause issues related to shared install plans and update policies between all Operators in the namespace. For more details on these limitations, see "Colocation of Operators in a namespace".
+When installing Operators with the {product-title} web console, the default behavior installs Operators that support the *All namespaces* install mode into the default `openshift-operators` global namespace. This can cause issues related to shared install plans and update policies between all Operators in the namespace. For more details on these limitations, see "Multitenancy and Operator colocation".
 
 As a cluster administrator, you can bypass this default behavior manually by creating a custom global namespace and using that namespace to install your individual or scoped set of Operators and their dependencies.
 

operators/admin/olm-adding-operators-to-cluster.adoc

@@ -11,6 +11,11 @@ toc::[]
 
 Using Operator Lifecycle Manager (OLM), cluster administrators can install OLM-based Operators to an {product-title} cluster.
 
+[NOTE]
+====
+For information on how OLM handles updates for installed Operators colocated in the same namespace, as well as an alternative method for installing Operators with custom global Operator groups, see xref:../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Multitenancy and Operator colocation].
+====
+
 ifdef::openshift-origin[]
 [id="olm-adding-operators-to-a-cluster-prereqs"]
 == Prerequisites
@@ -21,6 +26,9 @@ If you have the pull secret, add the `redhat-operators` catalog to the `Operator
 endif::[]
 
 include::modules/olm-installing-operators-from-operatorhub.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
 * xref:../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub]
 
 include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+1]
@@ -67,7 +75,7 @@ When you initiate the Operator installation, if the Operator has dependencies, t
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-colocation-namespaces_olm-understanding-dependency-resolution[Colocation of Operators in a namespace]
+* xref:../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Multitenancy and Operator colocation]
 
 include::modules/olm-pod-placement.adoc[leveloffset=+1]
 

operators/admin/olm-upgrading-operators.adoc

@@ -8,6 +8,11 @@ toc::[]
 
 As a cluster administrator, you can update Operators that have been previously installed using Operator Lifecycle Manager (OLM) on your {product-title} cluster.
 
+[NOTE]
+====
+For information on how OLM handles updates for installed Operators colocated in the same namespace, as well as an alternative method for installing Operators with custom global Operator groups, see xref:../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Multitenancy and Operator colocation].
+====
+
 include::modules/olm-preparing-upgrade.adoc[leveloffset=+1]
 include::modules/olm-changing-update-channel.adoc[leveloffset=+1]
 include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+1]

operators/understanding/olm-multitenancy.adoc

@@ -13,7 +13,6 @@ Consider the following scenarios to determine which Operator installation workfl
 [role="_additional-resources"]
 .Additional resources
 * xref:../../operators/understanding/olm-common-terms.adoc#olm-common-terms-multitenancy_olm-common-terms[Common terms: Multitenant]
-* xref:../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-colocation-namespaces_olm-understanding-dependency-resolution[Colocation of Operators in a namespace]
 * xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-limitations[Limitations for multitenant Operator management]
 
 include::modules/olm-default-install-behavior.adoc[leveloffset=+1]
@@ -28,4 +27,11 @@ include::modules/olm-multitenancy-solution.adoc[leveloffset=+1]
 .Additional resources
 * xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-preparing-operators-multitenant_olm-adding-operators-to-a-cluster[Preparing for multiple instances of an Operator for multitenant clusters]
 * xref:../../operators/admin/olm-creating-policy.adoc#olm-creating-policy[Allowing non-cluster administrators to install Operators]
-* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-restricted-networks-operatorhub_olm-managing-custom-catalogs[Disabling the default OperatorHub catalog sources]
+* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-restricted-networks-operatorhub_olm-managing-custom-catalogs[Disabling the default OperatorHub catalog sources]
+
+[id="olm-colocation_{context}"]
+== Operator colocation and Operator groups
+
+Operator Lifecycle Manager (OLM) handles OLM-managed Operators that are installed in the same namespace, meaning their `Subscription` resources are colocated in the same namespace, as related Operators. Even if they are not actually related, OLM considers their states, such as their version and update policy, when any one of them is updated.
+
+For more information on Operator colocation and using Operator groups effectively, see xref:../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Operator Lifecycle Manager (OLM) -> Multitenancy and Operator colocation].

operators/understanding/olm/olm-colocation.adoc

@@ -0,0 +1,16 @@
+:_content-type: ASSEMBLY
+[id="olm-colocation"]
+= Multitenancy and Operator colocation
+include::_attributes/common-attributes.adoc[]
+:context: olm-colocation
+
+toc::[]
+
+This guide outlines multitenancy and Operator colocation in Operator Lifecycle Manager (OLM).
+
+include::modules/olm-colocation-namespaces.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-global-namespaces_olm-adding-operators-to-a-cluster[Installing global Operators in custom namespaces]
+* xref:../../../operators/understanding/olm-multitenancy.adoc#olm-multitenancy[Operators in multitenant clusters]

operators/understanding/olm/olm-understanding-dependency-resolution.adoc

@@ -32,10 +32,4 @@ include::modules/olm-dependencies-best-practices.adoc[leveloffset=+1]
 * Kubernetes documentation: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#readme[Changing the API]
 
 include::modules/olm-dependencies-caveats.adoc[leveloffset=+1]
-include::modules/olm-dependency-resolution-examples.adoc[leveloffset=+1]
-include::modules/olm-colocation-namespaces.adoc[leveloffset=+1]
-[role="_additional-resources"]
-.Additional resources
-
-* xref:../../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-global-namespaces_olm-adding-operators-to-a-cluster[Installing global Operators in custom namespaces]
-* xref:../../../operators/understanding/olm-multitenancy.adoc#olm-multitenancy[Operators in multitenant clusters]
+include::modules/olm-dependency-resolution-examples.adoc[leveloffset=+1]

operators/understanding/olm/olm-understanding-olm.adoc

@@ -30,15 +30,15 @@ include::modules/olm-subscription.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-colocation-namespaces_olm-understanding-dependency-resolution[Colocation of Operators in a namespace]
+* xref:../../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Multitenancy and Operator colocation]
 * xref:../../../operators/admin/olm-status.adoc#olm-status-viewing-cli_olm-status[Viewing Operator subscription status by using the CLI]
 
 include::modules/olm-installplan.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-colocation-namespaces_olm-understanding-dependency-resolution[Colocation of Operators in a namespace]
+* xref:../../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Multitenancy and Operator colocation]
 * xref:../../../operators/admin/olm-creating-policy.adoc#olm-creating-policy[Allowing non-cluster administrators to install Operators]
 
 include::modules/olm-operatorgroups-about.adoc[leveloffset=+2]

operators/understanding/olm/olm-understanding-operatorgroups.adoc

@@ -21,6 +21,7 @@ include::modules/olm-operatorgroups-limitations.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
+* xref:../../../operators/understanding/olm/olm-colocation.adoc#olm-colocation[Operator Lifecycle Manager (OLM) -> Multitenancy and Operator colocation].
 * xref:../../../operators/understanding/olm-multitenancy.adoc#olm-multitenancy[Operators in multitenant clusters]
 * xref:../../../operators/admin/olm-creating-policy.adoc#olm-creating-policy[Allowing non-cluster administrators to install Operators]