Merge pull request #868 from amisevsk/airgap-docs

Add docs for airgap/offline deployment of Che

src/main/_data/sidebars/che_7_docs.yml

@@ -162,6 +162,9 @@ entries:
   - title: Advanced configuration options
     url: che-7/advanced-configuration-options
     output: web
+  - title: Installing Che in restricted environment
+    url: che-7/installing-che-in-restricted-environment
+    output: web
   #- title: Troubleshooting Che installation
     #url: che-7/troubleshooting-che-installation
     #output: web

src/main/pages/che-7/installation-guide/assembly_installing-che-in-restricted-environment.adoc

@@ -0,0 +1,223 @@
+---
+title: Installing Che in restricted environment
+keywords: air-gap, airgap, offline
+tags: installation
+sidebar: che_7_docs
+permalink: che-7/installing-che-in-restricted-environment/
+folder: che-7/installation-guide
+summary:
+---
+
+:parent-context-of-installing-che-in-restricted-environment: {context}
+
+[id='installing-che-in-restricted-environment_{context}']
+= Installing Che in offline mode
+
+:context: installing-che-in-restricted-environment
+
+The following sections describe the steps necessary to deploy Che in a Kubernetes or OpenShift cluster in a restricted environment (also called _offline mode_ or _air-gap scenario_).
+
+
+== Introduction
+
+By default, Eclipse Che workspaces reference various external resources, including container images available in public registries or sample projects hosted on GitHub.
+
+To deploy Che in an environment where these external resources are not available (for example, on a cluster that is not exposed to the public Internet):
+
+* Build images containing external resources (workspace plug-ins, projects).
+* Pull all images needed for running Che to a registry that is accessible.
+* Configure Che to use these images.
+
+
+[id="building-offline-versions-of-the-plug-in-and-devfile-registry_{context}"]
+== Building offline versions of the plug-in and devfile registry
+
+This section describes how to build _offline_ registry images. For additional information, see link:{site-baseurl}che-7/building-and-running-a-custom-registry-image/[Building and running a custom registry image].
+
+The main purpose of building offline registry images is to ensure that workspaces can be started without relying on resources from the outside internet. For the plug-in registry, this means building a registry that serves all plug-in or extension artifacts in addition to plug-in metadata. Similarly, an offline devfile registry serves all sample projects referenced in devfiles as `zip` files.
+
+Plug-in registry repositories contain scripts to make it easier to build custom images.
+
+
+[id="building-offline-plug-in-registry_{context}"]
+=== Building offline plug-in registry
+
+. Clone the plug-in registry repository:
++
+----
+$ git clone https://github.com/eclipse/che-plugin-registry.git
+$ cd che-plugin-registry
+----
+
+. Check out version of the registry to be deployed:
++
+----
+$ git checkout 7.3.0
+----
+
+. Build the plug-in registry image:
++
+[subs="+quotes"]
+----
+./build.sh --organization _<my-org>_ \
+           --registry _<my-registry>_ \
+           --tag _<my-tag>_ \
+           --offline
+----
++
+Use the `--help` parameter to display full options for the `build.sh` script.
+
+This build of the registry builds a container image that contains all `.vsix` and `.theia` extensions that can be used in workspaces. This results in a large image. To build a version of the registry that contains only the _latest_ version of each plug-in, use the `--latest-only` argument.
+
+
+[id="building-offline-devfile-registry_{context}"]
+=== Building offline devfile registry
+
+. Clone the devfile registry repository:
++
+----
+$ git clone https://github.com/eclipse/che-devfile-registry.git
+$ cd che-devfile-registry
+----
+
+. Check out version of the registry to be deployed:
++
+----
+$ git checkout 7.3.0
+----
+
+. Build the devfile registry image:
++
+[subs="+quotes"]
+----
+./build.sh --organization _<my-org>_ \
+           --registry _<my-registry>_ \
+           --tag _<my-tag>_ \
+           --offline
+----
++
+Use the `--help` parameter to display full options for the `build.sh` script.
+
+
+[id="pulling-images-used-by-che-to-a-private-registry_{context}"]
+== Pulling images used by Che to a private registry
+
+Che workspaces consist of pods running on a cluster, and therefore, many images are required to support all languages and plug-ins that can be used for a workspace. In an offline deployment, these images must be made available to the Che server running in the cluster.
+
+
+=== Essential images
+
+The images _essential_ to starting a workspace are infrastructure images that are included in every workspace launch:
+
+.Images essential to starting workspaces
+[cols="2*"]
+|===
+| `docker.io/eclipse/che-server`
+| The main Che server image
+
+| `docker.io/eclipse/che-postgres`
+| The database used by Che
+
+| `docker.io/eclipse/che-keycloak`
+| Keycloak pod for user authentication
+
+| `quay.io/eclipse/che-jwtproxy`
+| JWT proxy image for enabling authentication between services. See link:{site-baseurl}che-7/che-workspaces-architecture/#che-workspace-jwt-proxy_che-workspace-components[Che workspace JWT proxy].
+
+| `docker.io/eclipse/che-unified-plugin-broker` +
+  `docker.io/eclipse/che-init-plugin-broker`
+| Images for adding plug-ins to workspaces. See link:{site-baseurl}che-7/che-workspaces-architecture/#che-plug-in-broker_che-workspace-components[Che plug-in broker].
+
+| `quay.io/eclipse/che-plugin-registry` +
+  `quay.io/eclipse/che-devfile-registry`
+| Plug-in and devfile registries that store metadata for workspaces. See xref:building-offline-versions-of-the-plug-in-and-devfile-registry_{context}[] for information on building appropriate images.
+|===
+
+
+=== Workspace-specific images
+
+The images described in this section are required for running a workspace. Any one workspace uses a subset of the images below. It is only necessary to include the images that are used in workspaces created. For example, when using Che only for developing in Java, many images can be omitted.
+
+To avoid issues when only a subset of the images described below is needed, remove unnecessary plug-ins and devfiles when building custom registries (see link:{site-baseurl}che-7/customizing-the-devfile-and-plug-in-registries/[Customizing devfile and plug-in registries] for more information).
+
+
+==== Plug-in sidecar images
+
+Many workspace plug-ins are run in sidecar containers to ensure their dependencies are available. The offline plug-in registry (see xref:building-offline-plug-in-registry_{context}[]) includes a file with the list of all images referenced in its plug-ins.
+
+To get a list of images required for plug-ins, display this file:
+
+[subs="+quotes"]
+----
+$ docker run -it --rm \
+  --entrypoint cat _<my-offline-registry>_ /var/www/html/v3/external_images.txt
+----
+
+In the example above, substitute `<my-offline-registry>` for the image name and tag of the custom plug-in registry.
+
+
+==== Devfile base images
+
+Every Che workspace uses one or more _base_ images, which contain the development dependencies for the projects being built. Because the sample devfiles included in the devfile registry refer to images suited for this purpose, it is necessary to pull these images to be able to use the samples.
+
+An offline devfile registry (see xref:building-offline-devfile-registry_{context}[]) contains a file with the list of all images referenced in its devfiles:
+
+[subs="+quotes"]
+----
+$ docker run -it --rm \
+  --entrypoint cat _<my-offline-registry>_ /var/www/html/devfiles/external_images.txt
+----
+
+In the example above, substitute `<my-offline-registry>` for the image name and tag of the custom devfile registry.
+
+
+== Configuring Che to run in restricted environment
+
+This section describes how to configure Che and related containers to refer to images in a restricted environment instead of the default images in an online registry.
+
+.Prerequisites
+
+* All required images available in an image registry that is visible to the cluster where Che is to be deployed.
+
+.Procedure
+
+This procedure uses the following placeholders:
+
+.Placeholders used in examples
+[cols="1,2"]
+|===
+| `<my-internal-registry>`
+| hostname of the container-image registry (which is accessible in the restricted environment, see xref:pulling-images-used-by-che-to-a-private-registry_{context}[])
+
+| `<my-organization>`
+| organization of the container-image registry
+
+| `<my-offline-devfile-registry>` +
+  `<my-offline-plug-in-registry>`
+| offline plug-in and devfile registries (see xref:building-offline-versions-of-the-plug-in-and-devfile-registry_{context}[])
+
+| `<ver>`
+| release of Che that is being deployed
+|===
+
+The `CheCluster` Custom Resource, which is managed by the Che Operator, includes fields to facilitate deploying an instance of Che in a restricted environment:
+
+[source,yaml,subs="+quotes"]
+----
+# [...]
+spec:
+  server:
+    airGapContainerRegistryHostname: '__<my-internal-registry>__'
+    airGapContainerRegistryOrganization: '__<my-organization>__'
+# [...]
+----
+
+Setting these values uses `<my-internal-registry>` and `<my-organization>` for all images. This means that the operator expects the offline plug-in and devfile registries to be available at:
+
+[subs="+quotes"]
+----
+__<my-internal-registry>__/__<my-organization>__/che-plug-in-registry:__<ver>__
+__<my-internal-registry>__/__<my-organization>__/che-devfile-registry:__<ver>__
+----
+
+:context: {parent-context-of-installing-che-in-restricted-environment}