From a2f837abe0c623574d8ba4a48df9b30ec336cd1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Mon, 1 Jun 2026 15:26:08 -0400 Subject: [PATCH 1/2] OSDOCS-19851: adds disconnected instal docs RHCL --- _topic_maps/_topic_map.yml | 4 +- {install-guide => install-rhcl}/_attributes | 0 {install-guide => install-rhcl}/images | 0 .../install-guide.adoc | 0 {install-guide => install-rhcl}/modules | 0 install-rhcl/rhcl-install-disconnected.adoc | 30 ++++ {install-guide => install-rhcl}/snippets | 0 modules/con-rhcl-install-disconnected.adoc | 28 +++ ...c-rhcl-disconnected-install-operators.adoc | 160 ++++++++++++++++++ ...hcl-disconnected-install-ts-cat-image.adoc | 32 ++++ ...proc-rhcl-disconnected-install-ts-ops.adoc | 35 ++++ ...cl-disconnected-install-ts-pods-stuck.adoc | 42 +++++ ...proc-rhcl-disconnected-mirror-catalog.adoc | 117 +++++++++++++ modules/ref-relnotes-new-features.adoc | 6 + 14 files changed, 453 insertions(+), 1 deletion(-) rename {install-guide => install-rhcl}/_attributes (100%) rename {install-guide => install-rhcl}/images (100%) rename {install-guide => install-rhcl}/install-guide.adoc (100%) rename {install-guide => install-rhcl}/modules (100%) create mode 100644 install-rhcl/rhcl-install-disconnected.adoc rename {install-guide => install-rhcl}/snippets (100%) create mode 100644 modules/con-rhcl-install-disconnected.adoc create mode 100644 modules/proc-rhcl-disconnected-install-operators.adoc create mode 100644 modules/proc-rhcl-disconnected-install-ts-cat-image.adoc create mode 100644 modules/proc-rhcl-disconnected-install-ts-ops.adoc create mode 100644 modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc create mode 100644 modules/proc-rhcl-disconnected-mirror-catalog.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 2f9b133f3bf1..1add12e58fe6 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -45,11 +45,13 @@ Topics: File: rhcl-release-notes --- Name: Installing Connectivity Link -Dir: install-guide +Dir: install-rhcl Distros: rhcl Topics: - Name: Installing Connectivity Link File: install-guide +- Name: Installing Connectivity Link in a disconnected environment + File: rhcl-install-disconnected --- Name: Installing the MCP gateway Dir: mcp_gateway_install diff --git a/install-guide/_attributes b/install-rhcl/_attributes similarity index 100% rename from install-guide/_attributes rename to install-rhcl/_attributes diff --git a/install-guide/images b/install-rhcl/images similarity index 100% rename from install-guide/images rename to install-rhcl/images diff --git a/install-guide/install-guide.adoc b/install-rhcl/install-guide.adoc similarity index 100% rename from install-guide/install-guide.adoc rename to install-rhcl/install-guide.adoc diff --git a/install-guide/modules b/install-rhcl/modules similarity index 100% rename from install-guide/modules rename to install-rhcl/modules diff --git a/install-rhcl/rhcl-install-disconnected.adoc b/install-rhcl/rhcl-install-disconnected.adoc new file mode 100644 index 000000000000..75947a8c1fcc --- /dev/null +++ b/install-rhcl/rhcl-install-disconnected.adoc @@ -0,0 +1,30 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/attributes.adoc[] +[id="rhcl-install-disconnected"] += Installing {prodname} in a disconnected environment +:context: rhcl-install-disconnected + +toc::[] + +[role="_abstract"] +You can use {prodname} in a disconnected environment to apply the speed and automation of cloud-like traffic management within your private, secure network. + +include::modules/con-rhcl-install-disconnected.adoc[leveloffset=+1] + +include::modules/proc-rhcl-disconnected-mirror-catalog.adoc[leveloffset=+1] + +include::modules/proc-rhcl-disconnected-install-operators.adoc[leveloffset=+1] + +include::modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc[leveloffset=+1] + +include::modules/proc-rhcl-disconnected-install-ts-cat-image.adoc[leveloffset=+1] + +include::modules/proc-rhcl-disconnected-install-ts-ops.adoc[leveloffset=+1] + +[id="additional-resources_disconnected-install"] +[role="_additional-resources"] +== Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/images/managing-images[Managing image settings (OpenShift Container Platform documentation)] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/operators/administrator-tasks#olm-managing-custom-catalogs[Managing custom catalogs (OpenShift Container Platform documentation)] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/installing-mirroring-disconnected-about[Disconnected installation overview (OpenShift Container Platform documentation)] diff --git a/install-guide/snippets b/install-rhcl/snippets similarity index 100% rename from install-guide/snippets rename to install-rhcl/snippets diff --git a/modules/con-rhcl-install-disconnected.adoc b/modules/con-rhcl-install-disconnected.adoc new file mode 100644 index 000000000000..9713f974d080 --- /dev/null +++ b/modules/con-rhcl-install-disconnected.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// *install-guide/disconnected-install.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-rhcl-install-disconnected_{context}"] += Installing {prodname} in disconnected clusters + +[role="_abstract"] +By using {prodname} as disconnected gateway, you can securely route traffic, enforce rate limits, and perform automated failover between your isolated clusters. You can also automate internal TLS certificate management and manage all internal networking and security policies. + +{prodname} consists of four Operators bundled in a single combined catalog: + +* {prodname} Operator: Provides policy attachment and Gateway API integration. Includes runtime images for wasm-shim and console-plugin. +* Authorino Operator: Provides authentication and authorization engine. Includes the `authorino` runtime image. +* Limitador Operator: Provides rate limiting engine. Includes the `limitador` runtime image. +* DNS Operator: Provides multi-cluster DNS management. Includes the `coredns-kuadrant` runtime image. + +The catalog image is available at `quay.io/kuadrant/kuadrant-operator-catalog:latest`. All four Operators are available from this catalog. The {prodname} Operator declares the other three Operators as dependencies through Operator Lifecycle Manager (OLM). + +You install {prodname} Operators in disconnected {ocp} environments by mirroring the Operator catalog and images to your internal registry. Use the `oc-mirror` tool to perform the following actions: + +* Mirror the catalog image. +* Discover the following Operator bundles in the catalog: {prodname}, Authorino, Limitador, and DNS. +* Mirror all images from each bundle's `relatedImages` section. +* Generate the `ImageDigestMirrorSet` object for runtime images. +* Generate the `ImageTagMirrorSet` object for catalog and bundle images. +* Generate the `CatalogSource` manifest. diff --git a/modules/proc-rhcl-disconnected-install-operators.adoc b/modules/proc-rhcl-disconnected-install-operators.adoc new file mode 100644 index 000000000000..de467d40a4ad --- /dev/null +++ b/modules/proc-rhcl-disconnected-install-operators.adoc @@ -0,0 +1,160 @@ +// Module included in the following assemblies: +// +// *install-guide/disconnected-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-disconnected-install-operators_{context}"] += Installing {prodname} Operators + +[role="_abstract"] +After you mirrored all of the {prodname} Operator bundles, you are ready to install it into your disconnected {ocp} clusters. Repeat the process as needed for each cluster that shares the registry. + +.Prerequisites + +* You have a supported-version, disconnected {ocp} cluster. +* You configured a mirror registry. +* You mirrored the {prodname} Operator bundles. +* Optional. You installed the `oc-mirror` CLI tool for mirroring operator catalogs. + +.Procedure + +. Create a namespace for {prodname} by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc new-project kuadrant-system +---- +//Q: can the user change this namespace name? + +. Create an `OperatorGroup` custom resource (CR) by running the following command: ++ +[source,yaml,subs="+quotes"] +---- +apiVersion: operators.coreos.com/v1 +kind: OperatorGroup +metadata: + name: kuadrant-operator-group + namespace: kuadrant-system +spec: {} +---- ++ +[IMPORTANT] +==== +The empty `spec: {}` is required. {prodname} Operators support only the `AllNamespaces`, or cluster-scoped, install mode. Do not set the `targetNamespaces` parameter. +==== +//Q: can the user change the namespace name? + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f kuadrant-operator-group.yaml +---- + +. Query the default channel from the `PackageManifest` by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ CHANNEL=$(oc get packagemanifest kuadrant-operator -n openshift-marketplace \ + -o jsonpath='{.status.defaultChannel}') +---- + +. Create a `Subscription` resource by running the following command: ++ +[source,yaml,subs="+quotes"] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: kuadrant-operator + namespace: kuadrant-system +spec: + channel: ${CHANNEL} + name: kuadrant-operator + source: kuadrant-disconnected-catalog + sourceNamespace: openshift-marketplace + installPlanApproval: Automatic +---- ++ +[NOTE] +==== +Replace the `spec.source` parameter value with the `CatalogSource` name from `oc-mirror` if it differs. OLM automatically installs the Authorino, Limitador, and DNS Operators based on the dependencies declared in the {prodname} Operator bundle. +==== +//Q: don't know what this means; better to show an actual example from the previous step to this one + +. Apply the CR by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f kuadrant-operator.yaml +---- + +. Verify that all Operator `ClusterServiceVersion` resources are installed by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get csv -n kuadrant-system +---- ++ +.Example output +[source,text] +---- +NAME DISPLAY VERSION REPLACES PHASE +kuadrant-operator.vX.Y.Z Kuadrant Operator X.Y.Z Succeeded +authorino-operator.vX.Y.Z Authorino Operator X.Y.Z Succeeded +limitador-operator.vX.Y.Z Limitador Operator X.Y.Z Succeeded +dns-operator.vX.Y.Z DNS Operator X.Y.Z Succeeded +---- + +. Verify that all pods are running by using the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get pods -n kuadrant-system +---- + +. Create a `Kuadrant` custom resource (CR) by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ cat <_/kuadrant/kuadrant-operator-catalog:latest +---- ++ +Replace `__` with the path to your mirror registry. diff --git a/modules/proc-rhcl-disconnected-install-ts-ops.adoc b/modules/proc-rhcl-disconnected-install-ts-ops.adoc new file mode 100644 index 000000000000..cec18864b5a7 --- /dev/null +++ b/modules/proc-rhcl-disconnected-install-ts-ops.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// *install-guide/disconnected-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-disconnected-install-ts-ops_{context}"] += Dependent Operators are not installing + +[role="_abstract"] +If you only see the {prodname} Operator `ClusterServiceVersion`, but the Authorino, Limitador, or DNS Operators are missing, the catalog might be missing digest references or the dependencies are not declared. You can track the source of the problem by checking a couple of resources. + +.Prerequisites + +* You completed a disconnected installation of {prodname}. + +.Procedure + +. Verify that all four Operators are available as `PackageManifest` resources by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get packagemanifest -n openshift-marketplace | grep -E +'(kuadrant|authorino|limitador|dns)-operator' +---- +//Q: if one or more are missing, what do we do about it? + +. Check that the `InstallPlan` shows all dependencies by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get installplan -n kuadrant-system -o yaml +---- ++ +Look for all four Operators in the `InstallPlan` specification output. +//Q: if one or more are missing, what do we do about it? diff --git a/modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc b/modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc new file mode 100644 index 000000000000..8c8ada7c01b9 --- /dev/null +++ b/modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// *install-guide/disconnected-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-disconnected-install-ts-pods-stuck_{context}"] += Troubleshooting stuck pods in a disconnected installation + +[role="_abstract"] +If your pods are stuck with an `ImagePullBackOff` status, this might mean that the image is either not in the mirror registry or that the `ImageDigestMirrorSet` object not applied correctly. +//Q: should we specify an image here? + +.Prerequisites + +* You completed a disconnected installation of {prodname}. + +.Procedure + +. Verify that `ImageDigestMirrorSet` exists by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc get imagedigestmirrorset +---- + +. Check whether the specific image was mirrored by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc image info __/kuadrant/kuadrant-operator@sha256:__ +---- ++ +Replace `__` with the complete digest value. + +. Check pod events by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc describe pod __ -n kuadrant-system +---- ++ +Replace `__` with the name of the stuck pod. diff --git a/modules/proc-rhcl-disconnected-mirror-catalog.adoc b/modules/proc-rhcl-disconnected-mirror-catalog.adoc new file mode 100644 index 000000000000..1d8c1199426b --- /dev/null +++ b/modules/proc-rhcl-disconnected-mirror-catalog.adoc @@ -0,0 +1,117 @@ +// Module included in the following assemblies: +// +// *install-guide/disconnected-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-disconnected-mirror-catalog_{context}"] += Mirroring the {prodname} catalog + +[role="_abstract"] +To begin your disconnected {prodname} installation, you must mirror the Operator catalog. By mirroring, you are making a complete local copy of {prodname} on a private container registry that your isolated cluster can reach. + +[NOTE] +==== +Applying `ImageDigestMirrorSet` or `ImageTagMirrorSet` objects triggers `MachineConfig` object updates and restarts cluster nodes. +==== + +.Prerequisites + +* You have a supported-version, disconnected {ocp} cluster. +* You configured a mirror registry. +* You have either an `ImageDigestMirrorSet` or `ImageTagMirrorSet` object configured for platform images. +* Optional. You installed the `oc-mirror` CLI tool for mirroring operator catalogs. + +.Procedure + +. If you are using the `oc mirror` tool, add the {prodname} catalog to your `ImageSetConfiguration` file by using the following example: ++ +.Example `ImageSetConfiguration` YAML +[source,yaml] +---- +kind: ImageSetConfiguration +apiVersion: mirror.openshift.io/v2alpha1 +mirror: + operators: + - catalog: quay.io/kuadrant/kuadrant-operator-catalog:latest + full: true +---- ++ +This catalog has all of the Operators and their dependencies. + +. Optional: If you plan to use the DNS Operator CoreDNS deployment feature, add the CoreDNS image to your `ImageSetConfiguration` YAML file by adding the following configuration snippet: ++ +[source,yaml] +---- +additionalImages: + - name: quay.io/kuadrant/coredns-kuadrant:latest +---- ++ +. If you are not using the `oc mirror` tool, mirror the CoreDNS image directly by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc image mirror quay.io/kuadrant/coredns-kuadrant:latest \ + __/kuadrant/coredns-kuadrant:latest +---- + +. Mirror the Operator catalog and images to your registry by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc-mirror --config imageset-config.yaml docker://__ +---- ++ +Replace `__` with the path to your mirror registry. + +. Apply the generated `ImageDigestMirrorSet` configuration by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f oc-mirror-workspace/results-*/imageDigestMirrorSet.yaml +---- + +. Apply the generated `ImageTagMirrorSet` configuration by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f oc-mirror-workspace/results-*/imageTagMirrorSet.yaml +---- + +. Wait for the `MachineConfigPool` object to update by running the following command: ++ +[source,terminal] +---- +$ oc wait mcp --all --for=condition=Updated --timeout=30m +---- ++ +.Example output +[source,text] +---- +machineconfigpool.machineconfiguration.openshift.io/master condition met +machineconfigpool.machineconfiguration.openshift.io/worker condition met +---- + +. Apply the generated `CatalogSource` manifest by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc apply -f oc-mirror-workspace/results-*/catalogSource-*.yaml +---- +//Q: instead of the stars, can we give generic examples? + +. Wait for the Operator catalog to be ready by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ oc wait catalogsource -n openshift-marketplace --all --for=condition=Ready --timeout=5m +---- ++ +.Example output +[source,text] +---- +catalogsource.operators.coreos.com/certified-operators condition met +catalogsource.operators.coreos.com/community-operators condition met +catalogsource.operators.coreos.com/redhat-marketplace condition met +catalogsource.operators.coreos.com/redhat-operators condition met +catalogsource.operators.coreos.com/rhcl-operator-catalog condition met +---- diff --git a/modules/ref-relnotes-new-features.adoc b/modules/ref-relnotes-new-features.adoc index 0a50ddf59093..4ad25f8a8421 100644 --- a/modules/ref-relnotes-new-features.adoc +++ b/modules/ref-relnotes-new-features.adoc @@ -9,6 +9,12 @@ [role="_abstract"] You can use the new features and enhancements that are available with {product-title} {version}. +Disconnected installation documentation added:: + +The {prodname} documentation now includes procedures for installing in a disconnected environment. You can apply cloud-like traffic management within your private, secure network. + +//For more information, see xref:../install-rhcl/rhcl-install-disconnected.adoc#rhcl-install-disconnected[Installing Connectivity Link in a disconnected environment] + MCP gateway: MCP prompt federation is now available:: {mcpg} adds support for federating MCP prompts through the `Gateway` object as a Generally Available feature. MCP prompt federation makes it much easier to supply your large language models (LLMs) with the exact context and steering instructions they need, no matter which server originally hosted the template. From c4e72d58269b9878566e8e9d365e5d2f1ddc02c8 Mon Sep 17 00:00:00 2001 From: Michael Nairn Date: Wed, 3 Jun 2026 10:38:32 -0700 Subject: [PATCH 2/2] docs: Simplify RHCL disconnected installation to follow Red Hat patterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: Current RHCL disconnected docs use upstream catalog (quay.io/kuadrant), wrong package name (kuadrant-operator), and single-step mirroring that doesn't work for true air-gapped environments. Solution: Simplified docs that: 1. Use Red Hat catalog with correct package name (rhcl-operator) 2. Show two-step mirroring (mirror to disk → transfer → push to registry) 3. Focus on RHCL-specific details only, reference existing OLM disconnected docs for generic setup 4. Remove troubleshooting modules with wrong package names Pattern: Matches how other Red Hat operators document disconnected installation (HCP, MCE, Loki). Critical fixes: - Package name: kuadrant-operator → rhcl-operator - Catalog: quay.io/kuadrant/... → registry.redhat.io/redhat/redhat-operator-index - Mirroring: Single-step → Two-step disk-based workflow - CoreDNS image: quay.io/kuadrant/... → registry.redhat.io/rhcl-1/coredns-rhel9 Signed-off-by: Michael Nairn --- install-rhcl/rhcl-install-disconnected.adoc | 22 +-- modules/con-rhcl-install-disconnected.adoc | 27 ++-- ...roc-rhcl-disconnected-create-kuadrant.adoc | 73 ++++++++++ ...c-rhcl-disconnected-install-operators.adoc | 132 ++++++------------ ...hcl-disconnected-install-ts-cat-image.adoc | 32 ----- ...proc-rhcl-disconnected-install-ts-ops.adoc | 35 ----- ...cl-disconnected-install-ts-pods-stuck.adoc | 42 ------ ...proc-rhcl-disconnected-mirror-catalog.adoc | 105 +++++++------- 8 files changed, 188 insertions(+), 280 deletions(-) create mode 100644 modules/proc-rhcl-disconnected-create-kuadrant.adoc delete mode 100644 modules/proc-rhcl-disconnected-install-ts-cat-image.adoc delete mode 100644 modules/proc-rhcl-disconnected-install-ts-ops.adoc delete mode 100644 modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc diff --git a/install-rhcl/rhcl-install-disconnected.adoc b/install-rhcl/rhcl-install-disconnected.adoc index 75947a8c1fcc..46e1872cf6b0 100644 --- a/install-rhcl/rhcl-install-disconnected.adoc +++ b/install-rhcl/rhcl-install-disconnected.adoc @@ -7,7 +7,14 @@ include::_attributes/attributes.adoc[] toc::[] [role="_abstract"] -You can use {prodname} in a disconnected environment to apply the speed and automation of cloud-like traffic management within your private, secure network. +You can install {prodname} on an {ocp} cluster in a disconnected environment by mirroring the required operator catalog and installing the {prodname} operator from your local mirror registry. + +.Prerequisites + +* A disconnected {ocp} cluster version 4.14 or later +* Access to the cluster as a user with the `cluster-admin` role +* Configured mirror registry accessible from the cluster +* For general Operator Lifecycle Manager configuration in disconnected environments, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager in disconnected environments] include::modules/con-rhcl-install-disconnected.adoc[leveloffset=+1] @@ -15,16 +22,11 @@ include::modules/proc-rhcl-disconnected-mirror-catalog.adoc[leveloffset=+1] include::modules/proc-rhcl-disconnected-install-operators.adoc[leveloffset=+1] -include::modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc[leveloffset=+1] - -include::modules/proc-rhcl-disconnected-install-ts-cat-image.adoc[leveloffset=+1] - -include::modules/proc-rhcl-disconnected-install-ts-ops.adoc[leveloffset=+1] +include::modules/proc-rhcl-disconnected-create-kuadrant.adoc[leveloffset=+1] -[id="additional-resources_disconnected-install"] [role="_additional-resources"] == Additional resources -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/images/managing-images[Managing image settings (OpenShift Container Platform documentation)] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/operators/administrator-tasks#olm-managing-custom-catalogs[Managing custom catalogs (OpenShift Container Platform documentation)] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/installing-mirroring-disconnected-about[Disconnected installation overview (OpenShift Container Platform documentation)] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager in disconnected environments] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/installing-mirroring-installation-images[Mirroring images for a disconnected installation] +* link:https://docs.redhat.com[Red Hat Connectivity Link documentation] diff --git a/modules/con-rhcl-install-disconnected.adoc b/modules/con-rhcl-install-disconnected.adoc index 9713f974d080..507fa673f48f 100644 --- a/modules/con-rhcl-install-disconnected.adoc +++ b/modules/con-rhcl-install-disconnected.adoc @@ -4,25 +4,22 @@ :_mod-docs-content-type: CONCEPT [id="con-rhcl-install-disconnected_{context}"] -= Installing {prodname} in disconnected clusters += About installing {prodname} in disconnected environments [role="_abstract"] -By using {prodname} as disconnected gateway, you can securely route traffic, enforce rate limits, and perform automated failover between your isolated clusters. You can also automate internal TLS certificate management and manage all internal networking and security policies. +{prodname} provides policy-driven traffic management for {ocp} clusters using Gateway API. In a disconnected environment, you must mirror the {prodname} operator catalog and its container images to your local registry before installation. -{prodname} consists of four Operators bundled in a single combined catalog: +The installation process involves the following steps: -* {prodname} Operator: Provides policy attachment and Gateway API integration. Includes runtime images for wasm-shim and console-plugin. -* Authorino Operator: Provides authentication and authorization engine. Includes the `authorino` runtime image. -* Limitador Operator: Provides rate limiting engine. Includes the `limitador` runtime image. -* DNS Operator: Provides multi-cluster DNS management. Includes the `coredns-kuadrant` runtime image. +. Mirror the Red Hat operator catalog containing the {prodname} operator package to your local registry +. Configure the cluster to use the mirrored catalog +. Install the {prodname} operator using Operator Lifecycle Manager (OLM) +. Create a `Kuadrant` custom resource to deploy the {prodname} components -The catalog image is available at `quay.io/kuadrant/kuadrant-operator-catalog:latest`. All four Operators are available from this catalog. The {prodname} Operator declares the other three Operators as dependencies through Operator Lifecycle Manager (OLM). +The {prodname} operator automatically installs the following dependency operators: -You install {prodname} Operators in disconnected {ocp} environments by mirroring the Operator catalog and images to your internal registry. Use the `oc-mirror` tool to perform the following actions: +* Authorino Operator - Authentication and authorization +* Limitador Operator - Rate limiting +* DNS Operator - DNS management -* Mirror the catalog image. -* Discover the following Operator bundles in the catalog: {prodname}, Authorino, Limitador, and DNS. -* Mirror all images from each bundle's `relatedImages` section. -* Generate the `ImageDigestMirrorSet` object for runtime images. -* Generate the `ImageTagMirrorSet` object for catalog and bundle images. -* Generate the `CatalogSource` manifest. +All required images are included when you mirror the `rhcl-operator` package from the Red Hat catalog. diff --git a/modules/proc-rhcl-disconnected-create-kuadrant.adoc b/modules/proc-rhcl-disconnected-create-kuadrant.adoc new file mode 100644 index 000000000000..7e845227ff0f --- /dev/null +++ b/modules/proc-rhcl-disconnected-create-kuadrant.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// *install-guide/disconnected-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="proc-rhcl-disconnected-create-kuadrant_{context}"] += Creating a Kuadrant custom resource + +[role="_abstract"] +After installing the {prodname} operator, create a `Kuadrant` custom resource to deploy the {prodname} components. + +.Prerequisites + +* You have installed the {prodname} operator +* The {prodname} operator is running in the `kuadrant-system` namespace + +.Procedure + +. Create a `Kuadrant` custom resource: ++ +[source,yaml] +---- +apiVersion: kuadrant.io/v1beta1 +kind: Kuadrant +metadata: + name: kuadrant + namespace: kuadrant-system +spec: {} +---- + +. Apply the `Kuadrant` custom resource: ++ +[source,terminal] +---- +$ oc apply -f kuadrant.yaml +---- + +.Verification + +. Verify the `Kuadrant` resource is ready: ++ +[source,terminal] +---- +$ oc get kuadrant kuadrant -n kuadrant-system +---- ++ +.Example output +[source,terminal] +---- +NAME STATUS AGE +kuadrant Ready 2m +---- + +. Verify all component operator pods are running: ++ +[source,terminal] +---- +$ oc get pods -n kuadrant-system +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +authorino-operator-controller-manager- 2/2 Running 0 5m +dns-operator-controller-manager- 2/2 Running 0 5m +kuadrant-operator-controller-manager- 2/2 Running 0 7m +limitador-operator-controller-manager- 2/2 Running 0 5m +---- + +.Next steps + +* Configure Gateway API resources to use {prodname} policies. See link:https://docs.redhat.com[{prodname} documentation] for examples. diff --git a/modules/proc-rhcl-disconnected-install-operators.adoc b/modules/proc-rhcl-disconnected-install-operators.adoc index de467d40a4ad..1726a09b8208 100644 --- a/modules/proc-rhcl-disconnected-install-operators.adoc +++ b/modules/proc-rhcl-disconnected-install-operators.adoc @@ -4,31 +4,28 @@ :_mod-docs-content-type: PROCEDURE [id="proc-rhcl-disconnected-install-operators_{context}"] -= Installing {prodname} Operators += Installing the {prodname} operator [role="_abstract"] -After you mirrored all of the {prodname} Operator bundles, you are ready to install it into your disconnected {ocp} clusters. Repeat the process as needed for each cluster that shares the registry. +After mirroring the catalog, you can install the {prodname} operator using Operator Lifecycle Manager (OLM). .Prerequisites -* You have a supported-version, disconnected {ocp} cluster. -* You configured a mirror registry. -* You mirrored the {prodname} Operator bundles. -* Optional. You installed the `oc-mirror` CLI tool for mirroring operator catalogs. +* You have mirrored the {prodname} operator catalog to your local registry +* You have applied the catalog source to your cluster .Procedure -. Create a namespace for {prodname} by running the following command: +. Create a namespace for {prodname}: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- -$ oc new-project kuadrant-system +$ oc create namespace kuadrant-system ---- -//Q: can the user change this namespace name? -. Create an `OperatorGroup` custom resource (CR) by running the following command: +. Create an `OperatorGroup` for the {prodname} operator: + -[source,yaml,subs="+quotes"] +[source,yaml] ---- apiVersion: operators.coreos.com/v1 kind: OperatorGroup @@ -37,124 +34,77 @@ metadata: namespace: kuadrant-system spec: {} ---- -+ -[IMPORTANT] -==== -The empty `spec: {}` is required. {prodname} Operators support only the `AllNamespaces`, or cluster-scoped, install mode. Do not set the `targetNamespaces` parameter. -==== -//Q: can the user change the namespace name? - -. Apply the CR by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc apply -f kuadrant-operator-group.yaml ----- -. Query the default channel from the `PackageManifest` by running the following command: +. Apply the `OperatorGroup`: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- -$ CHANNEL=$(oc get packagemanifest kuadrant-operator -n openshift-marketplace \ - -o jsonpath='{.status.defaultChannel}') +$ oc apply -f operatorgroup.yaml ---- -. Create a `Subscription` resource by running the following command: +. Create a `Subscription` for the {prodname} operator: + -[source,yaml,subs="+quotes"] +[source,yaml] ---- apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: - name: kuadrant-operator + name: rhcl-operator namespace: kuadrant-system spec: - channel: ${CHANNEL} - name: kuadrant-operator - source: kuadrant-disconnected-catalog + channel: stable <1> + name: rhcl-operator + source: <2> sourceNamespace: openshift-marketplace - installPlanApproval: Automatic ---- + +<1> Specify `stable` as the channel. +<2> Specify the name of the `CatalogSource` object created by `oc-mirror`. You can find the catalog source name by running `oc get catalogsource -n openshift-marketplace`. ++ [NOTE] ==== -Replace the `spec.source` parameter value with the `CatalogSource` name from `oc-mirror` if it differs. OLM automatically installs the Authorino, Limitador, and DNS Operators based on the dependencies declared in the {prodname} Operator bundle. +OLM automatically installs the Authorino, Limitador, and DNS operators based on the dependencies declared in the {prodname} operator bundle. ==== -//Q: don't know what this means; better to show an actual example from the previous step to this one -. Apply the CR by running the following command: +. Apply the `Subscription`: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- -$ oc apply -f kuadrant-operator.yaml +$ oc apply -f subscription.yaml ---- -. Verify that all Operator `ClusterServiceVersion` resources are installed by running the following command: +.Verification + +. Verify the {prodname} operator installed successfully: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- $ oc get csv -n kuadrant-system ---- + .Example output -[source,text] +[source,terminal] ---- NAME DISPLAY VERSION REPLACES PHASE -kuadrant-operator.vX.Y.Z Kuadrant Operator X.Y.Z Succeeded authorino-operator.vX.Y.Z Authorino Operator X.Y.Z Succeeded -limitador-operator.vX.Y.Z Limitador Operator X.Y.Z Succeeded dns-operator.vX.Y.Z DNS Operator X.Y.Z Succeeded +kuadrant-operator.vX.Y.Z Kuadrant Operator X.Y.Z Succeeded +limitador-operator.vX.Y.Z Limitador Operator X.Y.Z Succeeded ---- -. Verify that all pods are running by using the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc get pods -n kuadrant-system ----- - -. Create a `Kuadrant` custom resource (CR) by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ cat < 2/2 Running 0 3m +dns-operator-controller-manager- 2/2 Running 0 3m +kuadrant-operator-controller-manager- 2/2 Running 0 5m +limitador-operator-controller-manager- 2/2 Running 0 3m ---- -+ -The output should show no image pull failures. -+ -[NOTE] -==== -Pod specifications still show original image references, for example, `quay.io/kuadrant/...`, even when images are pulled from your mirror registry. The redirection happens transparently at the CRI-O level through `ImageDigestMirrorSet` or `ImageTagMirrorSet` configuration objects. -==== diff --git a/modules/proc-rhcl-disconnected-install-ts-cat-image.adoc b/modules/proc-rhcl-disconnected-install-ts-cat-image.adoc deleted file mode 100644 index 855838d06971..000000000000 --- a/modules/proc-rhcl-disconnected-install-ts-cat-image.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// *install-guide/disconnected-install.adoc - -:_mod-docs-content-type: PROCEDURE -[id="proc-rhcl-disconnected-install-ts-cat-image_{context}"] -= Troubleshooting a catalog image not accessible - -[role="_abstract"] -If your `CatalogSource` object shows a `READY=False` status, the catalog image is not accessible from your mirror registry. You can check pod logs and check that the catalog image exists to troubleshoot this situation. - -.Prerequisites - -* You completed a disconnected installation of {prodname}. - -.Procedure - -. Check the catalog pod logs by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc logs -n openshift-marketplace -l olm.catalogSource=kuadrant-disconnected-catalog ----- - -. Verify that the catalog image exists in the mirror registry by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc image info __/kuadrant/kuadrant-operator-catalog:latest ----- -+ -Replace `__` with the path to your mirror registry. diff --git a/modules/proc-rhcl-disconnected-install-ts-ops.adoc b/modules/proc-rhcl-disconnected-install-ts-ops.adoc deleted file mode 100644 index cec18864b5a7..000000000000 --- a/modules/proc-rhcl-disconnected-install-ts-ops.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// *install-guide/disconnected-install.adoc - -:_mod-docs-content-type: PROCEDURE -[id="proc-rhcl-disconnected-install-ts-ops_{context}"] -= Dependent Operators are not installing - -[role="_abstract"] -If you only see the {prodname} Operator `ClusterServiceVersion`, but the Authorino, Limitador, or DNS Operators are missing, the catalog might be missing digest references or the dependencies are not declared. You can track the source of the problem by checking a couple of resources. - -.Prerequisites - -* You completed a disconnected installation of {prodname}. - -.Procedure - -. Verify that all four Operators are available as `PackageManifest` resources by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc get packagemanifest -n openshift-marketplace | grep -E -'(kuadrant|authorino|limitador|dns)-operator' ----- -//Q: if one or more are missing, what do we do about it? - -. Check that the `InstallPlan` shows all dependencies by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc get installplan -n kuadrant-system -o yaml ----- -+ -Look for all four Operators in the `InstallPlan` specification output. -//Q: if one or more are missing, what do we do about it? diff --git a/modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc b/modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc deleted file mode 100644 index 8c8ada7c01b9..000000000000 --- a/modules/proc-rhcl-disconnected-install-ts-pods-stuck.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// *install-guide/disconnected-install.adoc - -:_mod-docs-content-type: PROCEDURE -[id="proc-rhcl-disconnected-install-ts-pods-stuck_{context}"] -= Troubleshooting stuck pods in a disconnected installation - -[role="_abstract"] -If your pods are stuck with an `ImagePullBackOff` status, this might mean that the image is either not in the mirror registry or that the `ImageDigestMirrorSet` object not applied correctly. -//Q: should we specify an image here? - -.Prerequisites - -* You completed a disconnected installation of {prodname}. - -.Procedure - -. Verify that `ImageDigestMirrorSet` exists by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc get imagedigestmirrorset ----- - -. Check whether the specific image was mirrored by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc image info __/kuadrant/kuadrant-operator@sha256:__ ----- -+ -Replace `__` with the complete digest value. - -. Check pod events by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc describe pod __ -n kuadrant-system ----- -+ -Replace `__` with the name of the stuck pod. diff --git a/modules/proc-rhcl-disconnected-mirror-catalog.adoc b/modules/proc-rhcl-disconnected-mirror-catalog.adoc index 1d8c1199426b..58aeb7d00c00 100644 --- a/modules/proc-rhcl-disconnected-mirror-catalog.adoc +++ b/modules/proc-rhcl-disconnected-mirror-catalog.adoc @@ -4,80 +4,69 @@ :_mod-docs-content-type: PROCEDURE [id="proc-rhcl-disconnected-mirror-catalog_{context}"] -= Mirroring the {prodname} catalog += Mirroring the {prodname} operator catalog [role="_abstract"] -To begin your disconnected {prodname} installation, you must mirror the Operator catalog. By mirroring, you are making a complete local copy of {prodname} on a private container registry that your isolated cluster can reach. - -[NOTE] -==== -Applying `ImageDigestMirrorSet` or `ImageTagMirrorSet` objects triggers `MachineConfig` object updates and restarts cluster nodes. -==== +You can mirror the Red Hat operator catalog containing the {prodname} operator to your disconnected environment using the `oc-mirror` plugin. .Prerequisites -* You have a supported-version, disconnected {ocp} cluster. -* You configured a mirror registry. -* You have either an `ImageDigestMirrorSet` or `ImageTagMirrorSet` object configured for platform images. -* Optional. You installed the `oc-mirror` CLI tool for mirroring operator catalogs. +* You have installed the `oc-mirror` CLI plugin +* You have access to `registry.redhat.io` on an internet-connected workstation +* You have credentials for your mirror registry configured in `${HOME}/.docker/config.json` .Procedure -. If you are using the `oc mirror` tool, add the {prodname} catalog to your `ImageSetConfiguration` file by using the following example: +. On your internet-connected workstation, create an `ImageSetConfiguration` file named `rhcl-imageset-config.yaml`: + -.Example `ImageSetConfiguration` YAML -[source,yaml] +[source,yaml,subs="attributes+"] ---- -kind: ImageSetConfiguration apiVersion: mirror.openshift.io/v2alpha1 +kind: ImageSetConfiguration mirror: operators: - - catalog: quay.io/kuadrant/kuadrant-operator-catalog:latest - full: true + - catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version} <1> + packages: + - name: rhcl-operator <2> + additionalImages: + - name: registry.redhat.io/rhcl-1/coredns-rhel9:vX.Y.Z <3> ---- + -This catalog has all of the Operators and their dependencies. +<1> Specify the Red Hat operator catalog version matching your {ocp} cluster version. +<2> The {prodname} operator package. Dependency operators (Authorino, Limitador, DNS) are included automatically. +<3> Optional. The CoreDNS image if you plan to use the DNS Operator CoreDNS deployment feature. Replace `vX.Y.Z` with the version matching the {prodname} operator release. -. Optional: If you plan to use the DNS Operator CoreDNS deployment feature, add the CoreDNS image to your `ImageSetConfiguration` YAML file by adding the following configuration snippet: +. Mirror the catalog to a local directory: + -[source,yaml] +[source,terminal] ---- -additionalImages: - - name: quay.io/kuadrant/coredns-kuadrant:latest +$ oc mirror --v2 --config rhcl-imageset-config.yaml file://./rhcl-mirror ---- + -. If you are not using the `oc mirror` tool, mirror the CoreDNS image directly by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc image mirror quay.io/kuadrant/coredns-kuadrant:latest \ - __/kuadrant/coredns-kuadrant:latest ----- +This command downloads the catalog and operator images to the `rhcl-mirror` directory. -. Mirror the Operator catalog and images to your registry by running the following command: -+ -[source,terminal,subs="+quotes"] ----- -$ oc-mirror --config imageset-config.yaml docker://__ ----- -+ -Replace `__` with the path to your mirror registry. +. Transfer the `rhcl-mirror` directory to your disconnected environment using removable media. -. Apply the generated `ImageDigestMirrorSet` configuration by running the following command: +. On a host in the disconnected environment with access to your mirror registry, push the images to the registry: + [source,terminal,subs="+quotes"] ---- -$ oc apply -f oc-mirror-workspace/results-*/imageDigestMirrorSet.yaml +$ oc mirror --v2 --config rhcl-imageset-config.yaml \ + --from file://./rhcl-mirror \ + docker://__:__ ---- ++ +Replace `__` and `__` with your mirror registry details. -. Apply the generated `ImageTagMirrorSet` configuration by running the following command: +. Apply the `ImageDigestMirrorSet` or `ImageTagMirrorSet` to configure the cluster to use the mirrored images: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- -$ oc apply -f oc-mirror-workspace/results-*/imageTagMirrorSet.yaml +$ oc apply -f results-*/cluster-resources/idms-oc-mirror.yaml +$ oc apply -f results-*/cluster-resources/itms-oc-mirror.yaml ---- -. Wait for the `MachineConfigPool` object to update by running the following command: +. Wait for the `MachineConfigPool` to update: + [source,terminal] ---- @@ -90,28 +79,34 @@ $ oc wait mcp --all --for=condition=Updated --timeout=30m machineconfigpool.machineconfiguration.openshift.io/master condition met machineconfigpool.machineconfiguration.openshift.io/worker condition met ---- ++ +[NOTE] +==== +This step restarts the kubelet on all nodes to apply the new registry configuration. +==== -. Apply the generated `CatalogSource` manifest by running the following command: +. Apply the `CatalogSource` manifest: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- -$ oc apply -f oc-mirror-workspace/results-*/catalogSource-*.yaml +$ oc apply -f results-*/cluster-resources/catalogSource-*.yaml ---- -//Q: instead of the stars, can we give generic examples? -. Wait for the Operator catalog to be ready by running the following command: +. Verify the catalog source is ready: + -[source,terminal,subs="+quotes"] +[source,terminal] ---- -$ oc wait catalogsource -n openshift-marketplace --all --for=condition=Ready --timeout=5m +$ oc wait catalogsource -n openshift-marketplace \ + --all --for=condition=Ready --timeout=5m ---- + .Example output [source,text] ---- -catalogsource.operators.coreos.com/certified-operators condition met -catalogsource.operators.coreos.com/community-operators condition met -catalogsource.operators.coreos.com/redhat-marketplace condition met -catalogsource.operators.coreos.com/redhat-operators condition met -catalogsource.operators.coreos.com/rhcl-operator-catalog condition met +catalogsource.operators.coreos.com/rhcl-operator-catalog- condition met ---- + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html/disconnected_environments/about-installing-oc-mirror-v2#oc-mirror-workflows-fully-disconnected-v2_about-installing-oc-mirror-v2[Mirroring an image set in a fully disconnected environment]