Update the Helm procedure to use oc-mirror for air-gapped OCP environments (redhat-developer#868)

* fix: Update the Helm procedure to use oc-mirror for air-gapped OCP environments

Co-authored-by: Lindsey Frazier <lfrazier@redhat.com>
Co-authored-by: Armel Soro <asoro@redhat.com>

* Update modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc

---------

Co-authored-by: Lindsey Frazier <lfrazier@redhat.com>
Co-authored-by: Armel Soro <asoro@redhat.com>

Author: 3 people

modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc

@@ -2,137 +2,284 @@
 // no assembly
 
 [id="proc-install-rhdh-airgapped-environment-ocp-helm_{context}"]
-= Installing {product} in an air-gapped environment with the Helm Chart
+= Installing {product} on {ocp-short} in an air-gapped environment with the Helm chart
 
-An air-gapped environment, also known as an air-gapped network or isolated network, ensures security by physically segregating the system or network. This isolation is established to prevent unauthorized access, data transfer, or communication between the air-gapped system and external sources.
+You can install {product} in a fully disconnected or partially disconnected environment using the {product} Helm chart.
 
-You can install {product} in an air-gapped environment to ensure security and meet specific regulatory requirements.
+[role="_additional-resources"]
+.Additional resources
+* For more information about registry authentication, see https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication].
 
-To install {product-short} in an air-gapped environment, you must have access to the `registry.redhat.io` and the registry for the air-gapped environment.
+== Installing {product} on {ocp-short} in a partially disconnected environment with the Helm chart
+
+If your network has access to the `registry.redhat.io` registry and the `charts.openshift.io` Helm chart repository, you can deploy your {product} instance in your partially disconnected environment by mirroring the specified resources directly to the target registry.
 
 .Prerequisites
 
-* You have installed an {ocp-brand-name} {ocp-version-min} or later.
+* You have installed {ocp-brand-name} {ocp-version-min} or later.
+* You have access to the `charts.openshift.io` Helm chart repository.
 * You have access to the `registry.redhat.io`.
-* You have access to the {ocp-brand-name} image registry of your cluster. For more information about exposing the image registry, see the {ocp-brand-name} documentation about https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/registry/index#securing-exposing-registry[Exposing the registry].
+* You have access to a mirror registry that can be reached from the disconnected cluster, for example, the {ocp-short} image registry. For more information about exposing the {ocp-short} image registry, see https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/registry/index#securing-exposing-registry[Exposing the registry].
+* You are logged in to your target mirror registry and have permissions to push images to it. For more information, see link:https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-adding-registry-pull-secret_installing-mirroring-disconnected[Configuring credentials that allow images to be mirrored].
 * You have installed the {openshift-cli} on your workstation.
-* You have installed the `podman` command line tools on your workstation.
-* You you have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal.
+* You have installed the oc-mirror {openshift-cli} plugin, for more information see https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[Installing the oc-mirror OpenShift CLI plugin].
+* You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal.
 
 .Procedure
-
-. Log in to your {ocp-short} account using the {openshift-cli}, by running the following command:
+. Log in to your {ocp-short} account using the {openshift-cli} by running the following command:
 +
-[source,terminal]
+[source,terminal,subs="attributes+"]
 ----
 oc login -u <user> -p <password> https://api.<hostname>:6443
 ----
 
-. Log in to the {ocp-short} image registry using the `podman` command line tool, by running the following command:
+. From your disconnected cluster, log in to the image registry that you want to mirror, for example, the {ocp-short} image registry.
+. Create an `ImageSetConfiguration.yaml` file.
+. In your `ImageSetConfiguration.yaml` file, specify the resources that you want to mirror. For example:
 +
-[source,terminal]
+[source,terminal,subs="+quotes"]
 ----
-podman login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.<hostname>
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+mirror:
+  helm:
+    repositories:
+      - name: _<repository_name>_ (1)
+        url: _<repository_url>_ (2)
+        charts:
+          - name: _<chart_name>_ (3)
+            version: "_<rhdh_version>_" (4)
 ----
