procedures: Installing Che in a restricted environment on OpenShift

antora.yml

@@ -21,6 +21,8 @@ asciidoc:
     # for the project
     broker-ver: "v3.4.0"
     che-plugin-registry-directory: che-plugin-registry
+    devworkspace-operator-index: registry.redhat.io/redhat/redhat-operator-index:v4.10
+    devworkspace-operator-version-patch: "0.14.1"
     devworkspace: DevWorkspace
     hosted-che-docs: xref:hosted-che:hosted-che.adoc[]
     identity-provider-docs-url: https://www.keycloak.org/docs/
@@ -44,15 +46,15 @@ asciidoc:
     image-puller-repository-name: kubernetes-image-puller
     kube-ver-min: "1.21"
     kubernetes: Kubernetes
-    link-oauth2-proxy: link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2 Proxy]
-    link-kube-rbac-proxy: link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy]
-    link-understanding-custom-resources: "link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Kubernetes - Understanding Custom Resources]"
     link-installing-orch-cli: "link:https://kubernetes.io/docs/tasks/tools/#kubectl[Kubernetes - Install Tools: kubectl]"
+    link-kube-rbac-proxy: link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy]
     link-manage-compute-resources-container: "link:https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/[{kubernetes} - Resource management for pods and containers]"
+    link-oauth2-proxy: link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2 Proxy]
     link-prod-cli-documentation: "link:https://github.com/che-incubator/chectl/[`chectl` reference documentation]"
+    link-understanding-custom-resources: "link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Kubernetes - Understanding Custom Resources]"
     namespace: namespace # In context: API namespace
     ocp: OpenShift Container Platform
-    ocp4-ver: "4.6"
+    ocp4-ver: "4.10"
     orch-cli-link: link:https://kubernetes.io/docs/reference/kubectl/overview/[Overview of kubectl]
     orch-cli: kubectl
     orch-ingress: Kubernetes Ingress
@@ -65,38 +67,40 @@ asciidoc:
     platforms-name: Kubernetes or OpenShift
     platforms-namespace: Kubernetes namespace or OpenShift project
     postgresql-image-url: quay.io/eclipse/che--centos--postgresql-96-centos13
+    pre-migration-prod-checluster: eclipse-che
+    pre-migration-prod-deployment: che
+    pre-migration-prod-id-short: che
+    pre-migration-prod-operator: che-operator
+    pre-migration-prod-subscription: eclipse-che
     prod-checluster: eclipse-che
     prod-cli: chectl
     prod-deployment: che
-    prod-docs-url: https://www.eclipse.org/che/docs
     prod-docs-url-backup-recovery: link:https://www.eclipse.org/che/docs/che-7/administration-guide/backup-and-recovery/[Backup and recovery]
     prod-docs-url-enable-oauth: link:https://www.eclipse.org/che/docs/che-7/administration-guide/configuring-openshift-oauth/[Configuring OpenShift OAuth]
+    prod-docs-url: https://www.eclipse.org/che/docs
     prod-home: /home/user
     prod-host: che-host
     prod-id-short: che
     prod-id: eclipse-che
     prod-last-version-pre-dwo: v7.41
     prod-namespace: eclipse-che
     prod-operator-image-name: che-operator
+    prod-operator-index: registry.access.redhat.com/redhat/community-operator-index:v4.10
+    prod-operator-package-name: eclipse-che
     prod-operator: che-operator
     prod-prev-ver: "previous minor version"
     prod-short: Che
-    prod-stable-channel: stable
     prod-stable-channel-catalog-source: community-operators
     prod-stable-channel-package: eclipse-che
+    prod-stable-channel: stable
     prod-upstream: Eclipse{nbsp}Che
     prod-url: "https://__<che_fqdn>__"
     prod-ver-major: "7"
-    prod-ver-patch: main
-    prod-ver: main
+    prod-ver-patch: "7.47.0"
+    prod-ver: "7.47"
     prod-workspace: che-ws
     prod: Eclipse Che
     prod2: Eclipse Che
     project-context: che
     repo-path: ""
     theia-endpoint-image: eclipse/che-theia-endpoint-runtime:next
-    pre-migration-prod-id-short: che
-    pre-migration-prod-deployment: che
-    pre-migration-prod-operator: che-operator
-    pre-migration-prod-checluster: eclipse-che
-    pre-migration-prod-subscription: eclipse-che

