OSDOCS-8991: OLM on MicroShift intro

_topic_maps/_topic_map_ms.yml

@@ -446,6 +446,8 @@ Topics:
   File: microshift-authentication
 - Name: Using Operators
   File: microshift-operators
+- Name: Using Operator Lifecycle Manager
+  File: microshift-operators-olm
 ---
 Name: Backup and restore
 Dir: microshift_backup_and_restore

microshift_install/microshift-embed-in-rpm-ostree.adoc

@@ -29,13 +29,13 @@ include::modules/microshift-adding-repos-to-image-builder.adoc[leveloffset=+1]
 * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image Builder system requirements]
 * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-installing-image-builder_setting-up-image-builder[Installing Image Builder]
 
-
 include::modules/microshift-adding-service-to-blueprint.adoc[leveloffset=+1]
 
 include::modules/microshift-adding-olm-to-blueprint.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
+* xref:../microshift_running_apps/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}]
 * xref:../microshift_updating/microshift-update-rpms-ostree.adoc[Applying updates on an OSTree system]
 
 include::modules/microshift-ca-adding-bundle.adoc[leveloffset=+1]

microshift_install/microshift-install-rpm.adoc

@@ -39,13 +39,12 @@ include::modules/microshift-install-rpms.adoc[leveloffset=+1]
 
 include::modules/microshift-install-rpms-olm.adoc[leveloffset=+1]
 
-//TODO: Additional resources section that includes OLM resources when docs are complete
-
-//additional resources for install rpms module
+//additional resources for install rpms modules
 [role="_additional-resources"]
 .Additional resources
-* xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing MicroShift].
-* xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-rpm-preparing_microshift-install-rpm[Preparing to install MicroShift from an RPM package].
+* xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing MicroShift]
+* xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-rpm-preparing_microshift-install-rpm[Preparing to install MicroShift from an RPM package]
+* xref:../microshift_running_apps/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}]
 
 include::modules/microshift-service-starting.adoc[leveloffset=+1]
 

microshift_running_apps/microshift-operators-olm.adoc

@@ -0,0 +1,70 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="microshift-operators-olm"]
+= Using Operator Lifecycle Manager with {microshift-short}
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-operators-olm
+
+toc::[]
+
+The Operator Lifecycle Manager (OLM) package manager is used in {microshift-short} for installing and running optional link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/architecture/control-plane#olm-operators_control-plane[add-on Operators].
+
+* 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 cluster, 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 network-connected clusters, or for building catalogs for custom Operators that use an internal registry.
+** To mirror your catalogs and Operators for disconnected or offline clusters, install link:https://docs.openshift.com/container-platform/{ocp-version}/installing/disconnected_install/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[the oc-mirror OpenShift CLI plugin].
+
+[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 {microshift-short} clusters, 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/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/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-olm-namespaces.adoc[leveloffset=+1]
+
+include::modules/microshift-olm-build-op-catalogs.adoc[leveloffset=+1]
+
+//additional resources for builing 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.openshift.com/container-platform/{ocp-version}/operators/understanding/olm-rh-catalogs.html#olm-about-catalogs_olm-rh-catalogs[About Operator catalogs]
+* For instructions about creating 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.openshift.com/container-platform/4.14/operators/understanding/olm/olm-understanding-operatorgroups.html#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
+[role="_additional-resources"]
+.Additional resources
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-upgrading-operators[Updating installed Operators]
+* link:https://access.redhat.com/documentation/en-us/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]
+
+include::modules/microshift-olm-deploy-op-disconnected.adoc[leveloffset=+2]
+
+//additional resources for deploying operators in disconnected and offline environments
+[role="_additional-resources"]
+.Additional resources
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] for more information.
+* link:https://docs.openshift.com/container-platform/{ocp-version}/installing/disconnected_install/installing-mirroring-disconnected.html#installing-mirroring-disconnected[Mirroring images for a disconnected installation using the oc-mirror plugin]
+* xref:../microshift_install/microshift-deploy-with-mirror-registry.adoc#microshift-configuring-hosts-for-mirror_microshift-deployment-mirror[Configuring hosts for mirror registry access]
+* xref:../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts]
+* xref:../microshift_install/microshift-deploy-with-mirror-registry.adoc#microshift-get-mirror-reg-container-image-list_microshift-deploy-with-mirror-registry[Getting the mirror registry container image list]
+* xref:../microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-in-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use]

microshift_running_apps/microshift-operators.adoc

@@ -1,6 +1,6 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="operators-with-microshift"]
-= How Operators work with {microshift-short}
+= Using Operators with {microshift-short}
 include::_attributes/attributes-microshift.adoc[]
 :context: operators-microshift
 
@@ -10,9 +10,17 @@ You can use Operators with {microshift-short} to create applications that monito
 
 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.
 
-{microshift-short} applications are generally expected to be deployed in static environments. However, Operators are available if helpful in your use case. To determine an Operator's compatibility with {microshift-short}, check the Operator's documentation.
+{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="how-to-install-operators_{context}"]
-== How to install Operators in {microshift-short}
+[id="microshift-operators-installation-paths_{context}"]
+== How to use Operators with {microshift-short} clusters
 
