OSDOCS-15793: modularizes Operators assemblies MicroShift

Author: ShaunaDiaz

microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc

@@ -6,20 +6,20 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can use OLM-based Operators in disconnected situations by embedding them in a {op-system-ostree-first} image.
+[role="_abstract"]
+You can use Operators managed by Operator Lifecycle Manager (OLM) for various tasks in disconnected situations by embedding them in a {op-system-ostree-first} image.
 
-//Using OLM disconnected
 include::modules/microshift-olm-deploy-op-disconnected-con.adoc[leveloffset=+1]
 
-//additional resources for embedding operators into rhel for edge disconnected
-[role="_additional-resources"]
-.Additional resources
-* link:https://access.redhat.com/documentation/en-us/red_hat_build_of_microshift/{ocp-version}/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree#microshift-creating-ostree-iso_microshift-embed-in-rpm-ostree[Creating the RHEL for Edge image]
-* xref:../../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use]
-* xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-networking-disconnected-hosts[Configuring network settings for fully disconnected hosts]
-
 include::modules/microshift-oc-mirror-dry-run.adoc[leveloffset=+2]
 
 include::modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc[leveloffset=+2]
 
 include::modules/microshift-ops-config-embed-ostree.adoc[leveloffset=+2]
+
+[id="additional-resources_microshift-operators-oc-mirror-disconnected"]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use]
+* xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-networking-disconnected-hosts[Configuring network settings for fully disconnected hosts]

microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc

@@ -6,7 +6,8 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can create custom catalogs with widely available Operators and mirror them by using the oc-mirror {oc-first} plugin.
+[role="_abstract"]
+You can create custom catalogs with widely available Operators and mirror them by using the oc-mirror {oc-first} plugin. Custom catalogs give you the tool so that you can host Operators locally, or control a variety of factors, such as versions and access.
 
 include::modules/microshift-olm-rh-ops-mirror.adoc[leveloffset=+1]
 

microshift_running_apps/microshift_operators/microshift-operators-olm.adoc

@@ -6,58 +6,28 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-Operator Lifecycle Manager (OLM) is used in {microshift-short} for installing and running optional add-on Operators. See the following link for more information:
+[role="_abstract"]
+You can use Operator Lifecycle Manager (OLM) with {microshift-short} to install and run optional add-on Operators.
 
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/operators/understanding-operators#operator-lifecycle-manager-olm[Operator Lifecycle Manager]
+include::modules/microshift-olm-considerations.adoc[leveloffset=+1]
 
-[id="microshift-olm-considerations_{context}"]
-== Considerations for using OLM with {microshift-short}
-
-* Cluster Operators as applied in {ocp} are not used in {microshift-short}.
-* You must create your own catalogs for the add-on Operators you want to use with your applications. Catalogs are not provided by default.
-** Each catalog must have an accessible `CatalogSource` added to a node, so that the OLM catalog Operator can use the catalog for content.
-* You must use the CLI to conduct OLM activities with {microshift-short}. The console and OperatorHub GUIs are not available.
-** Use the link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/cli_tools/opm-cli#cli-opm-install[Operator Package Manager `opm` CLI] with a network-connected node, or for building catalogs for custom Operators that use an internal registry.
-** To mirror your catalogs and Operators for disconnected or offline nodes, install link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/disconnected_environments/index#installation-oc-mirror-installing-plugin_about-installing-oc-mirror-v2.
-
-[IMPORTANT]
-====
-Before using an Operator, verify with the provider that the Operator is supported on {product-title}.
-====
-
-[id="microshift-installing-olm-options_{context}"]
-== Determining your OLM installation type
-You can install the OLM package manager for use with {microshift-short} 4.15 or newer versions. There are different ways to install OLM for a {microshift-short} node, depending on your use case.
-
-* You can install the `microshift-olm` RPM at the same time you install the {microshift-short} RPM on {op-system-base-full}.
-* You can install the `microshift-olm` on an existing {microshift-short} {product-version}. Restart the {microshift-short} service after installing OLM for the changes to apply.
-See xref:../../microshift_install_rpm/microshift-install-rpm.adoc#microshift-install-rpms-olm_microshift-install-rpm[Installing the Operator Lifecycle Manager (OLM) from an RPM package].
-* You can embed OLM in a {op-system-ostree-first} image. See xref:../../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree.adoc#microshift-adding-olm-to-blueprint_microshift-embed-in-rpm-ostree[Adding the Operator Lifecycle Manager (OLM) service to a blueprint].
+include::modules/microshift-installing-olm-options.adoc[leveloffset=+1]
 
 include::modules/microshift-olm-namespaces.adoc[leveloffset=+1]
 
 include::modules/microshift-olm-build-op-catalogs.adoc[leveloffset=+1]
 
