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 be8304bcbf7e..2473f609fffa 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 @@ -1,26 +1,28 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-operators-oc-mirror-disconnected"] = Adding OLM-based Operators to a disconnected node + include::_attributes/attributes-microshift.adoc[] :context: microshift-operators-oc-mirror-disconnected 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] - //OCP module, edit with conditionals and care include::modules/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] \ No newline at end of file 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 72c8f256ec23..002ce8c0fcbd 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc @@ -1,32 +1,18 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-operators-oc-mirror"] = Creating custom catalogs using the oc-mirror plugin + include::_attributes/attributes-microshift.adoc[] :context: microshift-operators-oc-mirror toc::[] -You can create custom catalogs with widely available Operators and mirror them by using the oc-mirror OpenShift CLI (oc) plugin. - -[id="microshift-olm-red-hat-ops-mirror_{context}"] -== Using Red Hat-provided Operator catalogs and mirror registries -You can filter and prune catalogs to get specific Operators and mirror them by using the oc-mirror OpenShift CLI (oc) plugin. You can also use Operators in disconnected settings or embedded in {op-system-ostree-first} images. To read more details about how to configure your systems for mirroring, use the links in the following "Additional resources" section. If you are ready to deploy Operators from Red Hat-provided Operator catalogs, mirror them, or to embed them in {op-system-ostree} images, start with the following section, "Inspecting catalog contents by using the oc-mirror plugin." - -//additional resources for deploying operators in disconnected environments -[role="_additional-resources"] -.Additional resources -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] -* xref:../../microshift_install_get_ready/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_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-get-mirror-reg-container-image-list_microshift-deployment-mirror[Getting the mirror registry container image list] -* xref:../../microshift_install_rpm_ostree/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] +[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-oc-mirror-about-con.adoc[leveloffset=+1] -//additional resources for preqeq to using oc mirror -[role="_additional-resources"] -.Additional resources -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html-single/disconnected_environments/index#installing-mirroring-installation-images[Mirroring images for a disconnected installation by using the oc adm command] +include::modules/microshift-connectivity-pop-mirror-registry.adoc[leveloffset=+2] include::modules/microshift-oc-mirror-list-ops-catalogs.adoc[leveloffset=+2] @@ -36,20 +22,9 @@ include::modules/microshift-oc-mirror-creating-imageset-config.adoc[leveloffset= //OCP module, reference for valid imageset parameters for microshift; see conditionals include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+2] -//additional resources for creating image sets -[role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html-single/disconnected_environments/index#oc-mirror-image-set-examples_installing-mirroring-disconnected[Imageset configuration examples] - // OCP module, mirroring from mirror to mirror include::modules/oc-mirror-mirror-to-mirror.adoc[leveloffset=+2] -//additional resources for microshift mirror to mirror module -[role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html-single/disconnected_environments/index#oc-mirror-workflows-partially-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a partially disconnected environment] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/disconnected_environments/index#oc-mirror-workflows-fully-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a fully disconnected environment] - //Convert the imageset file and add configuration to CRI-O include::modules/microshift-oc-mirror-transform-imageset-to-crio.adoc[leveloffset=+2] @@ -59,7 +34,11 @@ include::modules/microshift-oc-mirror-install-catalog-node.adoc[leveloffset=+1] [id="Additional-resources_microshift-operators-oc-mirror_{context}"] [role="_additional-resources"] == Additional resources -* xref:../../microshift_install_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-configuring-hosts-for-mirror_microshift-deployment-mirror[Configuring hosts for mirror registry access] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/disconnected_environments/index#oc-mirror-image-set-examples_installing-mirroring-disconnected[Imageset configuration examples] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] + +{microshift-short} links:: * xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] * xref:../../microshift_install_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-deploy-with-mirror-registry[Mirroring container images for disconnected installations] * xref:../../microshift_install_rpm_ostree/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] diff --git a/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc index 910fe64488ab..4ed7fc1112bf 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc @@ -1,61 +1,35 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-operators-olm"] -= Using Operator Lifecycle Manager with {microshift-short} += Using Operator Lifecycle Manager with MicroShift + 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]. - -[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}. -==== +[role="_abstract"] +You can use Operator Lifecycle Manager (OLM) with {microshift-short} to install and run optional add-on Operators. -[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. +include::modules/microshift-olm-considerations.adoc[leveloffset=+1] -* 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 -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-upgrading-operators[Updating installed Operators] +== 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://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/operators/index#olm-about-catalogs_olm-rh-catalogs[About Operator catalogs] +* 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] * 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] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-managing-custom-catalogs-fb[Managing custom catalogs] diff --git a/microshift_running_apps/microshift_operators/microshift-operators.adoc b/microshift_running_apps/microshift_operators/microshift-operators.adoc index cf2b371bb064..b0b8afd7ac4f 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 000000000000..d9a680a08451 --- /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-connectivity-pop-mirror-registry.adoc b/modules/microshift-connectivity-pop-mirror-registry.adoc new file mode 100644 index 000000000000..df1ef511ce9e --- /dev/null +++ b/modules/microshift-connectivity-pop-mirror-registry.adoc @@ -0,0 +1,27 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-connectivity-pop-mirror-registry_{context}"] += Connectivity considerations when populating a mirror registry + +When you populate your registry, you can use one of following connectivity scenarios: + +Connected mirroring:: +If you have a host that can access both the internet and your mirror registry, but not your cluster node, you can directly mirror the content from that machine. + +Disconnected mirroring:: +If you do not have a host that can access both the internet and your mirror registry, you must mirror the images to a file system and then bring that host or removable media into your disconnected environment. ++ +[IMPORTANT] +==== +A container registry must be reachable by every machine in the clusters that you provision. Installing, updating, and other operations, such as relocating workloads, might fail if the registry is unreachable. +==== + +To avoid problems caused by an unreachable registry, use the following standard practices: + +* Run mirror registries in a highly available way. +* Ensure that the mirror registry at least matches the production availability of your clusters. + +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-installing-olm-options.adoc b/modules/microshift-installing-olm-options.adoc new file mode 100644 index 000000000000..28ff8320f36a --- /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/{ocp-version}/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/{ocp-version}/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 8c74f66a4ba4..bba80f9b88ba 100644 --- a/modules/microshift-oc-mirror-about-con.adoc +++ b/modules/microshift-oc-mirror-about-con.adoc @@ -1,39 +1,19 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: CONCEPT [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 prune Operator catalogs. You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments with {op-system-ostree}. +[role="_abstract"] +You can use the oc-mirror {oc-first} plugin with {microshift-short} to filter and prune Operator catalogs. You can also use Operators in disconnected settings or embedded in {op-system-ostree-first} images. + +You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments with {op-system-ostree}. [NOTE] ==== -{microshift-short} uses the generally available version (1) of the oc-mirror plugin. Do not use the following procedures with the Technical Preview version (2) of oc-mirror plugin. +{microshift-short} uses the generally available version, v1, of the oc-mirror plugin. Do not use the following procedures with the Technical Preview versio, v2, of oc-mirror plugin. ==== You can mirror the container images required by the desired Operators locally or to a container mirror registry that supports link:https://docs.docker.com/registry/[Docker v2-2], such as {quay}. 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 choose. After you mirror the contents of your catalog, configure each cluster to retrieve this content from your mirror registry. - -[id="microshift-populate-mirror-registry-connectivity_{context}"] -== Connectivity considerations when populating a mirror registry - -When you populate your registry, you can use one of following connectivity scenarios: - -Connected mirroring:: -If you have a host that can access both the internet and your mirror registry, but not your cluster node, you can directly mirror the content from that machine. - -Disconnected mirroring:: -If you do not have a host that can access both the internet and your mirror registry, you must mirror the images to a file system and then bring that host or removable media into your disconnected environment. -+ -[IMPORTANT] -==== -A container registry must be reachable by every machine in the clusters that you provision. Installing, updating, and other operations, such as relocating workloads, might fail if the registry is unreachable. -==== - -To avoid problems caused by an unreachable registry, use the following standard practices: - -* Run mirror registries in a highly available way. -* Ensure that the mirror registry at least matches the production availability of your clusters. - -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-creating-imageset-config.adoc b/modules/microshift-oc-mirror-creating-imageset-config.adoc index a90a976c8e84..a3f5d7c39d9b 100644 --- a/modules/microshift-oc-mirror-creating-imageset-config.adoc +++ b/modules/microshift-oc-mirror-creating-imageset-config.adoc @@ -1,12 +1,15 @@ // Module included in the following assemblies: // -//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-creating-imageset-config_{context}"] = Creating an image set configuration file -You must create an image set configuration file to mirror catalog contents with the oc-mirror plugin. The image set configuration file defines which Operators to mirror along with other configuration settings for the oc-mirror plugin. After generating a default image set file, you must edit the contents so that remaining entries are compatible with both {microshift-short} and the Operator you plan to use. +[role="_abstract"] +You must create an image set configuration file to mirror catalog contents with the oc-mirror plugin. The image set configuration file defines which Operators to mirror along with other configuration settings for the oc-mirror plugin. + +After generating a default image set file, you must edit the contents so that remaining entries are compatible with both {microshift-short} and the Operator you plan to use. You must specify a storage backend in the image set configuration file. This storage backend can be a local directory or a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker v2-2]. The oc-mirror plugin stores metadata in this storage backend during image set creation. diff --git a/modules/microshift-oc-mirror-install-catalog-node.adoc b/modules/microshift-oc-mirror-install-catalog-node.adoc index 7e527eb1099c..8675c7c81e8e 100644 --- a/modules/microshift-oc-mirror-install-catalog-node.adoc +++ b/modules/microshift-oc-mirror-install-catalog-node.adoc @@ -1,12 +1,15 @@ //Module included in the following assemblies: // -// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-install-catalog-in-node_{context}"] = Installing a custom catalog created with the oc-mirror plugin -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. +[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 249558766781..3288b90fab13 100644 --- a/modules/microshift-oc-mirror-list-ops-catalogs.adoc +++ b/modules/microshift-oc-mirror-list-ops-catalogs.adoc @@ -1,11 +1,12 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-list-operators-catalogs_{context}"] = Inspecting catalog contents by using the oc-mirror plugin +[role="_abstract"] Use the following example procedure to select a catalog and list Operators from available {OCP} content to add to your oc-mirror plugin image set configuration file. [NOTE] @@ -14,11 +15,13 @@ If you use your own catalogs and Operators, you can push the images directly to ==== .Prerequisites + * The {oc-first} is installed. * Operator Lifecycle Manager (OLM) is installed. * The oc-mirror OpenShift CLI (oc) plugin is installed. .Procedure + . Get a list of available Red{nbsp}Hat-provided Operator catalogs to filter by running the following command: + [source,terminal,subs="attributes+"] @@ -53,4 +56,4 @@ $ 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-transform-imageset-to-crio.adoc b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc index b3cf59d29ca9..f1c292e11bc4 100644 --- a/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc +++ b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc @@ -1,17 +1,19 @@ //Module included in the following assemblies: // -// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-transform-imageset-to-crio_{context}"] = Configuring CRI-O for using a registry mirror for Operators +[role="_abstract"] You must transform the `imageContentSourcePolicy.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}. .Prerequisites + * The {oc-first} is installed. * Operator Lifecycle Manager (OLM) is installed. -* The oc-mirror OpenShift CLI (oc) plugin is installed. +* The oc-mirror `oc` plugin is installed. * The `yq` binary is installed. * `ImageContentSourcePolicy` and `CatalogSource` YAML files are available in the `oc-mirror-workspace/results-*` directory. @@ -83,11 +85,11 @@ yq '.spec.repositoryDigestMirrors[] as $item ireduce([]; . + [{"mirror": $item.m location = ":" <1> insecure = false ---- -<1> Specify the host name and port of your mirror registry server, for example `microshift-quay:8443`. +<1> Specify the hostname and port of your mirror registry server, for example `microshift-quay:8443`. . Apply the CRI-O configuration changes by restarting {microshift-short} with the following command: + [source,terminal] ---- $ sudo systemctl restart crio ----- \ No newline at end of file +---- diff --git a/modules/microshift-olm-build-op-catalogs.adoc b/modules/microshift-olm-build-op-catalogs.adoc index e03c8665f5df..a4b9440ed414 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. -* 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 000000000000..d682b8ced178 --- /dev/null +++ b/modules/microshift-olm-considerations.adoc @@ -0,0 +1,29 @@ +//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 Operator Package Manager (`opm`) CLI with a network-connected node, or for building catalogs for custom Operators that use an internal registry. See the following link for more information: + +** link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/cli_tools/opm-cli#cli-opm-install[Operator Package Manager `opm` CLI] + +* To mirror your catalogs and Operators for disconnected or offline nodes, install the oc-mirror tool. See the following link for more information: + +** 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[Installing the oc-mirror OpenShift CLI plugin] + +[IMPORTANT] +==== +Before using an Operator, verify with the provider that the Operator is supported on {microshift-short}. +==== diff --git a/modules/microshift-olm-deploy-ops-con.adoc b/modules/microshift-olm-deploy-ops-con.adoc index 7890b48e4d86..9f040ccd124c 100644 --- a/modules/microshift-olm-deploy-ops-con.adoc +++ b/modules/microshift-olm-deploy-ops-con.adoc @@ -6,18 +6,19 @@ [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 deploy Operators anywhere a catalog is running. For example: * 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 diff --git a/modules/microshift-olm-deploy-ops-global-ns.adoc b/modules/microshift-olm-deploy-ops-global-ns.adoc index 260978740c0b..9b901d2a3411 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 7986e19c3ef2..68a3319fc0c5 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,9 +17,10 @@ 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. +* You created a custom catalog that is running in the global namespace. .Procedure diff --git a/modules/microshift-olm-namespaces.adoc b/modules/microshift-olm-namespaces.adoc index 32487164dc1b..4b97ce2f4fd1 100644 --- a/modules/microshift-olm-namespaces.adoc +++ b/modules/microshift-olm-namespaces.adoc @@ -6,7 +6,8 @@ [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-operators-how-to-install-and-manage.adoc b/modules/microshift-operators-how-to-install-and-manage.adoc new file mode 100644 index 000000000000..1aaf3042fc63 --- /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/oc-mirror-imageset-config-params.adoc b/modules/oc-mirror-imageset-config-params.adoc index 4bf9c1505f19..8313dd09f237 100644 --- a/modules/oc-mirror-imageset-config-params.adoc +++ b/modules/oc-mirror-imageset-config-params.adoc @@ -2,12 +2,13 @@ // // * installing/disconnected_install/installing-mirroring-disconnected.adoc // * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc -// * microshift_running_apps/microshift_operators//microshift-operators-olm.com +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.com :_mod-docs-content-type: REFERENCE [id="oc-mirror-imageset-config-params_{context}"] = Image set configuration parameters +[role="_abstract"] The oc-mirror plugin requires an image set configuration file that defines what images to mirror. The following table lists the available parameters for the `ImageSetConfiguration` resource. // TODO: Consider adding examples for the general "Object" params diff --git a/modules/oc-mirror-mirror-to-mirror.adoc b/modules/oc-mirror-mirror-to-mirror.adoc index 72e8683a37f5..dd3e2986a4aa 100644 --- a/modules/oc-mirror-mirror-to-mirror.adoc +++ b/modules/oc-mirror-mirror-to-mirror.adoc @@ -8,9 +8,10 @@ [id="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. -You are required to specify a storage backend in the image set configuration file. This storage backend can be a local directory or a Docker v2 registry. The oc-mirror plugin stores metadata in this storage backend during image set creation. +You must specify a storage backend in the image set configuration file. This storage backend can be a local directory or a Docker v2 registry. The oc-mirror plugin stores metadata in this storage backend during image set creation. [IMPORTANT] ====