-To minimize the footprint of {microshift-short}, Operators are installed directly with manifests instead of using the Operator Lifecycle Manager (OLM). You can use the `kustomize` configuration management tool with {microshift-short} to deploy an application. Use the same steps to install Operators with manifests. Read xref:../microshift_running_apps/microshift-applications.adoc#microshift-manifests-overview_applications-microshift[Using Kustomize manifests to deploy applications] for more information about manifests.
+There are two ways to use Operators for your {microshift-short} clusters:
+
+[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} cluster 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-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}].

modules/microshift-get-mirror-reg-container-image-list.adoc

@@ -4,10 +4,15 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="microshift-get-mirror-reg-container-image-list_{context}"]
-= Getting the {microshift-short} mirror registry container image list
+= Getting the mirror registry container image list
 
 To use a mirror registry, you must know which container image references are used by a specific version of {microshift-short}. These references are provided in the `release-<arch>.json` files that are part of the `microshift-release-info` RPM package.
 
+[NOTE]
+====
+To mirror the Operator Lifecycle Manager (OLM) in disconnected environments, add the references provided in the `release-olm-$ARCH.json` that is included in the `microshift-olm` RPM and follow the same procedure. Use `oc-mirror` for mirroring Operator catalogs and Operators.
+====
+
 .Prerequisites
 
 * You have installed jq.

modules/microshift-olm-build-op-catalogs.adoc

@@ -0,0 +1,22 @@
+//Module included in the following assemblies:
+//
+//* microshift_running_apps/microshift-operators-olm.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-options-building-operator-catalogs_{context}"]
+= About building Operator catalogs
+
+To use Operator Lifecycle Manager (OLM) with {microshift-short}, you must build custom Operator catalogs that you can then manage with OLM. The standard catalogs that are included with {OCP} are not included with {microshift-short}.
+
+[id="microshift-file-based-olm-catalogs_{context}"]
+== File-based Operator catalogs
+You can create catalogs for your custom Operators or filter catalogs of widely available Operators. You can combine both methods to create the catalogs needed for your specific use case. To run {microshift-short} with your own Operators and OLM, make a catalog by using the file-based catalog structure.
+
+* For details, see link:https://docs.openshift.com/container-platform/4.14/operators/admin/olm-managing-custom-catalogs.html#olm-creating-fb-catalog-image_olm-managing-custom-catalogs[Managing custom catalogs] and link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/understanding-operators#olm-fb-catalogs-example_olm-packaging-format[Example catalog].
+
+* See also link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/cli_tools/opm-cli[`opm` CLI reference].
+
+[IMPORTANT]
+====
+* When link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-creating-catalog-from-index_olm-restricted-networks[adding a catalog source to a cluster], set the `securityContextConfig` value to `restricted` in the `catalogSource.yaml` file. Ensure that your catalog can run with `restricted` permissions.
+====

modules/microshift-olm-deploy-op-disconnected.adoc

@@ -0,0 +1,19 @@
+//Module included in the following assemblies:
+//
+//* microshift_running_apps/microshift-operators-olm.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-adding-OLM-Operators-to-offline-cluster_{context}"]
+= About adding OLM-based Operators to an offline cluster
+
+For {microshift-short} clusters that are installed on disconnected or offline clusters, Operator Lifecycle Manager (OLM) by default cannot access sources hosted on remote registries because those remote sources require full internet connectivity.
+
+The following steps are required to use OLM-based Operators in offline situations:
+
+* Include OLM in your container image list for your mirror registry.
+* Configure the system to use the mirror by updating your CRI-O configuration directly. `ImageContentSourcePolicy` is not supported in {microshift-short}.
+* Add a `CatalogSource` object to the cluster so that the OLM catalog Operator can use the local catalog on the mirror registry.
+* Ensure that {microshift-short} is installed to run in an offline capacity.
+* Ensure that the network settings are configured to run in a disconnected mode.
+
+After enabling OLM in an offline cluster, you can continue to use your unrestricted workstation to keep your local catalog sources updated as newer versions of Operators are released.

modules/microshift-olm-deploy-ops-con.adoc

@@ -0,0 +1,23 @@
+//Module included in the following assemblies:
+//
+//* microshift_running_apps/microshift-operators-olm.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-deploy-operators_{context}"]
+= How to deploy Operators
+
+After you create and deploy your custom catalog, you must create a Subscription custom resource (CR) that can access the catalog and install the Operators you choose. Where Operators run depends on the namespace in which you create the Subscription CR.
+
+[IMPORTANT]
+====
+Operators in OLM have a watch scope. For example, some Operators only support watching their own namespace, while others support watching every namespace in the cluster. All Operators installed in a given namespace must have the same watch scope.
+====
+
+[id="microshift-operators-connection-details_{context}"]
+== Connectivity and Operator deployment
+Operators can be deployed anywhere a catalog is running.
+
+* For clusters that are connected to the internet, mirroring images is not required. Images can be pulled over the network.
+* For restricted networks in which {microshift-short} has access to an internal network only, images must be mirrored to an internal registry.
+* For use cases in which {microshift-short} clusters are completely offline, all images must be embedded into an `osbuild` blueprint.
+//TODO point to correct ref docs