-+
-[NOTE]
-====
-You can run the following commands to get the full host name of the {ocp-short} image registry, and then use the host name in a command to log in:
+<1> The name of the repository containing the Helm chart that you want to mirror, for example, `openshift-charts`.
+<2> The URL for the repository containing the Helm chart that you want to mirror, for example, `https://charts.openshift.io`.
+<3> The name of the Helm chart containing the images that you want to mirror, for example, `redhat-developer-hub`.
+<4> The {product} version that you want to use, for example, `{product-version}`
 
-[source,terminal]
+. Mirror the resources specified in the image set configuration file directly to the target registry by running the `oc-mirror` command. For example:
++
+[source,terminal,subs="+quotes"]
 ----
-REGISTRY_HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')
+oc-mirror --config=_<mirror_config_directory>_/ImageSetConfiguration.yaml _<target-mirror-registry>_
 ----
++
+--
+where:
 
-[source,terminal]
+`<mirror_config_directory>` :: Specifies the location of your image set configuration file on your system, for example, `.user`.
+
+`<target_mirror_registry>` :: Specifies the location and name of your target mirror registry, for example,`docker://registry.example:5000`.
+--
++
+[NOTE]
+====
+Running the `oc-mirror` command creates a local workspace containing the Helm chart and a `ImageContentSourcePolicy` (ICSP) manifest. The ICSP manifest contains an automatically-generated `imageContentSourcePolicy.yaml` file that you must apply against the cluster in a later step.
+====
++
+.Example output
+[source,terminal,subs="+quotes"]
 ----
-podman login -u kubeadmin -p $(oc whoami -t) $REGISTRY_HOST
+Writing image mapping to oc-mirror-workspace/results-1738070846/mapping.txt
+Writing ICSP manifests to oc-mirror-workspace/results-1738070846
 ----
-====
-
-. Log in to the `registry.redhat.io` in `podman` by running the following command:
 +
-[source,terminal]
+. In your workspace, locate the `imageContentSourcePolicy.yaml` file by running the `ls` command. For example:
++
+[source,terminal,subs="+quotes"]
 ----
-podman login registry.redhat.io
+ls _<workspace_directory>_/_<results_directory>_
 ----
 +
-For more information about registry authentication, see https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication].
+--
+where:
+
+`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`.
 
-. Pull {product-short} and PostgreSQL images from https://catalog.redhat.com/software/containers/search[{company-name} Image registry] to your workstation, by running the following commands:
+`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`.
+--
++
+. To mirror the Helm chart, deploy the `imageContentSourcePolicy.yaml` file in the disconnected cluster by running the `oc apply` command. For example:
 +
-[source,terminal,source,subs="attributes+"]
+[source,terminal,subs="+quotes"]
 ----
-podman pull registry.redhat.io/rhdh/rhdh-hub-rhel9:{product-version}
+oc apply -f _<workspace_directory>_/_<results_directory>_/`ImageContentSourcePolicy.yaml`
 ----
 +
-[source,terminal,source,subs="attributes+"]
+--
+where:
+
+`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`.
+
+`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`.
+--
+. In your air-gapped environment, deploy the Helm chart to the namespace that you want to use by running the `helm install` command with `namespace` and `set` options. For example:
++
+[source,terminal,subs="+quotes"]
 ----
-podman pull registry.redhat.io/rhel9/postgresql-15:latest
+CLUSTER_ROUTER_BASE=$(oc get route console -n openshift-console -o=jsonpath='{.spec.host}' | sed 's/^[^.]*\.//')
+
+helm install _<rhdh_instance>_ _<workspace_directory>_/_<results_directory>_/charts/_<archive_file>_ --namespace _<your_namespace>_ --create-namespace \
+  --set global.clusterRouterBase="$CLUSTER_ROUTER_BASE"
 ----
