From 1232e862aabfd8d32307dde13659e93b43afbe78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Wed, 21 Feb 2024 14:42:55 -0500 Subject: [PATCH] OSDOCS-8990: Adds oc mirror for MicroShift operator deployment with OLM --- _topic_maps/_topic_map_ms.yml | 21 ++- ...icroshift-deploy-with-mirror-registry.adoc | 2 +- ...shift-embed-in-rpm-ostree-offline-use.adoc | 2 + .../microshift-embed-in-rpm-ostree.adoc | 2 +- .../microshift-install-rpm.adoc | 2 +- .../_attributes | 0 .../images | 0 .../microshift-creating-network-policy.adoc | 0 .../microshift-deleting-network-policy.adoc | 0 .../microshift-editing-network-policy.adoc | 0 .../microshift-network-policy-index.adoc | 0 .../microshift-viewing-network-policy.adoc | 0 .../modules | 0 .../snippets | 0 .../microshift_operators/_attributes | 1 + .../microshift_operators/images | 1 + ...hift-operators-oc-mirror-disconnected.adoc | 26 +++ .../microshift-operators-oc-mirror.adoc | 57 ++++++ .../microshift-operators-olm.adoc | 27 +-- .../microshift-operators.adoc | 8 +- .../microshift_operators/modules | 1 + .../microshift_operators/snippets | 1 + .../microshift-mirror-container-images.adoc | 2 +- modules/microshift-oc-mirror-about-con.adoc | 37 ++++ ...ft-oc-mirror-creating-imageset-config.adoc | 90 +++++++++ ...-oc-mirror-embed-ops-disconnected-use.adoc | 171 ++++++++++++++++++ ...ift-oc-mirror-install-catalog-cluster.adoc | 99 ++++++++++ ...icroshift-oc-mirror-list-ops-catalogs.adoc | 56 ++++++ ...-oc-mirror-transform-imageset-to-crio.adoc | 93 ++++++++++ modules/microshift-olm-build-op-catalogs.adoc | 2 +- ...oshift-olm-deploy-op-disconnected-con.adoc | 19 ++ ...microshift-olm-deploy-op-disconnected.adoc | 19 -- modules/microshift-olm-deploy-ops-con.adoc | 10 +- .../microshift-olm-deploy-ops-global-ns.adoc | 12 +- .../microshift-olm-deploy-ops-spec-ns.adoc | 2 +- modules/microshift-olm-namespaces.adoc | 2 +- .../microshift-ops-config-embed-ostree.adoc | 134 ++++++++++++++ modules/oc-mirror-dry-run.adoc | 3 +- modules/oc-mirror-imageset-config-params.adoc | 19 +- modules/oc-mirror-mirror-to-mirror.adoc | 30 ++- 40 files changed, 878 insertions(+), 73 deletions(-) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/_attributes (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/images (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/microshift-creating-network-policy.adoc (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/microshift-deleting-network-policy.adoc (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/microshift-editing-network-policy.adoc (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/microshift-network-policy-index.adoc (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/microshift-viewing-network-policy.adoc (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/modules (100%) rename microshift_networking/{microshift-network-policy => microshift_network_policy}/snippets (100%) create mode 120000 microshift_running_apps/microshift_operators/_attributes create mode 120000 microshift_running_apps/microshift_operators/images create mode 100644 microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc create mode 100644 microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc rename microshift_running_apps/{ => microshift_operators}/microshift-operators-olm.adoc (62%) rename microshift_running_apps/{ => microshift_operators}/microshift-operators.adoc (58%) create mode 120000 microshift_running_apps/microshift_operators/modules create mode 120000 microshift_running_apps/microshift_operators/snippets create mode 100644 modules/microshift-oc-mirror-about-con.adoc create mode 100644 modules/microshift-oc-mirror-creating-imageset-config.adoc create mode 100644 modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc create mode 100644 modules/microshift-oc-mirror-install-catalog-cluster.adoc create mode 100644 modules/microshift-oc-mirror-list-ops-catalogs.adoc create mode 100644 modules/microshift-oc-mirror-transform-imageset-to-crio.adoc create mode 100644 modules/microshift-olm-deploy-op-disconnected-con.adoc delete mode 100644 modules/microshift-olm-deploy-op-disconnected.adoc create mode 100644 modules/microshift-ops-config-embed-ostree.adoc diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index f03671bb97..9d7fc00a9c 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_topic_maps/_topic_map_ms.yml @@ -403,7 +403,7 @@ Topics: - Name: Using networking settings File: microshift-networking-settings - Name: Network policies - Dir: microshift-network-policy + Dir: microshift_network_policy Topics: - Name: About network policies File: microshift-network-policy-index @@ -455,14 +455,21 @@ Topics: File: microshift-embedding-apps-tutorial - Name: Creating application or workload health check scripts File: microshift-greenboot-workload-scripts -- Name: Pod security authentication and authorization - File: microshift-authentication -- Name: Using Operators - File: microshift-operators -- Name: Using Operator Lifecycle Manager - File: microshift-operators-olm - Name: Automating application management with GitOps File: microshift-gitops +- Name: Pod security authentication and authorization + File: microshift-authentication +- Name: Operators + Dir: microshift_operators + Topics: + - Name: Using Operators + File: microshift-operators + - Name: Using Operator Lifecycle Manager + File: microshift-operators-olm + - Name: Creating custom catalogs with oc-mirror + File: microshift-operators-oc-mirror + - Name: Adding OLM-based Operators to a disconnected cluster + File: microshift-operators-oc-mirror-disconnected --- Name: Backup and restore Dir: microshift_backup_and_restore diff --git a/microshift_install/microshift-deploy-with-mirror-registry.adoc b/microshift_install/microshift-deploy-with-mirror-registry.adoc index 8651c78615..cea1e12782 100644 --- a/microshift_install/microshift-deploy-with-mirror-registry.adoc +++ b/microshift_install/microshift-deploy-with-mirror-registry.adoc @@ -6,7 +6,7 @@ include::_attributes/attributes-microshift.adoc[] toc::[] -You can use a custom container registry when you deploy {microshift-short} in an air-gapped network. Running your cluster in a restricted network without direct internet connectivity is possible by installing the cluster from a mirrored set of container images in a private registry. +You can use a custom container registry when you deploy {microshift-short} in a disconnected network. Running your cluster in a restricted network without direct internet connectivity is possible by installing the cluster from a mirrored set of container images in a private registry. include::modules/microshift-mirror-container-images.adoc[leveloffset=+1] diff --git a/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc b/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc index 4643a78c6e..45e3481dc1 100644 --- a/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc +++ b/microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc @@ -34,3 +34,5 @@ include::modules/microshift-creating-ostree-iso.adoc[leveloffset=+2] * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/composing_a_customized_rhel_system_image/assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image_composing-a-customized-rhel-system-image#con_the-container-registry-credentials_assembly_pushing-a-container-to-a-register-and-embedding-it-into-a-image[Pushing a container to a registry and embedding it into an image] * link:https://osbuild.org/docs/on-premises/installation/container-auth[Container registry credentials] * xref:../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] +* xref:../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] +* xref:../microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc#microshift-operators-oc-mirror[Creating custom catalogs using the oc-mirror plugin] diff --git a/microshift_install/microshift-embed-in-rpm-ostree.adoc b/microshift_install/microshift-embed-in-rpm-ostree.adoc index cb2e906095..3c0dba7cc2 100644 --- a/microshift_install/microshift-embed-in-rpm-ostree.adoc +++ b/microshift_install/microshift-embed-in-rpm-ostree.adoc @@ -35,7 +35,7 @@ include::modules/microshift-adding-olm-to-blueprint.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* xref:../microshift_running_apps/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] +* xref:../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] * xref:../microshift_updating/microshift-update-rpms-ostree.adoc[Applying updates on an OSTree system] include::modules/microshift-ca-adding-bundle.adoc[leveloffset=+1] diff --git a/microshift_install/microshift-install-rpm.adoc b/microshift_install/microshift-install-rpm.adoc index b50ea5cde4..6bc9544ab3 100644 --- a/microshift_install/microshift-install-rpm.adoc +++ b/microshift_install/microshift-install-rpm.adoc @@ -44,7 +44,7 @@ include::modules/microshift-install-rpms-olm.adoc[leveloffset=+1] .Additional resources * xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-system-requirements_microshift-install-rpm[System requirements for installing MicroShift] * xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-rpm-preparing_microshift-install-rpm[Preparing to install MicroShift from an RPM package] -* xref:../microshift_running_apps/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] +* xref:../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}] include::modules/microshift-install-rpms-gitops.adoc[leveloffset=+1] diff --git a/microshift_networking/microshift-network-policy/_attributes b/microshift_networking/microshift_network_policy/_attributes similarity index 100% rename from microshift_networking/microshift-network-policy/_attributes rename to microshift_networking/microshift_network_policy/_attributes diff --git a/microshift_networking/microshift-network-policy/images b/microshift_networking/microshift_network_policy/images similarity index 100% rename from microshift_networking/microshift-network-policy/images rename to microshift_networking/microshift_network_policy/images diff --git a/microshift_networking/microshift-network-policy/microshift-creating-network-policy.adoc b/microshift_networking/microshift_network_policy/microshift-creating-network-policy.adoc similarity index 100% rename from microshift_networking/microshift-network-policy/microshift-creating-network-policy.adoc rename to microshift_networking/microshift_network_policy/microshift-creating-network-policy.adoc diff --git a/microshift_networking/microshift-network-policy/microshift-deleting-network-policy.adoc b/microshift_networking/microshift_network_policy/microshift-deleting-network-policy.adoc similarity index 100% rename from microshift_networking/microshift-network-policy/microshift-deleting-network-policy.adoc rename to microshift_networking/microshift_network_policy/microshift-deleting-network-policy.adoc diff --git a/microshift_networking/microshift-network-policy/microshift-editing-network-policy.adoc b/microshift_networking/microshift_network_policy/microshift-editing-network-policy.adoc similarity index 100% rename from microshift_networking/microshift-network-policy/microshift-editing-network-policy.adoc rename to microshift_networking/microshift_network_policy/microshift-editing-network-policy.adoc diff --git a/microshift_networking/microshift-network-policy/microshift-network-policy-index.adoc b/microshift_networking/microshift_network_policy/microshift-network-policy-index.adoc similarity index 100% rename from microshift_networking/microshift-network-policy/microshift-network-policy-index.adoc rename to microshift_networking/microshift_network_policy/microshift-network-policy-index.adoc diff --git a/microshift_networking/microshift-network-policy/microshift-viewing-network-policy.adoc b/microshift_networking/microshift_network_policy/microshift-viewing-network-policy.adoc similarity index 100% rename from microshift_networking/microshift-network-policy/microshift-viewing-network-policy.adoc rename to microshift_networking/microshift_network_policy/microshift-viewing-network-policy.adoc diff --git a/microshift_networking/microshift-network-policy/modules b/microshift_networking/microshift_network_policy/modules similarity index 100% rename from microshift_networking/microshift-network-policy/modules rename to microshift_networking/microshift_network_policy/modules diff --git a/microshift_networking/microshift-network-policy/snippets b/microshift_networking/microshift_network_policy/snippets similarity index 100% rename from microshift_networking/microshift-network-policy/snippets rename to microshift_networking/microshift_network_policy/snippets diff --git a/microshift_running_apps/microshift_operators/_attributes b/microshift_running_apps/microshift_operators/_attributes new file mode 120000 index 0000000000..93957f0227 --- /dev/null +++ b/microshift_running_apps/microshift_operators/_attributes @@ -0,0 +1 @@ +../_attributes \ No newline at end of file diff --git a/microshift_running_apps/microshift_operators/images b/microshift_running_apps/microshift_operators/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/microshift_running_apps/microshift_operators/images @@ -0,0 +1 @@ +../images \ No newline at end of file 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 new file mode 100644 index 0000000000..2ce9aa562d --- /dev/null +++ b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-operators-oc-mirror-disconnected"] += Adding OLM-based Operators to a disconnected cluster +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. + +//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/installing/microshift-embed-in-rpm-ostree-for-offline-use#microshift-creating-ostree-iso_microshift-embed-rpm-ostree-offline-use[Creating the RHEL for Edge image] +* xref:../../microshift_install/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] diff --git a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc new file mode 100644 index 0000000000..43d7f3c05c --- /dev/null +++ b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc @@ -0,0 +1,57 @@ +:_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://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] +* xref:../../microshift_install/microshift-deploy-with-mirror-registry.adoc#microshift-configuring-hosts-for-mirror_microshift-deployment-mirror[Configuring hosts for mirror registry access] +* xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] +* xref:../../microshift_install/microshift-deploy-with-mirror-registry.adoc#microshift-get-mirror-reg-container-image-list_microshift-deploy-with-mirror-registry[Getting the mirror registry container image list] +* xref:../../microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-in-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use] + +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://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#prerequisites_installing-mirroring-disconnected[Installing the oc mirror plugin] + +include::modules/microshift-oc-mirror-list-ops-catalogs.adoc[leveloffset=+2] + +//First, make the image sets +include::modules/microshift-oc-mirror-creating-imageset-config.adoc[leveloffset=+2] + +//OCP module, reference for valid imageset parameters for microshift; see conditionals +include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+3] + +//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/installing/disconnected-installation-mirroring#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/installing/disconnected-installation-mirroring#mirroring-image-set-partial[Mirroring an image set in a partially disconnected environment] +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#mirroring-image-set-full[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] + +//Apply changes to cluster so it can use Operators +include::modules/microshift-oc-mirror-install-catalog-cluster.adoc[leveloffset=+2] \ No newline at end of file diff --git a/microshift_running_apps/microshift-operators-olm.adoc b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc similarity index 62% rename from microshift_running_apps/microshift-operators-olm.adoc rename to microshift_running_apps/microshift_operators/microshift-operators-olm.adoc index 6f910cd718..1a788623a3 100644 --- a/microshift_running_apps/microshift-operators-olm.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc @@ -8,6 +8,9 @@ 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 cluster, so that the OLM catalog Operator can use the catalog for content. @@ -26,26 +29,26 @@ You can install the OLM package manager for use with {microshift-short} 4.15 or * You can install the `microshift-olm` RPM at the same time you install the {microshift-short} RPM on {op-system-base-full}. * You can install the `microshift-olm` on an existing {microshift-short} {product-version}. Restart the {microshift-short} service after installing OLM for the changes to apply. -See xref:../microshift_install/microshift-install-rpm.adoc#microshift-install-rpms-olm_microshift-install-rpm[Installing the Operator Lifecycle Manager (OLM) from an RPM package]. -* You can embed OLM in a {op-system-ostree-first} image. See xref:../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-adding-olm-to-blueprint_microshift-embed-in-rpm-ostree[Adding the Operator Lifecycle Manager (OLM) service to a blueprint]. +See xref:../../microshift_install/microshift-install-rpm.adoc#microshift-install-rpms-olm_microshift-install-rpm[Installing the Operator Lifecycle Manager (OLM) from an RPM package]. +* You can embed OLM in a {op-system-ostree-first} image. See xref:../../microshift_install/microshift-embed-in-rpm-ostree.adoc#microshift-adding-olm-to-blueprint_microshift-embed-in-rpm-ostree[Adding the Operator Lifecycle Manager (OLM) service to a blueprint]. include::modules/microshift-olm-namespaces.adoc[leveloffset=+1] include::modules/microshift-olm-build-op-catalogs.adoc[leveloffset=+1] -//additional resources for builing catalogs module +//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.openshift.com/container-platform/{ocp-version}/operators/understanding/olm-rh-catalogs.html#olm-about-catalogs_olm-rh-catalogs[About Operator catalogs] -* For instructions about creating file-based catalogs by using the `opm` CLI, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-managing-custom-catalogs[Managing custom catalogs] +* 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.openshift.com/container-platform/4.14/operators/understanding/olm/olm-understanding-operatorgroups.html#olm-operatorgroups-membership_olm-understanding-operatorgroups[Operator group membership] +* link:https://docs.openshift.com/container-platform/{ocp-version}/operators/understanding/olm/olm-understanding-operatorgroups.html#olm-operatorgroups-membership_olm-understanding-operatorgroups[Operator group membership] include::modules/microshift-olm-deploy-ops-global-ns.adoc[leveloffset=+2] @@ -55,16 +58,4 @@ include::modules/microshift-olm-deploy-ops-spec-ns.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources * link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-upgrading-operators[Updating installed Operators] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-deleting-operator-from-a-cluster-using-cli_olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster using the CLI] - -include::modules/microshift-olm-deploy-op-disconnected.adoc[leveloffset=+2] - -//additional resources for deploying operators in disconnected and offline environments -[role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] for more information. -* link:https://docs.openshift.com/container-platform/{ocp-version}/installing/disconnected_install/installing-mirroring-disconnected.html#installing-mirroring-disconnected[Mirroring images for a disconnected installation using the oc-mirror plugin] -* xref:../microshift_install/microshift-deploy-with-mirror-registry.adoc#microshift-configuring-hosts-for-mirror_microshift-deployment-mirror[Configuring hosts for mirror registry access] -* xref:../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] -* xref:../microshift_install/microshift-deploy-with-mirror-registry.adoc#microshift-get-mirror-reg-container-image-list_microshift-deploy-with-mirror-registry[Getting the mirror registry container image list] -* xref:../microshift_install/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-in-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use] +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-deleting-operator-from-a-cluster-using-cli_olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster using the CLI] \ No newline at end of file diff --git a/microshift_running_apps/microshift-operators.adoc b/microshift_running_apps/microshift_operators/microshift-operators.adoc similarity index 58% rename from microshift_running_apps/microshift-operators.adoc rename to microshift_running_apps/microshift_operators/microshift-operators.adoc index bb70dea0b8..e665d028fe 100644 --- a/microshift_running_apps/microshift-operators.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators.adoc @@ -19,8 +19,12 @@ There are two ways to use Operators for your {microshift-short} clusters: [id="microshift-operators-paths-manifests_{context}"] === Manifests for Operators -* Operators can be installed and managed directly by using manifests. You can use the `kustomize` configuration management tool with {microshift-short} to deploy an application. Use the same steps to install Operators with manifests. See xref:../microshift_running_apps/microshift-applications.adoc#microshift-manifests-overview_applications-microshift[Using Kustomize manifests to deploy applications] and xref:../microshift_running_apps/microshift-applications.adoc#microshift-applying-manifests-example_applications-microshift[Using manifests example] for details. +Operators can be installed and managed directly by using manifests. You can use the `kustomize` configuration management tool with {microshift-short} to deploy an application. Use the same steps to install Operators with manifests. + +* See xref:../../microshift_running_apps/microshift-applications.adoc#microshift-manifests-overview_applications-microshift[Using Kustomize manifests to deploy applications] and xref:../../microshift_running_apps/microshift-applications.adoc#microshift-applying-manifests-example_applications-microshift[Using manifests example] for details. [id="microshift-operators-paths-olm_{context}"] === Operator Lifecycle Manager for Operators -* You can also install add-on Operators to a {microshift-short} cluster using Operator Lifecycle Manager (OLM). OLM can be used to manage both custom Operators and Operators that are widely available. Building catalogs is required to use OLM with {microshift-short}. For details, see xref:../microshift_running_apps/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}]. +You can also install add-on Operators to a {microshift-short} cluster using Operator Lifecycle Manager (OLM). OLM can be used to manage both custom Operators and Operators that are widely available. Building catalogs is required to use OLM with {microshift-short}. + +* For details, see xref:../../microshift_running_apps/microshift_operators/microshift-operators-olm.adoc#microshift-operators-olm[Using Operator Lifecycle Manager with {microshift-short}]. diff --git a/microshift_running_apps/microshift_operators/modules b/microshift_running_apps/microshift_operators/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/microshift_running_apps/microshift_operators/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/microshift_running_apps/microshift_operators/snippets b/microshift_running_apps/microshift_operators/snippets new file mode 120000 index 0000000000..9d58b92e50 --- /dev/null +++ b/microshift_running_apps/microshift_operators/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/modules/microshift-mirror-container-images.adoc b/modules/microshift-mirror-container-images.adoc index cf6750d418..4c0ad71230 100644 --- a/modules/microshift-mirror-container-images.adoc +++ b/modules/microshift-mirror-container-images.adoc @@ -12,7 +12,7 @@ To create an air-gapped mirror registry for {microshift-short} containers, you m * Get the container image list to be mirrored. * Configure the mirroring prerequisites. -* Download images on a host with the internet access. +* Download images on a host with internet access. * Copy the downloaded image directory to an air-gapped site. * Upload images to a mirror registry in an air-gapped site. * Configure your {microshift-short} hosts to use the mirror registry. diff --git a/modules/microshift-oc-mirror-about-con.adoc b/modules/microshift-oc-mirror-about-con.adoc new file mode 100644 index 0000000000..c6ebccdef6 --- /dev/null +++ b/modules/microshift-oc-mirror-about-con.adoc @@ -0,0 +1,37 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.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}. + +[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. +==== + +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 Red Hat 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. \ No newline at end of file diff --git a/modules/microshift-oc-mirror-creating-imageset-config.adoc b/modules/microshift-oc-mirror-creating-imageset-config.adoc new file mode 100644 index 0000000000..cb3595819e --- /dev/null +++ b/modules/microshift-oc-mirror-creating-imageset-config.adoc @@ -0,0 +1,90 @@ +// Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.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. + +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. + +[IMPORTANT] +==== +Do not delete or modify the metadata that is generated by the oc-mirror plugin. You must use the same storage backend every time you run the oc-mirror plugin for the same mirror registry. +==== + +.Prerequisites + +* You have created a container image registry credentials file. See link:https://docs.openshift.com/container-platform/{ocp-version}/installing/disconnected_install/installing-mirroring-disconnected.html#installation-adding-registry-pull-secret_installing-mirroring-disconnected[Configuring credentials that allow images to be mirrored]. + +.Procedure + +. Use the `oc mirror init` command to create a template for the image set configuration and save it to a file called `imageset-config.yaml`: ++ +[source,terminal] +---- +$ oc mirror init <--registry > imageset-config.yaml <1> +---- +<1> Specifies the location of your storage backend, such as `example.com/mirror/oc-mirror-metadata`. ++ +.Example default image set configuration file +[source,yaml] +---- +kind: ImageSetConfiguration +apiVersion: mirror.openshift.io/v1alpha2 +storageConfig: + registry: + imageURL: registry.example.com/oc-mirror + skipTLS: false +mirror: + platform: <1> + channels: + - name: stable-4.15 + type: ocp + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: serverless-operator + channels: + - name: stable + additionalImages: <2> + - name: registry.redhat.io/ubi8/ubi:latest + helm: {} <3> +---- +<1> The `platform` field and related fields are not supported by {microshift-short} and must be deleted. +<2> Specify any additional images to include in the image set. If you do not need to specify additional images, delete this field. +<3> Helm is not supported by {microshift-short}, and must be deleted. + +. Edit the values of your image set configuration file to meet the requirements of both {microshift-short} and the Operator you want to mirror, like the following example: ++ +.Example edited {microshift-short} image set configuration file +[source,yaml,subs="attributes+"] +---- +kind: ImageSetConfiguration +apiVersion: mirror.openshift.io/v1alpha2 +storageConfig: <1> + registry: + imageURL: <2> + skipTLS: false +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 <3> + packages: + - name: amq-broker-rhel8 <4> + channels: + - name: 7.11.x <5> +---- +<1> Set the backend location where the image set metadata is saved. This location can be a registry or local directory. It is required to specify `storageConfig` values. +<2> Set the registry URL for the storage backend, such as ` Set the Operator catalog to retrieve images from. +<4> Specify the Operator packages to include in the image set. Remove this field to retrieve all packages in the catalog. +<5> Specify only certain channels of the Operator packages to include in the image set. You must always include the default channel for the Operator package even if you do not use the bundles in that channel. You can find the default channel by running the following command: `oc mirror list operators --catalog= --package=`. + +. Save the updated file. + +.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 clusters. \ No newline at end of file diff --git a/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc b/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc new file mode 100644 index 0000000000..feecec7306 --- /dev/null +++ b/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc @@ -0,0 +1,171 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-oc-mirror-prep-ops-cat-images-disconnected-use_{context}"] += Getting catalogs and Operator container image references to use with RHEL for Edge in disconnected environments + +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. + +[NOTE] +==== +For catalogs made for proprietary Operators, you can format image references for the Image Builder blueprint without using the following procedure. +==== + +.Prerequisites +* You have a catalog index for the Operators you want to use. +* You have installed the `jq` CLI tool. +* You are familiar with Image Builder blueprint files. +* You have an Image Builder blueprint TOML file. + +.Procedure + +. Parse the catalog `index.json` file to get the image references that you need to include in the Image Builder blueprint. You can use either the unfiltered catalog or you can filter out images that cannot be mirrored: + +.. Parse the unfiltered catalog `index.json` file to get the image references by running the following command: ++ +[source,terminal] +---- +jq -r --slurp '.[] | select(.relatedImages != null) | "[[containers]]\nsource = \"" + .relatedImages[].image + "\"\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v4.15/index/index.json +---- + +.. If you want to filter out images that cannot be mirrored, filter and parse the catalog `index.json` file by running the following command: ++ +[source,terminal] +---- +$ jq -r --slurp '.[] | select(.relatedImages != null) | .relatedImages[] | select(.name | contains("ppc") or contains("s390x") | not) | "[[containers]]\\nsource = \\"" + .image + "\\"\\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v4.15/index/index.json +---- ++ +[NOTE] +==== +This step uses the AMQ Broker Operator as an example. You can add other criteria to the `jq` command for further filtering as required by your use case. +==== ++ +.Example image-reference output +[source,terminal] +---- +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0b2126cfb6054fdf428c1f43b69e36e93a09a49ce15350e9273c98cc08c6598b" + +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f" +... +... + +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15" + +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1" +… +EOF +---- ++ +[IMPORTANT] +==== +For mirrored and disconnected use cases, ensure that all of the sources filtered from your catalog `index.json` file are digests. If any of the sources use tags instead of digests, the Operator installation fails. Tags require an internet connection. +==== + +. View the `imageset-config.yaml` to get the catalog image reference for the `CatalogSource` custom resource (CR) by running the following command: ++ +[source,terminal] +---- +$ cat imageset-config.yaml +---- ++ +.Example output +[source,terminal] +---- +kind: ImageSetConfiguration +apiVersion: mirror.openshift.io/v1alpha2 +storageConfig: + registry: + imageURL: registry.example.com/microshift-mirror +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 <1> + packages: + - name: amq-broker-rhel8 + channels: + - name: 7.11.x +---- +<1> Use the value in the `mirror.catalog` catalog image reference for the follwing `jq` command to get the image digest. In this example, __. + +. Get the SHA of the catalog index image by running the following command: ++ +[source,terminal] +---- +$ skopeo inspect docker:// | jq `.Digest` <1> +---- +<1> Use the value in the `mirror.catalog` catalog image reference for the `jq` command to get the image digest. In this example, __. ++ +.Example output +[source,terminal] +---- +"sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6" +---- + +. To get ready to add the image references to your Image Builder blueprint file, format the catalog image reference by using the following example: ++ +[source,terminal] +---- +[[containers]] +source = "registry.redhat.io/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6" +---- + +. Add the image references from all the previous steps to the Image Builder blueprint. ++ +.Generated Image Builder blueprint example snippet +[source,text] +---- +name = "microshift_blueprint" +description = "MicroShift 4.15.1 on x86_64 platform" +version = "0.0.1" +modules = [] +groups = [] + +[[packages]] <1> +name = "microshift" +version = "4.15.1" +... +... + +[customizations.services] <2> +enabled = ["microshift"] + +[customizations.firewall] +ports = ["22:tcp", "80:tcp", "443:tcp", "5353:udp", "6443:tcp", "30000-32767:tcp", "30000-32767:udp"] +... +... + +[[containers]] <3> +source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:f41e79c17e8b41f1b0a5a32c3e2dd7cd15b8274554d3f1ba12b2598a347475f4" + +[[containers]] +source = "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:dbc65f1fba7d92b36cf7514cd130fe83a9bd211005ddb23a8dc479e0eea645fd" +... +... + +[[containers]] <4> +source = "registry.redhat.io/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6" +... +... + +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f" +... +... + +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15" + +[[containers]] +source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1" +… +EOF +---- +<1> References for all non-optional {microshift-short} RPM packages using the same version compatible with the `microshift-release-info` RPM. +<2> References for automatically enabling {microshift-short} on system startup and applying default networking settings. +<3> References for all non-optional {microshift-short} container images necessary for a disconnected deployment. +<4> References for the catalog index. diff --git a/modules/microshift-oc-mirror-install-catalog-cluster.adoc b/modules/microshift-oc-mirror-install-catalog-cluster.adoc new file mode 100644 index 0000000000..61f94c09b7 --- /dev/null +++ b/modules/microshift-oc-mirror-install-catalog-cluster.adoc @@ -0,0 +1,99 @@ +//Module included in the following assemblies: +// +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-oc-mirror-install-catalog-in-cluster_{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 cluster. The `CatalogSource` CR is used by Operator Lifecycle Manager (OLM) 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 + +* You mirrored the image set to your registry mirror. +* You added image reference information to the CRI-O container runtime configuration. + +.Procedure + +. Apply the catalog source configuration file from the results directory to create the catalog source object by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ./oc-mirror-workspace/results-1708508014/catalogSource-cs-redhat-operator-index.yaml +---- ++ +.Example catalog source configuration file +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: redhat-catalog + namespace: openshift-marketplace <1> +spec: + sourceType: grpc + image: registry.example.com/redhat/redhat-operator-index:v4.15 + updateStrategy: + registryPoll: + interval: 60m +---- +<1> Specifies the global namespace. Setting the `metadata.namespace` to `openshift-marketplace` enables the catalog to reference catalogs in all namespaces. Subscriptions in any namespace can reference catalogs created in the `openshift-marketplace` namespace. ++ +.Example output +[source,terminal] +---- +catalogsource.operators.coreos.com/cs-redhat-operator-index created +---- + +. Verify that the `CatalogSource` resources were successfully installed by running the following command: ++ +[source,terminal] +---- +$ oc get catalogsource --all-namespaces +---- +//add example output + +. Verify that the catalog source is running by using the following command: ++ +[source,terminal] +---- +$ oc get pods -n openshift-marketplace +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +cs-redhat-operator-index-4227b 2/2 Running 0 2m5s +---- + +. Create a `Subscription` CR, similar to the following example: ++ +.Example `Subscription` CR +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: amq-broker + namespace: openshift-operators +spec: + channel: 7.11.x + name: amq-broker-rhel8 + source: cs-redhat-operator-index + sourceNamespace: openshift-marketplace +---- + +. Apply the Subscription CR configuration by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ./ <1> +---- +<1> Specify the name of your subscription, such as `my-subscription-cr.yaml`. ++ +.Example output +[source,terminal] +---- +subscription.operators.coreos.com/amq-broker created +---- diff --git a/modules/microshift-oc-mirror-list-ops-catalogs.adoc b/modules/microshift-oc-mirror-list-ops-catalogs.adoc new file mode 100644 index 0000000000..1025dc5b53 --- /dev/null +++ b/modules/microshift-oc-mirror-list-ops-catalogs.adoc @@ -0,0 +1,56 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc + +:_mod-docs-content-type: PROCEDURE +[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 Operators from available {OCP} content to add to your oc-mirror plugin image set configuration file. + +[NOTE] +==== +If you use your own catalogs and Operators, you can push the images directly to your internal registry. +==== + +.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+"] +---- +$ oc mirror list operators --version {product-version} --catalogs +---- + +. Get a list of Operators in the Red{nbsp}Hat Operators catalog by running the following command: ++ +[source,terminal] +---- +$ oc mirror list operators <--catalog=> <1> +---- +<1> Specifies your catalog source, such as `registry.redhat.io/redhat/redhat-operator-index:v{product-version}` or `quay.io/operatorhubio/catalog:latest`. + +. Select an Operator. For this example, `amq-broker-rhel8` is selected. + +. Optional: To inspect the channels and versions of the Operator you want to filter, enter the following commands: + +.. Get a list of channels by running the following command: ++ +[source,terminal] +---- +$ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v4.15 --package=amq-broker-rhel8 +---- +.. Get a list of versions within a channel by running the following command: ++ +[source,terminal] +---- +$ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v4.15 --package=amq-broker-rhel8 --channel=7.11.x +---- + +.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 diff --git a/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc new file mode 100644 index 0000000000..b3cf59d29c --- /dev/null +++ b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc @@ -0,0 +1,93 @@ +//Module included in the following assemblies: +// +// * microshift_running_apps/microshift_operators/microshift-operators-olm.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 + +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 `yq` binary is installed. +* `ImageContentSourcePolicy` and `CatalogSource` YAML files are available in the `oc-mirror-workspace/results-*` directory. + +.Procedure + +. Confirm the contents of the `imageContentSourcePolicy.yaml` file by running the following command: ++ +[source,terminal] +---- +$ cat oc-mirror-workspace//imageContentSourcePolicy.yaml <1> +---- +<1> Specify the `results` directory name, such as ``. ++ +.Example output +[source,terminal] +---- +apiVersion: operator.openshift.io/v1alpha1 +kind: ImageContentSourcePolicy +metadata: + labels: + operators.openshift.org/catalog: "true" + name: operator-0 +spec: + repositoryDigestMirrors: + - mirrors: + - registry./amq7 + source: registry.redhat.io/amq7 +---- + +. Transform the `imageContentSourcePolicy.yaml` into a format ready for CRI-O configuration by running the following command: ++ +[source,terminal] +---- +yq '.spec.repositoryDigestMirrors[] as $item ireduce([]; . + [{"mirror": $item.mirrors[], "source": ($item | .source)}]) | .[] | + "[[registry]] + prefix = \"" + .source + "\" + location = \"" + .mirror + "\" + mirror-by-digest-only = true + insecure = true + "' ./icsp.yaml +---- ++ +.Example output +[source,terminal] +---- +[[registry]] + prefix = "registry.redhat.io/amq7" + location = "registry.example.com/amq7" + mirror-by-digest-only = true + insecure = true +---- + +. Add the output to the CRI-O configuration file in the `/etc/containers/registries.conf.d/` directory: ++ +.Example `crio-config.yaml` mirror configuration file +[source,yaml] +---- +[[registry]] + prefix = "registry.redhat.io/amq7" + location = "registry.example.com/amq7" + mirror-by-digest-only = true + insecure = true + +[[registry]] + prefix = "" + location = "quay.io" + mirror-by-digest-only = true +[[registry.mirror]] + location = ":" <1> + insecure = false +---- +<1> Specify the host name 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 32856b8db9..bfa1f40aa1 100644 --- a/modules/microshift-olm-build-op-catalogs.adoc +++ b/modules/microshift-olm-build-op-catalogs.adoc @@ -1,6 +1,6 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc :_mod-docs-content-type: CONCEPT [id="microshift-options-building-operator-catalogs_{context}"] diff --git a/modules/microshift-olm-deploy-op-disconnected-con.adoc b/modules/microshift-olm-deploy-op-disconnected-con.adoc new file mode 100644 index 0000000000..78eaaaf733 --- /dev/null +++ b/modules/microshift-olm-deploy-op-disconnected-con.adoc @@ -0,0 +1,19 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-adding-OLM-Operators-to-disconnected-cluster_{context}"] += About adding OLM-based Operators to a disconnected cluster + +For Operators that are installed on disconnected clusters, 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. + +The following steps are required to use OLM-based 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}. +* Add a `CatalogSource` object to the cluster so that the OLM catalog Operator can use the local catalog on the mirror registry. +* Ensure that {microshift-short} is installed to run in a disconnected capacity. +* Ensure that the network settings are configured to run in disconnected mode. + +After enabling OLM in a disconnected cluster, you can continue to use your internet-connected workstation to keep your local catalog sources updated as newer versions of Operators are released. diff --git a/modules/microshift-olm-deploy-op-disconnected.adoc b/modules/microshift-olm-deploy-op-disconnected.adoc deleted file mode 100644 index 43c55f38fc..0000000000 --- a/modules/microshift-olm-deploy-op-disconnected.adoc +++ /dev/null @@ -1,19 +0,0 @@ -//Module included in the following assemblies: -// -//* microshift_running_apps/microshift-operators-olm.adoc - -:_mod-docs-content-type: CONCEPT -[id="microshift-adding-OLM-Operators-to-offline-cluster_{context}"] -= About adding OLM-based Operators to an offline cluster - -For {microshift-short} clusters that are installed on disconnected or offline clusters, Operator Lifecycle Manager (OLM) by default cannot access sources hosted on remote registries because those remote sources require full internet connectivity. - -The following steps are required to use OLM-based Operators in offline situations: - -* Include OLM in your container image list for your mirror registry. -* Configure the system to use the mirror by updating your CRI-O configuration directly. `ImageContentSourcePolicy` is not supported in {microshift-short}. -* Add a `CatalogSource` object to the cluster so that the OLM catalog Operator can use the local catalog on the mirror registry. -* Ensure that {microshift-short} is installed to run in an offline capacity. -* Ensure that the network settings are configured to run in a disconnected mode. - -After enabling OLM in an offline cluster, you can continue to use your unrestricted workstation to keep your local catalog sources updated as newer versions of Operators are released. diff --git a/modules/microshift-olm-deploy-ops-con.adoc b/modules/microshift-olm-deploy-ops-con.adoc index 57d42cf925..2484efd099 100644 --- a/modules/microshift-olm-deploy-ops-con.adoc +++ b/modules/microshift-olm-deploy-ops-con.adoc @@ -1,10 +1,10 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc :_mod-docs-content-type: CONCEPT -[id="microshift-deploy-operators_{context}"] -= How to deploy Operators +[id="microshift-olm-deploy-operators_{context}"] += How to deploy Operators using OLM 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. @@ -13,8 +13,8 @@ After you create and deploy your custom catalog, you must create a Subscription Operators in OLM have a watch scope. For example, some Operators only support watching their own namespace, while others support watching every namespace in the cluster. All Operators installed in a given namespace must have the same watch scope. ==== -[id="microshift-operators-connection-details_{context}"] -== Connectivity and Operator deployment +[id="microshift-olm-operators-connection-details_{context}"] +== Connectivity and OLM Operator deployment Operators can be deployed anywhere a catalog is running. * For clusters that are connected to the internet, mirroring images is not required. Images can be pulled over the network. diff --git a/modules/microshift-olm-deploy-ops-global-ns.adoc b/modules/microshift-olm-deploy-ops-global-ns.adoc index e6fc3dd3c8..da162828a1 100644 --- a/modules/microshift-olm-deploy-ops-global-ns.adoc +++ b/modules/microshift-olm-deploy-ops-global-ns.adoc @@ -1,6 +1,6 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-OLM-deploy-Operators_{context}"] @@ -75,16 +75,16 @@ spec: interval: 60m ---- <1> The global namespace. Setting the `metadata.namespace` to `openshift-marketplace` enables the catalog to run in all namespaces. Subscriptions in any namespace can reference catalogs created in the `openshift-marketplace` namespace. -<2> Community Operators are not installed by default with OLM for {miroshift-short}. Listed here for example only. +<2> Community Operators are not installed by default with OLM for {microshift-short}. Listed here for example only. <3> The value of `securityContextConfig` must be set to `restricted` for {microshift-short}. . Apply the `CatalogSource` configuration by running the following command: + [source,terminal] ---- -$ oc apply -f __ <1> +$ oc apply -f <1> ---- -<1> Replace __ with your catalog source configuration file name. In this example, `catalogsource.yaml` is used. +<1> Replace `` with your catalog source configuration file name. In this example, `catalogsource.yaml` is used. + .Example output [source,terminal] @@ -174,9 +174,9 @@ spec: + [source,terminal] ---- -$ oc apply -f __ <1> +$ oc apply -f <1> ---- -<1> Replace __ with your Subscription CR filename. In this example, `sub.yaml` is used. +<1> Replace `` with your Subscription CR filename. In this example, `sub.yaml` is used. + .Example output [source,terminal] diff --git a/modules/microshift-olm-deploy-ops-spec-ns.adoc b/modules/microshift-olm-deploy-ops-spec-ns.adoc index 38da22caa6..1d057fff6e 100644 --- a/modules/microshift-olm-deploy-ops-spec-ns.adoc +++ b/modules/microshift-olm-deploy-ops-spec-ns.adoc @@ -1,6 +1,6 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-OLM-deploy-Operators-specific-namespace_{context}"] diff --git a/modules/microshift-olm-namespaces.adoc b/modules/microshift-olm-namespaces.adoc index 54763905ce..32487164dc 100644 --- a/modules/microshift-olm-namespaces.adoc +++ b/modules/microshift-olm-namespaces.adoc @@ -1,6 +1,6 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc :_mod-docs-content-type: CONCEPT [id="microshift-olm-namespaces_{context}"] diff --git a/modules/microshift-ops-config-embed-ostree.adoc b/modules/microshift-ops-config-embed-ostree.adoc new file mode 100644 index 0000000000..264405bd4a --- /dev/null +++ b/modules/microshift-ops-config-embed-ostree.adoc @@ -0,0 +1,134 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-olm.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 + +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. + +.Procedure + +. Create a `CatalogSource` custom resource (CR), similar to the following example: ++ +.Example `my-catalog-source-cr.yaml` file +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: cs-redhat-operator-index + namespace: openshift-marketplace <1> +spec: + image: registry.example.com/redhat/redhat-operator-index:v4.15 + sourceType: grpc + displayName: + publisher: + updateStrategy: + registryPoll: + interval: 60m +---- +<1> The global namespace. Setting the `metadata.namespace` to `openshift-marketplace` enables the catalog to run in all namespaces. Subscriptions in any namespace can reference catalogs created in the `openshift-marketplace` namespace. ++ +[NOTE] +==== +The default pod security admission definition for `openshift-marketplace` is `baseline`, therefore a catalog source custom resource (CR) created in that namespace does not require a `spec.grpcPodConfig.securityContextConfig` value to be set. You can set a `legacy` or `restricted` value if required for the namespace and Operators you want to use. +==== + +. Add the SHA of the catalog index commit to the Catalog Source (CR), similar to the following example: ++ +.Example namespace `spec.image` configuration +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: cs-redhat-operator-index + namespace: openshift-marketplace +spec: + image: registry.example.com/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6 <1> + sourceType: grpc + displayName: + publisher: + updateStrategy: + registryPoll: + interval: 60m +---- +<1> The SHA of the image commit. Use the same SHA you added to the Image Builder blueprint. ++ +[IMPORTANT] +==== +You must use the SHA instead of a tag in your catalog CR or the pod fails to start. +==== + +. Apply the YAML file from the oc-mirror plugin dry run results directory to the cluster by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ./oc-mirror-workspace/results-1708508014/catalogSource-cs-redhat-operator-index.yaml +---- ++ +.Example output +[source,terminal] +---- +catalogsource.operators.coreos.com/cs-redhat-operator-index created +---- + +. Verify that the `CatalogSource` resources were successfully installed by running the following command: ++ +[source,terminal] +---- +$ oc get catalogsource --all-namespaces +---- +//Example output + +. Verify that the catalog source is running by using the following command: ++ +[source,terminal] +---- +$ oc get pods -n openshift-marketplace +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +cs-redhat-operator-index-4227b 2/2 Running 0 2m5s +---- + +. Create a `Subscription` CR, similar to the following example: ++ +.Example `my-subscription-cr.yaml` file +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: amq-broker + namespace: openshift-operators +spec: + channel: 7.11.x + name: amq-broker-rhel8 + source: cs-redhat-operator-index + sourceNamespace: openshift-marketplace +---- + +. Apply the `Subscription` CR by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ./ <1> +---- +<1> Specify the name of your `Subscription` CR, such as `my-subscription-cr.yaml`. ++ +.Example output +[source,terminal] +---- +subscription.operators.coreos.com/amq-broker created +---- diff --git a/modules/oc-mirror-dry-run.adoc b/modules/oc-mirror-dry-run.adoc index 9c1e2a6af2..aa2c7fa4d3 100644 --- a/modules/oc-mirror-dry-run.adoc +++ b/modules/oc-mirror-dry-run.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.adoc :_mod-docs-content-type: PROCEDURE [id="oc-mirror-dry-run_{context}"] = Performing a dry run -You can use oc-mirror to perform a dry run, without actually mirroring any images. This allows you to review the list of images that would be mirrored, as well as any images that would be pruned from the mirror registry. It also allows you to catch any errors with your image set configuration early or use the generated list of images with other tools to carry out the mirroring operation. +You can use oc-mirror to perform a dry run, without actually mirroring any images. This allows you to review the list of images that would be mirrored, as well as any images that would be pruned from the mirror registry. A dry run also allows you to catch any errors with your image set configuration early or use the generated list of images with other tools to carry out the mirroring operation. .Prerequisites diff --git a/modules/oc-mirror-imageset-config-params.adoc b/modules/oc-mirror-imageset-config-params.adoc index 822857b602..b52d9cfad9 100644 --- a/modules/oc-mirror-imageset-config-params.adoc +++ b/modules/oc-mirror-imageset-config-params.adoc @@ -2,6 +2,7 @@ // // * 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 :_mod-docs-content-type: REFERENCE [id="oc-mirror-imageset-config-params_{context}"] @@ -22,10 +23,14 @@ The oc-mirror plugin requires an image set configuration file that defines what |The API version for the `ImageSetConfiguration` content. |String. For example: `mirror.openshift.io/v1alpha2`. +ifndef::microshift[] + |`archiveSize` |The maximum size, in GiB, of each archive file within the image set. |Integer. For example: `4` +endif::microshift[] + |`mirror` |The configuration of the image set. |Object @@ -48,6 +53,8 @@ additionalImages: |The full tag, digest, or pattern of images to block from mirroring. |Array of strings. For example: `docker.io/library/alpine` +ifndef::microshift[] + |`mirror.helm` |The helm configuration of the image set. Note that the oc-mirror plugin supports only helm charts that do not require user input when rendered. |Object @@ -105,6 +112,8 @@ repositories: |The version of the named helm chart to mirror. |String. For example: `5.0.0`. +endif::microshift[] + |`mirror.operators` |The Operators configuration of the image set. |Array of objects. For example: @@ -190,6 +199,8 @@ The `targetName` parameter is deprecated. Use the `targetCatalog` parameter inst |An alternative tag to append to the `targetName` or `targetCatalog`. |String. For example: `v1` +ifndef::microshift[] + |`mirror.platform` |The platform configuration of the image set. |Object @@ -249,6 +260,8 @@ channels: |Indicates whether the OSUS graph is added to the image set and subsequently published to the mirror. |Boolean. The default value is `false`. +endif::microshift[] + |`storageConfig` |The back-end configuration of the image set. |Object @@ -277,9 +290,9 @@ channels: [NOTE] ==== -Using the `minVersion` and `maxVersion` properties to filter for a specific Operator version range can result in a multiple channel heads error. The error message will state that there are `multiple channel heads`. This is because when the filter is applied, the update graph of the operator is truncated. +Using the `minVersion` and `maxVersion` properties to filter for a specific Operator version range can result in a multiple channel heads error. The error message states that there are `multiple channel heads`. This is because when the filter is applied, the update graph of the Operator is truncated. -The Operator Lifecycle Manager requires that every operator channel contains versions that form an update graph with exactly one end point, that is, the latest version of the operator. When applying the filter range that graph can turn into two or more separate graphs or a graph that has more than one end point. +Operator Lifecycle Manager requires that every Operator channel contains versions that form an update graph with exactly one end point, that is, the latest version of the Operator. When the filter range is applied, that graph can turn into two or more separate graphs or a graph that has more than one end point. -To avoid this error, do not filter out the latest version of an operator. If you still run into the error, depending on the operator, either the `maxVersion` property needs to be increased or the `minVersion` property needs to be decreased. Because every operator graph can be different, you might need to adjust these values, according to the procedure, until the error is gone. +To avoid this error, do not filter out the latest version of an Operator. If you still run into the error, depending on the Operator, either the `maxVersion` property must be increased or the `minVersion` property must be decreased. Because every Operator graph can be different, you might need to adjust these values until the error resolves. ==== diff --git a/modules/oc-mirror-mirror-to-mirror.adoc b/modules/oc-mirror-mirror-to-mirror.adoc index 9cee4adbed..72e8683a37 100644 --- a/modules/oc-mirror-mirror-to-mirror.adoc +++ b/modules/oc-mirror-mirror-to-mirror.adoc @@ -2,6 +2,7 @@ // // * 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-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="oc-mirror-mirror-to-mirror_{context}"] @@ -18,7 +19,7 @@ Do not delete or modify the metadata that is generated by the oc-mirror plugin. .Prerequisites -* You have access to the internet to obtain the necessary container images. +* You have access to the internet to get the necessary container images. * You have installed the OpenShift CLI (`oc`). * You have installed the `oc-mirror` CLI plugin. * You have created the image set configuration file. @@ -29,27 +30,46 @@ Do not delete or modify the metadata that is generated by the oc-mirror plugin. + [source,terminal] ---- -$ oc mirror --config=./imageset-config.yaml \// <1> +$ oc mirror --config=./ \// <1> docker://registry.example:5000 <2> ---- -<1> Pass in the image set configuration file that was created. This procedure assumes that it is named `imageset-config.yaml`. +<1> Specify the image set configuration file that you created. For example, `imageset-config.yaml`. <2> Specify the registry to mirror the image set file to. The registry must start with `docker://`. If you specify a top-level namespace for the mirror registry, you must also use this same namespace on subsequent executions. +ifdef::microshift[] +.Example output +[source,terminal] +---- +Rendering catalog image "registry.example.com/redhat/redhat-operator-index:v{ocp-version}" with file-based catalog +---- +endif::microshift[] + .Verification . Navigate into the `oc-mirror-workspace/` directory that was generated. . Navigate into the results directory, for example, `results-1639608409/`. . Verify that YAML files are present for the `ImageContentSourcePolicy` and `CatalogSource` resources. +ifndef::microshift[] [NOTE] ==== The `repositoryDigestMirrors` section of the `ImageContentSourcePolicy` YAML file is used for the `install-config.yaml` file during installation. ==== -+ +endif::microshift[] // TODO: Test and get some better wording/example output. -.Next steps +ifdef::microshift[] +[IMPORTANT] +==== +The `ImageContentSourcePolicy` YAML file is used as reference content for manual configuration of CRI-O in {microshift-short}. You cannot apply the resource directly into a {microshift-short} cluster. +==== +endif::microshift[] +.Next steps +ifdef::microshift[] +* Convert the `ImageContentSourcePolicy` YAML content for use in manually configuring CRI-O. +* If required, mirror the images from mirror to disk for disconnected or offline use. +endif::microshift[] * Configure your cluster to use the resources generated by oc-mirror. .Troubleshooting