diff --git a/modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc b/modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc index b0b4f18d8e..200dcad6f9 100644 --- a/modules/installation/proc-install-rhdh-airgapped-environment-ocp-helm.adoc +++ b/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 -p https://api.: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. +apiVersion: mirror.openshift.io/v1alpha2 +kind: ImageSetConfiguration +mirror: + helm: + repositories: + - name: __ (1) + url: __ (2) + charts: + - name: __ (3) + 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=__/ImageSetConfiguration.yaml __ ---- ++ +-- +where: -[source,terminal] +`` :: Specifies the location of your image set configuration file on your system, for example, `.user`. + +`` :: 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 __/__ ---- + -For more information about registry authentication, see https://access.redhat.com/RegistryAuthentication[{company-name} Container Registry Authentication]. +-- +where: + +`` :: 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: +`` :: 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 __/__/`ImageContentSourcePolicy.yaml` ---- + -[source,terminal,source,subs="attributes+"] +-- +where: + +`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`` :: 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 __ __/__/charts/__ --namespace __ --create-namespace \ + --set global.clusterRouterBase="$CLUSTER_ROUTER_BASE" ---- ++ +-- +where: + +`` :: Specifies the name of your {product} instance, for example, `my-rhdh`. + +`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`` :: Specifies the name of your results directory, for example, `results-1738070846`. + +`` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`. + +`` :: 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.//rhdh-hub-rhel9:{product-version} +apiVersion: mirror.openshift.io/v1alpha2 +kind: ImageSetConfiguration +mirror: + helm: + repositories: + - name: __ (1) + url: __ (2) + charts: + - name: __ (3) + 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.//postgresql-15:latest +oc-mirror --config=__/ImageSetConfiguration.yaml __/ ---- + -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: + +`` :: Specifies the location of your image set configuration file on your system, for example, `.user`. + +`` :: Specifies the name of your mirror configuration yaml file, for example, `mirror-config.yaml` + +`` :: 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 __ __ +---- ++ +-- +where: -. Enable local image lookup for both images by running the following commands: +`` :: Specifies the name of the file containing the resources that you want to mirror, for example,`mirror_seq1_0000.tar`. + +`` :: 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 __/__ ---- - -. 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: + +`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`` :: 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 __/__/ImageContentSourcePolicy.yaml ---- ++ +-- +where: + +`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. -.Example values for PostgreSQL image -[source,yaml] +`` :: 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 __ __/__/charts/__ --namespace __ --create-namespace \ + --set global.clusterRouterBase="$CLUSTER_ROUTER_BASE" ---- ++ -- +where: + +`` :: Specifies the name of your {product} instance, for example, `my-rhdh`. -. Install the {product} using Helm chart. +`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. + +`` :: Specifies the name of your results directory, for example, `results-1738070846`. + +`` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`. + +`` :: Specifies the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`. +--