From e0f0b713e51d567d92a916c20a34b4e974f84a50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Wed, 5 Nov 2025 09:25:52 -0500 Subject: [PATCH] OSDOCS-15793: modularizes Operators assemblies MicroShift --- ...hift-operators-oc-mirror-disconnected.adoc | 18 +++---- .../microshift-operators-oc-mirror.adoc | 3 +- .../microshift-operators-olm.adoc | 48 ++++--------------- .../microshift-operators.adoc | 28 +++-------- modules/microshift-about-using-operators.adoc | 14 ++++++ .../microshift-installing-olm-options.adoc | 16 +++++++ modules/microshift-oc-mirror-about-con.adoc | 3 +- .../microshift-oc-mirror-connectivity.adoc | 3 +- ...ft-oc-mirror-creating-imageset-config.adoc | 4 +- modules/microshift-oc-mirror-dry-run.adoc | 5 +- ...-oc-mirror-embed-ops-disconnected-use.adoc | 5 +- ...oshift-oc-mirror-install-catalog-node.adoc | 1 + ...icroshift-oc-mirror-list-ops-catalogs.adoc | 8 +++- modules/microshift-oc-mirror-to-mirror.adoc | 1 + ...-oc-mirror-transform-imageset-to-crio.adoc | 3 +- modules/microshift-olm-build-op-catalogs.adoc | 15 +++--- modules/microshift-olm-considerations.adoc | 22 +++++++++ ...oshift-olm-deploy-op-disconnected-con.adoc | 9 ++-- modules/microshift-olm-deploy-ops-con.adoc | 10 ++-- .../microshift-olm-deploy-ops-global-ns.adoc | 18 +++---- .../microshift-olm-deploy-ops-spec-ns.adoc | 8 +++- modules/microshift-olm-namespaces.adoc | 8 ++-- modules/microshift-olm-rh-ops-mirror.adoc | 1 + ...t-operators-how-to-install-and-manage.adoc | 25 ++++++++++ .../microshift-ops-config-embed-ostree.adoc | 4 +- 25 files changed, 172 insertions(+), 108 deletions(-) create mode 100644 modules/microshift-about-using-operators.adoc create mode 100644 modules/microshift-installing-olm-options.adoc create mode 100644 modules/microshift-olm-considerations.adoc create mode 100644 modules/microshift-operators-how-to-install-and-manage.adoc diff --git a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc index 780ab51a2f..7d1b6a5f89 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc +++ b/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] diff --git a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc index 410cc8ff35..0f3e965e33 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc +++ b/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] diff --git a/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc index 920a07dd51..06c750c861 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +++ b/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] diff --git a/microshift_running_apps/microshift_operators/microshift-operators.adoc b/microshift_running_apps/microshift_operators/microshift-operators.adoc index cf2b371bb0..b0b8afd7ac 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators.adoc +++ b/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] diff --git a/modules/microshift-about-using-operators.adoc b/modules/microshift-about-using-operators.adoc new file mode 100644 index 0000000000..d9a680a084 --- /dev/null +++ b/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. diff --git a/modules/microshift-installing-olm-options.adoc b/modules/microshift-installing-olm-options.adoc new file mode 100644 index 0000000000..eeaaf875e5 --- /dev/null +++ b/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] diff --git a/modules/microshift-oc-mirror-about-con.adoc b/modules/microshift-oc-mirror-about-con.adoc index 1c4ea03b13..07ef9321a3 100644 --- a/modules/microshift-oc-mirror-about-con.adoc +++ b/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. diff --git a/modules/microshift-oc-mirror-connectivity.adoc b/modules/microshift-oc-mirror-connectivity.adoc index 639115905b..46ad0a6fb4 100644 --- a/modules/microshift-oc-mirror-connectivity.adoc +++ b/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. diff --git a/modules/microshift-oc-mirror-creating-imageset-config.adoc b/modules/microshift-oc-mirror-creating-imageset-config.adoc index 1e508a9820..efcda62ccc 100644 --- a/modules/microshift-oc-mirror-creating-imageset-config.adoc +++ b/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. diff --git a/modules/microshift-oc-mirror-dry-run.adoc b/modules/microshift-oc-mirror-dry-run.adoc index 16d3574c8e..25208cd7a7 100644 --- a/modules/microshift-oc-mirror-dry-run.adoc +++ b/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 diff --git a/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc b/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc index 0b12bd82d3..630bb3bf64 100644 --- a/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc +++ b/modules/microshift-oc-mirror-embed-ops-disconnected-use.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-prep-ops-cat-images-disconnected-use_{context}"] = Getting catalogs and Operator container image references -After performing a dry run with the oc-mirror plugin to review the list of images that you want to mirror, you must get all of the container image references, then format the output for adding to an image builder blueprint. +[role="_abstract"] +After performing a dry run with the oc-mirror plugin to review the list of images that you want to mirror, you must get all of the container image references. Then you must format the output for adding to an image builder blueprint. [NOTE] ==== diff --git a/modules/microshift-oc-mirror-install-catalog-node.adoc b/modules/microshift-oc-mirror-install-catalog-node.adoc index 0c8fe9ec67..0b44aa6526 100644 --- a/modules/microshift-oc-mirror-install-catalog-node.adoc +++ b/modules/microshift-oc-mirror-install-catalog-node.adoc @@ -6,6 +6,7 @@ [id="microshift-oc-mirror-install-catalog-in-node_{context}"] = Installing a custom catalog created with the oc-mirror plugin +[role="_abstract"] After you mirror your image set to the mirror registry, you must apply the generated `CatalogSource` custom resource (CR) into the node. Operator Lifecycle Manager (OLM) uses the `CatalogSource` CR to retrieve information about the available Operators in the mirror registry. You must then create and apply a subscription CR to subscribe to your custom catalog. .Prerequisites diff --git a/modules/microshift-oc-mirror-list-ops-catalogs.adoc b/modules/microshift-oc-mirror-list-ops-catalogs.adoc index 3d7a3d004f..455a2bef78 100644 --- a/modules/microshift-oc-mirror-list-ops-catalogs.adoc +++ b/modules/microshift-oc-mirror-list-ops-catalogs.adoc @@ -6,7 +6,8 @@ [id="microshift-oc-mirror-list-operators-catalogs_{context}"] = Inspecting catalog contents by using the oc-mirror plugin -Use the following example procedure to select a catalog and list {OCP} Operators to add to your oc-mirror plugin image set configuration file. You must use oc mirror v1 to selecting a catalog and listing Operators. +[role="_abstract"] +Use the following example procedure to select a catalog and list Operators to add to your oc-mirror plugin image set configuration file. You must use oc mirror v1 to select a catalog and list Operators. [NOTE] ==== @@ -14,11 +15,13 @@ If you use your own catalogs and Operators, you can push the images directly to ==== .Prerequisites + * You uninstalled {oc-first}. * You installed the Operator Lifecycle Manager (OLM). * You installed the oc-mirror plugin. .Procedure + . Get a list of available Red{nbsp}Hat-provided Operator catalogs to filter by running the following command: + [source,terminal,subs="attributes+"] @@ -52,5 +55,6 @@ $ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-i ---- .Next steps + * Create and edit an image set configuration file using the information gathered in this procedure. -* Mirror the images from the transformed image set configuration file to a mirror registry or disk. \ No newline at end of file +* Mirror the images from the transformed image set configuration file to a mirror registry or disk. diff --git a/modules/microshift-oc-mirror-to-mirror.adoc b/modules/microshift-oc-mirror-to-mirror.adoc index 7e03caa4d9..75e6ad6671 100644 --- a/modules/microshift-oc-mirror-to-mirror.adoc +++ b/modules/microshift-oc-mirror-to-mirror.adoc @@ -6,6 +6,7 @@ [id="microshift-oc-mirror-mirror-to-mirror_{context}"] = Mirroring from mirror to mirror +[role="_abstract"] You can use the oc-mirror plugin to mirror an image set directly to a target mirror registry that is accessible during image set creation. .Prerequisites diff --git a/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc index 246f3983cf..2213aeead7 100644 --- a/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc +++ b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc @@ -6,7 +6,8 @@ [id="microshift-oc-mirror-transform-imageset-to-crio_{context}"] = Configuring CRI-O for using a registry mirror for Operators -You must transform the `ImageDigestMirrorSet` YAML file created with the oc-mirror plugin into a format that is compatible with the CRI-O container runtime configuration used by {microshift-short}. +[role="_abstract"] +To use a registry mirror for Operators with {microshift-short}, you must transform the `ImageDigestMirrorSet` YAML file created with the oc-mirror plugin into a format that is compatible with the {microshift-short} CRI-O container runtime configuration. .Prerequisites diff --git a/modules/microshift-olm-build-op-catalogs.adoc b/modules/microshift-olm-build-op-catalogs.adoc index e03c8665f5..5d1baca949 100644 --- a/modules/microshift-olm-build-op-catalogs.adoc +++ b/modules/microshift-olm-build-op-catalogs.adoc @@ -6,18 +6,21 @@ [id="microshift-options-building-operator-catalogs_{context}"] = About building Operator catalogs +[role="_abstract"] 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. -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/operators/index#olm-managing-custom-catalogs[Managing custom catalogs] -* 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] +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 more information, see the following links: -* 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-managing-custom-catalogs[Managing custom catalogs] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/understanding-operators#olm-packaging-format[Example catalog] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/cli_tools/opm-cli#cli-opm-ref[`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. -==== \ No newline at end of file +* When 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. For more information, see: + +* 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] +==== diff --git a/modules/microshift-olm-considerations.adoc b/modules/microshift-olm-considerations.adoc new file mode 100644 index 0000000000..4eb968030a --- /dev/null +++ b/modules/microshift-olm-considerations.adoc @@ -0,0 +1,22 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-olm-considerations_{context}"] += Considerations for using OLM with {microshift-short} + +[role="_abstract"] +You must consider the application of Operators and steps to use them when planning which ones you want to use with your {microshift-short} platform. + +* 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.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}. +==== diff --git a/modules/microshift-olm-deploy-op-disconnected-con.adoc b/modules/microshift-olm-deploy-op-disconnected-con.adoc index 6fc8f063fe..6f0c5b918c 100644 --- a/modules/microshift-olm-deploy-op-disconnected-con.adoc +++ b/modules/microshift-olm-deploy-op-disconnected-con.adoc @@ -1,14 +1,17 @@ //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: CONCEPT [id="microshift-adding-OLM-Operators-to-disconnected-node_{context}"] = About adding OLM-based Operators to a disconnected node -For Operators that are installed on disconnected nodes, Operator Lifecycle Manager (OLM) by default cannot access sources hosted on remote registries because those remote sources require full internet connectivity. Therefore, you must mirror the remote registries to a highly available container registry. +[role="_abstract"] +You must mirror remote registries to a highly available container registry for Operators that are installed on a disconnected node. -The following steps are required to use OLM-based Operators in disconnected situations: +By default, Operator Lifecycle Manager (OLM) requires full internet connectivity to access remote registries such as Red{nbsp}Hat-provided Operator catalogs. For a disconnected node, you must mirror remote registries to a highly available container registry. + +The following steps are required to use OLM to install, manage, and lifecycle Operators in disconnected situations: * Include OLM in the container image list for your mirror registry. * Configure the system to use your mirror registry by updating your CRI-O configuration directly. `ImageContentSourcePolicy` is not supported in {microshift-short}. diff --git a/modules/microshift-olm-deploy-ops-con.adoc b/modules/microshift-olm-deploy-ops-con.adoc index 7890b48e4d..1ea39647dd 100644 --- a/modules/microshift-olm-deploy-ops-con.adoc +++ b/modules/microshift-olm-deploy-ops-con.adoc @@ -6,18 +6,20 @@ [id="microshift-olm-deploy-operators_{context}"] = How to deploy Operators using OLM +[role="_abstract"] 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 node. All Operators installed in a given namespace must have the same watch scope. +Operators that you are managing with Operator Lifecycle Manager (OLM) have a watch scope. For example, some Operators only support watching their own namespace, while others support watching every namespace in the node. All Operators installed in a given namespace must have the same watch scope. ==== [id="microshift-olm-operators-connection-details_{context}"] == Connectivity and OLM Operator deployment -Operators can be deployed anywhere a catalog is running. + +You can deplpy Operators anywhere a catalog is running. * For a node that is 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 a {microshift-short} node is completely offline, all images must be embedded into an `osbuild` blueprint. -//TODO point to correct ref docs \ No newline at end of file +* For use cases in which a {microshift-short} node is completely offline, all images must be embedded into an `osbuild` blueprint or a Containerfile. +//osbuild is removed with RHEL 10/MS 4.21 diff --git a/modules/microshift-olm-deploy-ops-global-ns.adoc b/modules/microshift-olm-deploy-ops-global-ns.adoc index 260978740c..9b901d2a34 100644 --- a/modules/microshift-olm-deploy-ops-global-ns.adoc +++ b/modules/microshift-olm-deploy-ops-global-ns.adoc @@ -6,17 +6,21 @@ [id="microshift-OLM-deploy-Operators_{context}"] = Adding OLM-based Operators to a networked node using the global namespace -To deploy different operators to different namespaces, use this procedure. For a {microshift-short} node that has network connectivity, Operator Lifecycle Manager (OLM) can access sources hosted on remote registries. The following procedure lists the basic steps of using configuration files to install an Operator that uses the global namespace. +[role="_abstract"] +To deploy different Operators to different namespaces, follow the basic steps to use configuration files to install an Operator that uses the global namespace. + +For a {microshift-short} node that has network connectivity, Operator Lifecycle Manager (OLM) can access sources hosted on remote registries. [NOTE] ==== -To use an Operator installed in a different namespace, or in more than one namespace, make sure that the catalog source and the Subscription CR that references the Operator are running in the `openshift-marketplace` namespace. +To use an Operator installed in a different namespace, or in more than one namespace, make sure that both the catalog source and the Subscription CR that references the Operator are running in the `openshift-marketplace` namespace. ==== .Prerequisites + * The {oc-first} is installed. * Operator Lifecycle Manager (OLM) is installed. -* You have created a custom catalog in the global namespace. +* You created a custom catalog in the global namespace. .Procedure @@ -80,8 +84,7 @@ spec: . Apply the `CatalogSource` configuration by running the following command: + -[subs="+quotes"] -[source,terminal] +[source,terminal,subs="+quotes"] ---- $ oc apply -f __ # <1> ---- @@ -173,8 +176,7 @@ spec: . Apply the Subscription CR configuration by running the following command: + -[subs="+quotes"] -[source,terminal] +[source,terminal,subs="+quotes"] ---- $ oc apply -f __ # <1> ---- @@ -210,4 +212,4 @@ NAME READY STATUS RESTARTS AGE cert-manager-7df8994ddb-4vrkr 1/1 Running 0 19s cert-manager-cainjector-5746db8fd7-69442 1/1 Running 0 18s cert-manager-webhook-f858bf58b-748nt 1/1 Running 0 18s ----- \ No newline at end of file +---- diff --git a/modules/microshift-olm-deploy-ops-spec-ns.adoc b/modules/microshift-olm-deploy-ops-spec-ns.adoc index 7986e19c3e..51b09747ff 100644 --- a/modules/microshift-olm-deploy-ops-spec-ns.adoc +++ b/modules/microshift-olm-deploy-ops-spec-ns.adoc @@ -6,7 +6,10 @@ [id="microshift-OLM-deploy-Operators-specific-namespace_{context}"] = Adding OLM-based Operators to a networked node in a specific namespace -Use this procedure if you want to specify a namespace for an Operator, for example, `olm-microshift`. In this example, the catalog is scoped and available in the global `openshift-marketplace` namespace. The Operator uses content from the global namespace, but runs only in the `olm-microshift` namespace. For a {microshift-short} node that has network connectivity, Operator Lifecycle Manager (OLM) can access sources hosted on remote registries. +[role="_abstract"] +You can specify a namespace for an Operator for a variety of reasons, such as security and resource isolation. For example, you can specify the namespace `olm-microshift`. + +In the following example, the catalog is scoped and available in the global `openshift-marketplace` namespace. The Operator uses content from the global namespace, but runs only in the `olm-microshift` namespace. For a {microshift-short} node that has network connectivity, Operator Lifecycle Manager (OLM) can access sources hosted on remote registries. [IMPORTANT] ==== @@ -14,6 +17,7 @@ All of the Operators installed in a specific namespace must have the same watch ==== .Prerequisites + * The {oc-first} is installed. * Operator Lifecycle Manager (OLM) is installed. * You have created a custom catalog that is running in the global namespace. @@ -251,4 +255,4 @@ Allow a minute or two for the Operator start. ---- NAME READY STATUS RESTARTS AGE gitlab-controller-manager-69bb6df7d6-g7ntx 2/2 Running 0 3m24s ----- \ No newline at end of file +---- diff --git a/modules/microshift-olm-namespaces.adoc b/modules/microshift-olm-namespaces.adoc index 32487164dc..baef3db313 100644 --- a/modules/microshift-olm-namespaces.adoc +++ b/modules/microshift-olm-namespaces.adoc @@ -2,11 +2,12 @@ // // * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: REFERENCE [id="microshift-olm-namespaces_{context}"] = Namespace use in {microshift-short} -The `microshift-olm` RPM creates the three default namespaces: one for running OLM, and two for catalog and Operator installation. You can create additional namespaces as needed for your use case. +[role="_abstract"] +The `microshift-olm` RPM creates the three default namespaces: one for running Operator Lifecycle Manager (OLM), and two for catalog and Operator installation. You can create additional namespaces as needed for your use case. [id="microshift-olm-default-namespaces_{context}"] == Default namespaces @@ -31,4 +32,5 @@ The following table lists the default namespaces and a brief description of how [id="microshift-olm-custom-namespace_{context}"] == Custom namespaces -If you want to use a catalog and Operator together in a single namespace, then you must create a custom namespace. After you create the namespace, you must create the catalog in that namespace. All Operators running in the custom namespace must have the same single-namespace watch scope. \ No newline at end of file + +If you want to use a catalog and Operator together in a single namespace, then you must create a custom namespace. After you create the namespace, you must create the catalog in that namespace. All Operators running in the custom namespace must have the same single-namespace watch scope. diff --git a/modules/microshift-olm-rh-ops-mirror.adoc b/modules/microshift-olm-rh-ops-mirror.adoc index 195558c726..fa3f6bdab7 100644 --- a/modules/microshift-olm-rh-ops-mirror.adoc +++ b/modules/microshift-olm-rh-ops-mirror.adoc @@ -7,6 +7,7 @@ [id="microshift-olm-rh-ops-mirror_{context}"] = Using Red Hat-provided Operator catalogs and mirror registries +[role="_abstract"] You can filter catalogs and delete images to get specific Operators and mirror them by using the oc-mirror {oc-first} plugin. You can also use Operators in disconnected settings or embedded in a {op-system-base-full} image. * To understand more about how to configure your systems for mirroring, follow the links in the following "Additional resources" section. diff --git a/modules/microshift-operators-how-to-install-and-manage.adoc b/modules/microshift-operators-how-to-install-and-manage.adoc new file mode 100644 index 0000000000..1aaf3042fc --- /dev/null +++ b/modules/microshift-operators-how-to-install-and-manage.adoc @@ -0,0 +1,25 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-operators-how-to-install-and-manage_{context}"] += How to use Operators with a {microshift-short} node + +[role="_abstract"] +There are two ways to install and manage Operators for your {microshift-short} node. You can use manifests or Operator Lifecycle Manager (OLM). + +[id="microshift-operators-paths-manifests_{context}"] +== Manifests for Operators + +You can install and manage Operators 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. For more information, see the following links: + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/applications-with-microshift[Using Kustomize manifests to deploy applications] +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/applications-with-microshift#microshift-applying-manifests-example_applications-microshift[Using manifests example] + +[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 more information, see the following link: + +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_microshift/{ocp-version}/html/running_applications/operators#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] diff --git a/modules/microshift-ops-config-embed-ostree.adoc b/modules/microshift-ops-config-embed-ostree.adoc index badbff3743..a9120da1ac 100644 --- a/modules/microshift-ops-config-embed-ostree.adoc +++ b/modules/microshift-ops-config-embed-ostree.adoc @@ -1,14 +1,16 @@ //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-apply-ops-ostree-disconnected-use_{context}"] = Applying catalogs and Operators in a disconnected-deployment RHEL for Edge image +[role="_abstract"] After you have created a {op-system-ostree} image for a disconnected environment and configured {microshift-short} networking settings for disconnected use, you can configure the namespace and create catalog and Operator custom resources (CR) for running your Operators. .Prerequisites + * You have a {op-system-ostree} image. * Networking is configured for disconnected use. * You completed the oc-mirror plugin dry run procedure.