modules/administration-guide/attachments/restricted-environment/prepare-restricted-environment.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+#
+# Copyright (c) 2022 Red Hat, Inc.
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+#
+
+# Fail on error
+set -e
+
+# Handle command line parameters
+while [ $# -gt 0 ]; do
+  if [[ $1 == *"--"* ]]; then
+    param="${1/--/}"
+    declare "$param"="$2"
+  fi
+  shift
+done
+
+# Display commands
+set -x
+
+# OpenShift cluster version
+declare ocp_ver="${ocp_ver:?Define the variable}"
+
+# Operators
+declare devworkspace_operator_index="${devworkspace_operator_index:?Define the variable}"
+declare devworkspace_operator_package_name="devworkspace-operator"
+declare devworkspace_operator_version="${devworkspace_operator_version:?Define the variable}"
+declare prod_operator_index="${prod_operator_index:?Define the variable}"
+declare prod_operator_package_name="${prod_operator_package_name:?Define the variable}"
+declare prod_operator_version="${prod_operator_version:?Define the variable}"
+
+# Destination registry
+declare my_registry="${my_registry:-default-route-openshift-image-registry.apps-crc.testing}"
+declare my_catalog="${my_catalog:-restricted-environment-install}"
+declare my_operator_index="$my_registry/$my_catalog/my-operator-index:v${ocp_ver}"
+
+# Create local directories
+mkdir -p "${my_catalog}/${devworkspace_operator_package_name}" "${my_catalog}/${prod_operator_package_name}"
+
+# Get metadata for the operator catalog channels and packages.
+# Filter only the operator channel and the required version bundle
+# to limit the number of related images to mirror.
+opm render "${devworkspace_operator_index}" \
+  | jq "select(\
+    .name == \"${devworkspace_operator_package_name}\" \
+    or (.package == \"${devworkspace_operator_package_name}\" and .schema == \"olm.channel\" ) \
+    or .name == \"${devworkspace_operator_package_name}.${devworkspace_operator_version}\" \
+    )" \
+  > "${my_catalog}/${devworkspace_operator_package_name}/render.json"
+
+opm render "${prod_operator_index}" \
+  | jq "select(\
+    .name == \"${prod_operator_package_name}\" \
+    or (.package == \"${prod_operator_package_name}\" and .schema == \"olm.channel\" ) \
+    or .name == \"${prod_operator_package_name}.${prod_operator_version}\" \
+    )" \
+  > "${my_catalog}/${prod_operator_package_name}/render.json"
+
+# Create the catalog dockerfile
+if [ -f "${my_catalog}.Dockerfile" ]; then
+  rm -f "${my_catalog}.Dockerfile"
+fi
+opm alpha generate dockerfile "./${my_catalog}"
+
+# Build the catalog image locally
+podman build -t "${my_operator_index}" -f "./${my_catalog}.Dockerfile" --no-cache .
+
+# Disable default OperatorHub catalog
+oc patch OperatorHub cluster --type json \
+    --patch '[{"op": "add", "path": "/spec/disableAllDefaultSources", "value": true}]'
+
+# Deploy my catalog image
+oc delete project "$my_catalog" --grace-period=1 --ignore-not-found=true
+oc wait --for=delete "project/$my_catalog"
+sleep 5
+oc new-project "$my_catalog"
+skopeo copy --dest-tls-verify=false --all "containers-storage:$my_operator_index" "docker://$my_operator_index"
+
+# Deploy my catalog source
+oc apply -f - << EOF
+apiVersion: operators.coreos.com/v1alpha1
+kind: CatalogSource
+metadata:
+  name: $my_catalog
+  namespace: openshift-marketplace
+spec:
+  sourceType: grpc
+  image: $my_operator_index
+EOF
+
+# Create CheCluster custom resource configuration file
+cat > che-operator-cr-patch.yaml << EOF
+kind: CheCluster
+apiVersion: org.eclipse.che/v1
+spec:
+  server:
+    airGapContainerRegistryHostname: "$my_registry"
+    airGapContainerRegistryOrganization: "${my_catalog}"
+EOF
+
+# Mirror related images
+oc adm catalog mirror "$my_operator_index" "$my_registry" --insecure
+
+echo "INFO: Catalog $my_operator_index deployed to the $my_registry registry."

modules/administration-guide/nav.adoc

@@ -22,8 +22,6 @@
 *** xref:installing-che-on-codeready-containers.adoc[]
 *** xref:installing-che-on-minikube.adoc[]
 ** xref:installing-che-in-a-restricted-environment.adoc[]
-*** xref:preparing-a-restricted-environment.adoc[]
-*** xref:configuring-che-to-run-in-a-restricted-environment.adoc[]
 * xref:configuring-che.adoc[]
 ** xref:understanding-the-checluster-custom-resource.adoc[]
 *** xref:using-the-openshift-web-console-to-configure-the-checluster-custom-resource-during-installation.adoc[]

modules/administration-guide/pages/installing-che-in-a-restricted-environment.adoc

@@ -1,26 +1,35 @@
 :_content-type: PROCEDURE
-:navtitle: Installing {prod-short} in restricted environment
+:navtitle: Installing {prod-short} in a restricted environment
 :keywords: administration guide, installing-che-in-a-restricted-environment, installing-che-in-restricted-environment
-:page-aliases: installation-guide:installing-che-in-restricted-environment, installation-guide:installing-che-in-a-restricted-environment
+:page-aliases: installation-guide:installing-che-in-restricted-environment, installation-guide:installing-che-in-a-restricted-environment, preparing-a-restricted-environment, configuring-che-to-run-in-a-restricted-environment
 
-:parent-context-of-installing-che-in-a-restricted-environment: {context}
 
-[id="installing-{prod-id-short}-in-a-restricted-environment_{context}"]
-= Installing {prod-short} in a restricted environment
 
-:context: installing-{prod-id-short}-in-a-restricted-environment
+[id="installing-{prod-id-short}-in-a-restricted-environment-on-openshift_{context}"]
+= Installing {prod-short} in a restricted environment on OpenShift
 
-By default, {prod-short} workspaces reference various external resources, including container images available in public registries or sample projects hosted on public resources. This section describes how to deploy {prod-short} in a restricted environment where these external resources are not available. This method is also called _offline mode_ or _air-gap scenario_.
+On an OpenShift cluster operating in a restricted network, public resources are not available.
 
-.Prerequisites
+However, deploying {prod-short} and running workspaces requires the following public resources:
+
+* Operator catalog
+* Container images
+* Sample projects
+
+To make these resources available, you can replace them with their copy in a registry accessible by the OpenShift cluster.
 
-* You are logged in to the cluster using the developer account.
 
-* Dynamic provisioning or pre-defined PVs configured before the deployment.
+.Prerequisites
+
+include::partial$snip_preparing-images-for-a-restricted-environment.adoc[]
 
-* Block-based storage volume or NFS share available outside of the cluster to serve dynamic storage provisioning or PVs. Block-based storage is recommended for optimal performance. 
+. Install {prod-short} with the configuration set in the `che-operator-cr-patch.yaml` during the previous step:
++
+[subs="+attributes,+quotes"]
+----
+$ {prod-cli} server:deploy --platform=openshift \
+  --che-operator-cr-patch-yaml=che-operator-cr-patch.yaml
+----
 
-* xref:preparing-a-restricted-environment.adoc[]
-* xref:configuring-che-to-run-in-a-restricted-environment.adoc[]
+include::partial$snip_installing-che-in-a-restricted-environment-additional-resources.adoc[]
 
-:context: {parent-context-of-installing-che-in-a-restricted-environment}

modules/administration-guide/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc

@@ -3,26 +3,18 @@
 :keywords: Upgrading {prod-short} in restricted environment
 :page-aliases: installation-guide:upgrading-che-using-the-cli-management-tool-in-restricted-environment, installation-guide:upgrading-che-in-restricted-environment
 
-:parent-context-of-upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment: {context}
-
 [id="upgrading-{prod-id-short}-using-the-cli-management-tool-in-restricted-environment_{context}"]
 = Upgrading {prod-short} using the CLI management tool in restricted environment
 
-:context: upgrading-prod-short-using-the-cli-management-tool-in-restricted-environment
 
 This section describes how to upgrade {prod} using the CLI management tool in restricted environment. The upgrade path supports minor version update, from {prod-short} {prod-prev-ver} to version {prod-ver}.
 
 .Prerequisites
 
-* An administrative account on an instance of {platforms-name}.
-
-* An instance running {prod-short} {prod-prev-ver}, installed using the CLI management tool on the same instance of {platforms-name}, with the {prod-cli} `--installer operator` method, in the `_<{prod-namespace}>_` project. See xref:installing-che-in-a-restricted-environment.adoc[].
-
-* The `{prod-cli}` {prod-ver} management tool is available. See xref:using-the-chectl-management-tool.adoc[].
 
-* Essential container images are available to the {prod-short} server running in the cluster. See xref:preparing-a-restricted-environment.adoc[].
+* An instance running {prod-short} {prod-prev-ver}, installed on the same instance of OpenShift, with the `{prod-cli} --installer operator` method, in the `_<{prod-namespace}>_` project. See xref:installing-che-in-a-restricted-environment.adoc[].
 
-.Procedure
+include::partial$snip_preparing-images-for-a-restricted-environment.adoc[]
 
 . In all running workspaces in the {prod-short} {prod-prev-ver} instance, save and push changes back to the Git repositories.
 
@@ -32,20 +24,13 @@ This section describes how to upgrade {prod} using the CLI management tool in re
 +
 [subs="+attributes,+quotes"]
 ----
-$ {prod-cli} server:update --che-operator-image=__<image-registry>__/__<organization>__/{prod-operator-image-name}:{prod-ver} -n {prod-namespace}
+$ {prod-cli} server:update --che-operator-image="$TAG" -n {prod-namespace} --k8spodwaittimeout=1800000
 ----
-+
-* _<image-registry>_: A hostname and a port of the container-image registry accessible in the restricted environment.
-* _<organization>_: An organization of the container-image registry. See: See xref:preparing-a-restricted-environment.adoc[].
 
 .Verification steps
 
 . Navigate to the {prod-short} instance.
 
 . The {prod-ver} version number is visible at the bottom of the page.
 
-[NOTE]
-====
-For slow systems or internet connections, add the `--k8spodwaittimeout=1800000` flag option to the `{prod-cli} server:update` command to extend the Pod timeout period to 1800000 ms or longer. 
-====
-
+include::partial$snip_installing-che-in-a-restricted-environment-additional-resources.adoc[]