++
+--
+where:
+
+`<rhdh_instance>` :: Specifies the name of your {product} instance, for example, `my-rhdh`.
+
+`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`.
+
+`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`.
+
+`<archive_file>` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`.
+
+`<your_namespace>` :: Specifies the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`.
+--
+
+== Installing {product} on {ocp-short} in a fully disconnected environment with the Helm chart
+
+If your network has access to the registry through a bastion host, you can use the Helm chart to install {product} by mirroring specified resources to disk and transferring them to your air-gapped environment without any connection to the internet.
+
+.Prerequisites
 
-. Push both images to the internal {ocp-short} image registry by running the following commands:
+* You have set up your workstation.
+** You have access to the registry.redhat.io.
+** You have access to the charts.openshift.io Helm chart repository.
+** You have installed the {openshift-cli} on your workstation.
+** You have installed the oc-mirror {openshift-cli} plugin, for more information see https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[Installing the oc-mirror OpenShift CLI plugin].
+** You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal.
+* You have set up your intermediary host.
+** Your host has access to the disconnected cluster and to the target mirror registry, for example, the {ocp-brand-name} image registry. For more information about exposing the {ocp-short} image registry, see https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/registry/index#securing-exposing-registry[Exposing the registry].
+** You have installed the oc-mirror {openshift-cli} plugin, for more information see https://docs.openshift.com/container-platform/4.17/disconnected/mirroring/installing-mirroring-disconnected.html#installation-oc-mirror-installing-plugin_installing-mirroring-disconnected[Installing the oc-mirror OpenShift CLI plugin].
+** You have installed {ocp-brand-name} {ocp-version-min} or later.
+** You have installed the {openshift-cli} on your workstation.
+
+.Procedure
+. Create an `ImageSetConfiguration` file to specify the resources that you want to mirror. For example:
 +
-[source,terminal,source,subs="attributes+"]
+[source,terminal,subs="+quotes"]
 ----
-podman push --remove-signatures registry.redhat.io/rhdh/rhdh-hub-rhel9:{product-version} default-route-openshift-image-registry.<hostname>/<project_name>/rhdh-hub-rhel9:{product-version}
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+mirror:
+  helm:
+    repositories:
+           - name: _<repository_name>_ (1)
+        url: _<repository_url>_ (2)
+        charts:
+          - name: _<chart_name>_ (3)
+            version: "_<rhdh_version>_" (4)
 ----
+<1> The name of the repository that you want to mirror, for example, `openshift-charts`.
+<2> The URL for the repository that you want to mirror, for example, `https://charts.openshift.io`.
+<3> The name of the Helm chart that you want to mirror, for example, `redhat-developer-hub`.
+<4> The version of {product} that you want to use, for example, `{product-version}`
+
+. Mirror the resources specified in the `ImageSetConfiguration.yaml` file by running the `oc-mirror` command. For example:
 +
-[source,terminal]
+[source,terminal,subs="+quotes"]
 ----
-podman push --remove-signatures registry.redhat.io/rhel9/postgresql-15:latest default-route-openshift-image-registry.<hostname>/<project_name>/postgresql-15:latest
+oc-mirror --config=_<mirror_config_directory>_/ImageSetConfiguration.yaml _<mirror_archive_directory>_/
 ----
 +
-For more information about pushing images directly to the {ocp-short} image registry, see https://access.redhat.com/solutions/6959306[How do I push an Image directly into the OpenShift 4 registry].
+--
+where:
+
+`<mirror_config_directory>` :: Specifies the location of your image set configuration file on your system, for example, `.user`.
+
+`<mirror_configuration_file>` :: Specifies the name of your mirror configuration yaml file, for example, `mirror-config.yaml`
+
+`<mirror_archive_directory>` :: Specifies the location of your directory where the mirror archive will be created, for example,`file://.user`.
+--
 +
-[IMPORTANT]
+[NOTE]
 ====
-If an x509 error occurs, verify that you have link:https://access.redhat.com/solutions/6088891[installed the CA certificate used for {ocp-short} routes on your system].
+Running the `oc-mirror` command generates a local workspace containing the mirror archive file, the Helm chart, and a `ImageContentSourcePolicy` (ICSP) manifest. The ICSP manifest contains an `imageContentSourcePolicy.yaml` file that you must apply against the cluster in a later step.
 ====