-//additional resources for building catalogs module
-[role="_additional-resources"]
-.Additional resources
-* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/cli_tools/opm-cli[`opm` CLI reference]
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/operators/index#olm-about-catalogs_olm-rh-catalogs[About Operator catalogs]
-* To create file-based catalogs by using the `opm` CLI, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-managing-custom-catalogs[Managing custom catalogs]
-
 include::modules/microshift-olm-deploy-ops-con.adoc[leveloffset=+1]
 
-//additional resources for deploying operators concept module
-[role="_additional-resources"]
-.Additional resources
-* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/operators/index#olm-operatorgroups-membership_olm-understanding-operatorgroups[Operator group membership]
-
 include::modules/microshift-olm-deploy-ops-global-ns.adoc[leveloffset=+2]
 
 include::modules/microshift-olm-deploy-ops-spec-ns.adoc[leveloffset=+2]
 
-//additional resources for working with operators after deployment
+[id="Additional-resources_microshift-operators-oc-mirror_{context}"]
 [role="_additional-resources"]
-.Additional resources
+== Additional resources
+
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/understanding-operators#operator-lifecycle-manager-olm[Operator Lifecycle Manager]
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/cli_tools/opm-cli[`opm` CLI reference]
 * link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-upgrading-operators[Updating installed Operators]
 * link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-deleting-operator-from-a-cluster-using-cli_olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster using the CLI]

microshift_running_apps/microshift_operators/microshift-operators.adoc

@@ -1,30 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
-[id="operators-with-microshift"]
+[id="microshift-operators"]
 = Using Operators with {microshift-short}
 include::_attributes/attributes-microshift.adoc[]
-:context: operators-microshift
+:context: microshift-operators
 
 toc::[]
 
-You can use Operators with {microshift-short} to create applications that monitor the running services in your node. Operators can manage applications and their resources, such as deploying a database or message bus. As customized software running inside your node, Operators can be used to implement and automate common operations.
+[role="_abstract"]
+You can use Operators with {microshift-short} to create applications that monitor the running services in your node. As customized software running inside your node, you can use Operators to implement and automate common operations.
 
-Operators offer a more localized configuration experience and integrate with Kubernetes APIs and CLI tools such as `kubectl` and `oc`. Operators are designed specifically for your applications. Operators enable you to configure components instead of modifying a global configuration file.
+include::modules/microshift-about-using-operators.adoc[leveloffset=+1]
 
-{microshift-short} applications are generally expected to be deployed in static environments. However, Operators are available if helpful in your use case. To determine the compatibility of an Operator with {microshift-short}, check the Operator documentation.
-
-[id="microshift-operators-installation-paths_{context}"]
-== How to use Operators with a {microshift-short} node
-
-There are two ways to use Operators for your {microshift-short} node:
-
-[id="microshift-operators-paths-manifests_{context}"]
-=== Manifests for Operators
-Operators can be installed and managed directly by using manifests. You can use the `kustomize` configuration management tool with {microshift-short} to deploy an application. Use the same steps to install Operators with manifests.
-
-* See xref:../../microshift_running_apps/microshift-applications.adoc#microshift-manifests-overview_applications-microshift[Using Kustomize manifests to deploy applications] and xref:../../microshift_running_apps/microshift-applications.adoc#microshift-applying-manifests-example_applications-microshift[Using manifests example] for details.
-
-[id="microshift-operators-paths-olm_{context}"]
-=== Operator Lifecycle Manager for Operators
-You can also install add-on Operators to a {microshift-short} node by using Operator Lifecycle Manager (OLM). OLM can be used to manage both custom Operators and Operators that are widely available. Building catalogs is required to use OLM with {microshift-short}.
-
-* For details, see xref:../../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}].
+include::modules/microshift-operators-how-to-install-and-manage.adoc[leveloffset=+1]

modules/microshift-about-using-operators.adoc

@@ -0,0 +1,14 @@
+//Module included in the following assemblies:
+//
+//* microshift_running_apps/microshift_operators/microshift-operators.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-about-using-operators_{context}"]
+= About using Operators with a {microshift-short} node
+
+[role="_abstract"]
+You can use Operators to manage applications and their resources, such as deploying a database or message bus.
+
+Operators offer a more localized configuration experience and integrate with Kubernetes APIs and CLI tools such as `kubectl` and `oc`. You can design or use Operators that are specifically for your applications. By using Operators, you can configure components instead of modifying a global configuration file.
+
+{microshift-short} applications are generally expected to be deployed in static environments. However, Operators are available if helpful in your use case. To discover whether an Operator is compatible with {microshift-short}, check the Operator documentation.

