diff --git a/content/learn/disconnected-installation.adoc b/content/learn/disconnected-installation.adoc new file mode 100644 index 000000000..84ebfe4b2 --- /dev/null +++ b/content/learn/disconnected-installation.adoc @@ -0,0 +1,199 @@ +--- +menu: + learn: + parent: Patterns quick start +title: Deploying in a disconnected network +weight: 22 +aliases: /learn/disconnected-installation/ +--- + +:toc: +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +[id="disconnected-installation"] +== Deploying a validated pattern in a disconnected network + +A disconnected (air-gapped) network is an infrastructure that is isolated from +external internet access. Deploying {solution-name-upstream} in such an +environment requires additional steps to mirror container images, configure +internal registries, and adjust pattern configuration files. + +This guide walks through deploying the {mcg-pattern} on {ocp} 4.19 in +a disconnected network. The same approach applies to other validated patterns, +though the specific list of images and operators will vary by pattern. + +== Prerequisites + +* One or more {ocp} clusters deployed in a disconnected network +* An OCI-compliant registry accessible from the disconnected network (referred + to as `registry.internal.disconnected.net` in this guide) +* A Git repository accessible from the disconnected network +* (Optional) A VM in the disconnected network from which to run commands + +[NOTE] +==== +Deploying {ocp} in a disconnected network is out of scope for this guide. See the +https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/disconnected_environments/index#about-installing-oc-mirror-v2[{ocp} disconnected environments documentation] +for details. +==== + +== Mirroring container images + +The first step is to mirror all required container images to the internal +registry. The exact list of images depends on the pattern, the {ocp} version, +and the required operators. The list of images will depend on the pattern, +the below is an example for Multicloud GitOps. + +This guide uses `oc mirror --v2`. Create an `imageset-config.yaml` file that +lists the required platform images, operators, and additional images: + +[source,yaml] +---- +kind: ImageSetConfiguration +apiVersion: mirror.openshift.io/v2alpha1 +mirror: + platform: + graph: true + channels: + - name: stable-4.19 + type: ocp + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.19 + packages: + - name: lvms-operator + - name: advanced-cluster-management + channels: + - name: release-2.14 + - name: openshift-external-secrets-operator + channels: + - name: stable-v1 + - name: multicluster-engine + channels: + - name: stable-2.9 + - name: openshift-gitops-operator + channels: + - name: gitops-1.19 + - catalog: registry.redhat.io/redhat/community-operator-index:v4.19 + packages: + - name: patterns-operator + additionalImages: + - name: registry.redhat.io/ubi9/ubi-minimal:latest + - name: registry.connect.redhat.com/hashicorp/vault:1.20.2-ubi + - name: registry.access.redhat.com/ubi8/httpd-24:10.0-1755779646 + - name: ghcr.io/external-secrets/external-secrets:v0.10.2-ubi + # Validated Patterns Helm charts + - name: quay.io/validatedpatterns/acm:0.1.17 + - name: quay.io/validatedpatterns/clustergroup:0.9.41 + - name: quay.io/validatedpatterns/gitea:0.0.3 + - name: quay.io/validatedpatterns/golang-external-secrets:0.1.5 + - name: quay.io/validatedpatterns/openshift-external-secrets:0.0.3 + - name: quay.io/validatedpatterns/hashicorp-vault:0.1.6 + - name: quay.io/validatedpatterns/utility-container:latest + - name: quay.io/validatedpatterns/imperative-container:v1 + - name: quay.io/validatedpatterns/pattern-install:0.0.11 + - name: docker.io/gitea/gitea:1.22.6-rootless +---- + +Run the mirror command, specifying a local cache directory and the target +registry: + +[source,sh] +---- +oc mirror --config=/var/cache/oc-mirror/imageset-config.yaml \ + --workspace file:///var/cache/oc-mirror/workspace \ + docker://registry.internal.disconnected.net --v2 +---- + +Once mirroring completes, `oc mirror` generates resource files under +`/var/cache/oc-mirror/workspace/working-dir/cluster-resources`. Apply these to +the cluster so that it can resolve images from the internal registry: + +[source,sh] +---- +cd /var/cache/oc-mirror/workspace/working-dir/cluster-resources +oc apply -f cs-community-operator-index-v4-19.yaml \ + cs-redhat-operator-index-v4-19.yaml idms-oc-mirror.yaml \ + itms-oc-mirror.yaml +---- + +[IMPORTANT] +==== +The catalog source names generated by `oc mirror` (for example, +`cs-redhat-operator-index-v4-19`) are needed in the next step when configuring +the pattern's values files. +==== + +== Configuring the pattern for disconnected use + +The pattern's values files must be updated to reference the mirrored catalog +sources and the internal Helm chart registry. Ensure your local Git clone has +its `origin` remote pointing to the disconnected Git server (verify with +`git remote -v`). + +=== values-global.yaml + +Point the Helm chart repository to the internal registry and configure operator +sources: + +[source,yaml] +---- +main: + multiSourceConfig: + enabled: true + clusterGroupChartVersion: "0.9.*" + helmRepoUrl: registry.internal.disconnected.net/validatedpatterns + patternsOperator: + source: cs-community-operator-index-v4-19 + gitops: + operatorSource: cs-redhat-operator-index-v4-19 +---- + +=== values-hub.yaml + +Configure operator sources for hub-specific components: + +[source,yaml] +---- +acm: + mce_operator: + source: cs-redhat-operator-index-v4-19 + +clusterGroup: + subscriptions: + acm: + name: advanced-cluster-management + namespace: open-cluster-management + channel: release-2.14 + source: cs-redhat-operator-index-v4-19 +---- + +Commit and push these changes to the disconnected Git server. + +== Deploying the pattern + +With images mirrored and the pattern configured, deploy from a machine that has +access to both the disconnected cluster and the Git repository: + +[source,sh] +---- +# Point the installer to the mirrored Helm chart +export PATTERN_DISCONNECTED_HOME=registry.internal.disconnected.net/validatedpatterns +./pattern.sh make install +---- + +The cluster will converge to the desired state and the pattern will be +installed. + +== Adapting this guide for other patterns + +The steps above use the {mcg-pattern} as an example. When deploying a different +pattern in a disconnected network: + +* Identify all operators required by the pattern and add them to the + `imageset-config.yaml` operator list. +* Identify all additional container images referenced by the pattern's Helm + charts and add them to the `additionalImages` list. +* Update each values file (`values-global.yaml`, `values-hub.yaml`, and any + site-specific values files) to reference the correct catalog source names for + all operator subscriptions. diff --git a/content/learn/quickstart.adoc b/content/learn/quickstart.adoc index 64d2f68c8..40200ac33 100644 --- a/content/learn/quickstart.adoc +++ b/content/learn/quickstart.adoc @@ -55,5 +55,5 @@ Before beginning, ensure you have the following: * An OCI-compliant registry that is accessible from the disconnected network * A Git Repository that is accessible from the disconnected network -For more information on disconnected installation, see link:/blog/2024-10-12-disconnected/[Validated Patterns in a disconnected Network]. +For more information on disconnected installation, see link:/learn/disconnected-installation/[Deploying in a disconnected network].