-
-. Use the following command to verify that both images are present in the internal {ocp-short} registry:
 +
-[source,terminal,subs="+attributes"]
+.Example output
+[source,terminal,subs="+quotes"]
 ----
-oc get imagestream -n {my-product-namespace}
+Creating archive /path/to/mirror-archive/mirror_seq1_000000.tar
 ----
++
+. Transfer the generated archive file (for example, `mirror_seq1_000000.tar`) to the air-gapped environment.
+. Connect to your air-gapped environment and make sure that you are also connected to the following objects:
++
+* The local target registry
+* The target {ocp-short} cluster
++
+. From your air-gapped environment, mirror the resources from the archive to the target registry by running the `oc-mirror` command. For example:
++
+[source,terminal,subs="+quotes"]
+----
+oc-mirror --from _<mirror-archive-file>_ _<target-registry>_
+----
++
+--
+where:
 
-. Enable local image lookup for both images by running the following commands:
+`<mirror_archive_file>` :: Specifies the name of the file containing the resources that you want to mirror, for example,`mirror_seq1_0000.tar`.
+
+`<target_registry>` :: Specifies the name of the target registry that you want to push the mirrored images to, for example, `docker://registry.localhost:5000`.
+--
 +
-[source,terminal]
+.Example output
+[source,terminal,subs="+quotes"]
 ----
-oc set image-lookup postgresql-15
+Wrote release signatures to oc-mirror-workspace/results-1738075410
+Writing image mapping to oc-mirror-workspace/results-1738075410/mapping.txt
+Writing ICSP manifests to oc-mirror-workspace/results-1738075410
 ----
 +
-[source,terminal]
+. In your workspace, locate the `imageContentSourcePolicy.yaml` file by running the `ls` command. For example:
++
+[source,terminal,subs="+quotes"]
 ----
-oc set image-lookup  rhdh-hub-rhel9
+ls _<workspace_directory>_/_<results_directory>_
 ----
-
-. Go to *YAML view* and update the `image` section for `backstage` and `postgresql` using the following values:
 +
 --
-.Example values for Developer Hub image
-[source,yaml]
+where:
+
+`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`.
+
+`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`.
+--
++
+. To mirror the Helm chart, deploy the `imageContentSourcePolicy.yaml` file in the disconnected cluster by running the `oc apply` command. For example:
++
+[source,terminal,subs="+quotes"]
 ----
-upstream:
-  backstage:
-    image:
-      registry: ""
-      repository: rhdh-hub-rhel9
-      tag: latest
+oc apply -f _<workspace_directory>_/_<results_directory>_/ImageContentSourcePolicy.yaml
 ----
++
+--
+where:
+
+`<workspace-directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`.
 
-.Example values for PostgreSQL image
-[source,yaml]
+`<results-directory>` :: Specifies the name of your results directory, for example, `results-1738070846`.
+--
+. In your air-gapped environment, deploy the Helm chart to the namespace that you want to use by running the `helm install` command with `namespace` and `set` options. For example:
++
+[source,terminal,subs="+quotes"]
 ----
-upstream:
-  postgresql:
-    image:
-      registry: ""
-      repository: postgresql-15
-      tag: latest
+CLUSTER_ROUTER_BASE=$(oc get route console -n openshift-console -o=jsonpath='{.spec.host}' | sed 's/^[^.]*\.//')
+
+helm install _<rhdh_instance>_ _<workspace_directory>_/_<results_directory>_/charts/_<archive_file>_ --namespace _<your_namespace>_ --create-namespace \
+  --set global.clusterRouterBase="$CLUSTER_ROUTER_BASE"
 ----
++
 --
+where:
+
+`<rhdh_instance>` :: Specifies the name of your {product} instance, for example, `my-rhdh`.
 
-. Install the {product} using Helm chart.
+`<workspace_directory>` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`.
+
+`<results_directory>` :: Specifies the name of your results directory, for example, `results-1738070846`.
+
+`<archive_file>` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`.
+
+`<your_namespace>` :: Specifies the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`.
+--