modules/microshift-installing-olm-options.adoc

@@ -0,0 +1,16 @@
+//Module included in the following assemblies:
+//
+//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-installing-olm-options_{context}"]
+= Determining your OLM installation type
+
+[role="_abstract"]
+You can install Operator Lifecycle Manager (OLM) for use with {microshift-short} 4.16 or newer versions. There are different ways to install OLM for a {microshift-short} node, depending on your use case.
+
+* You can install the `microshift-olm` RPM at the same time you install the {microshift-short} RPM on {op-system-base-full}.
+* You can install the `microshift-olm` on an existing {microshift-short} {product-version}. Restart the {microshift-short} service after installing OLM for the changes to apply.
+* See the following links for specifics on each installation type:
+** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.20/html/installing_optional_rpm_packages/microshift-install-optional-rpms#microshift-installing-with-olm-from-rpm-package_microshift-install-optional-rpm[Installing the Operator Lifecycle Manager (OLM) from an RPM package]
+** link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/4.20/html/embedding_in_a_rhel_for_edge_image/microshift-embed-in-rpm-ostree#microshift-adding-other-services-to-blueprint_microshift-embed-in-rpm-ostree[Adding other packages to a blueprint]

modules/microshift-oc-mirror-about-con.adoc

@@ -6,6 +6,7 @@
 [id="microshift-using-oc-mirror_{context}"]
 = About the oc-mirror plugin for creating a mirror registry
 
-You can use the oc-mirror OpenShift CLI (oc) plugin with {microshift-short} to filter and delete images from Operator catalogs. You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments.
+[role="_abstract"]
+You can use the oc-mirror {oc-first} plugin with {microshift-short} to filter and delete images from Operator catalogs. You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments.
 
 The procedure to mirror content from Red Hat-hosted registries connected to the internet to a disconnected image registry is the same, independent of the registry you select. After you mirror the contents of your catalog, configure each node to retrieve this content from your mirror registry.

modules/microshift-oc-mirror-connectivity.adoc

@@ -6,7 +6,8 @@
 [id="microshift-connectivity-considerations_{context}"]
 = Connectivity considerations when populating a mirror registry
 
-When you populate your registry, you can use one of following connectivity scenarios:
+[role="_abstract"]
+When you populate your mirror registry, you can use connected or disconnected mirroring depending on your use case.
 
 Connected mirroring::
 If you have a host that can access both the internet and your mirror registry, but not your node, you can directly mirror the content from that machine.

modules/microshift-oc-mirror-creating-imageset-config.adoc

@@ -6,7 +6,8 @@
 [id="microshift-oc-mirror-creating-imageset-config_{context}"]
 = Creating an image set configuration file
 
-You must create an `ImageSetConfiguration` YAML file. This image set configuration file specifies both the Operators to mirror and the configuration settings for the oc-mirror plugin. Edit the contents of the image set configuration file so that the entries are compatible with both {microshift-short} and the Operator you plan to use.
+[role="_abstract"]
+You must create an `ImageSetConfiguration` YAML file to specify both the Operators to mirror and the configuration settings for the oc-mirror plugin. Edit the contents of the file so that the entries are compatible with both {microshift-short} and the Operator you plan to use.
 
 [NOTE]
 ====
@@ -54,6 +55,7 @@ The `platform` field, related fields, and Helm are not supported by {microshift-
 . Save the updated file as `ImageSetConfiguration.yaml`.
 
 .Next steps
+
 * Use the oc-mirror plugin to mirror an image set directly to a target mirror registry.
 * Configure CRI-O.
 * Apply the catalog sources to your node.

modules/microshift-oc-mirror-dry-run.adoc

@@ -1,12 +1,13 @@
 // Module included in the following assemblies:
 //
-// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc
+// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-oc-mirror-dry-run_{context}"]
 = Performing a dry run
 
-You can use oc-mirror to perform a dry run, without actually mirroring any images. A dry run means you can review the list of images to be mirrored. You can catch any errors with your image set configuration early by using a dry run, or use the generated list of images with other tools to conduct mirroring.
+[role="_abstract"]
+You can use oc-mirror to perform a dry run so that you can review the list of images to be mirrored. By using a dry run, you can catch any errors with your image set configuration early or use the generated list of images with other tools to conduct mirroring.
 
 .Prerequisites