Installing Che in a restricted environment

By default, Che 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 Che in a restricted environment where these external resources are not available. This method is also called offline mode or air-gap scenario.

Prerequisites
  • You are logged in to the cluster using the developer account.

  • Dynamic provisioning or pre-defined PVs configured before the deployment.

  • 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.

Understanding network connectivity in restricted environments

Che requires that each Kubernetes Ingress or OpenShift Route created for Che is accessible from inside the Kubernetes or OpenShift cluster. These Che components have a Kubernetes Ingress or OpenShift Route: che-server, keycloak, devfile-registry, plugin-registry.

Consider the network topology of the environment to determine how best to accomplish this.

Example 1. Network owned by a company or an organization, disconnected from the public Internet

The network administrators must ensure that it is possible to route traffic bound from the cluster to Kubernetes Ingress or OpenShift Route host names.

Example 2. Private subnetwork in a cloud provider

Create a proxy configuration allowing the traffic to leave the node to reach an external-facing Load Balancer.

Understanding the Che registries

Che uses two registries: the plug-ins registry and the devfile registry. They are static websites publishing the metadata of Che plug-ins and devfiles. When built in offline mode they also include artifacts.

The devfile and plug-in registries run in two separate Pods. Their deployment is part of the Che installation.

The devfile and plug-in registries
The devfile registry

The devfile registry holds the definitions of the Che stacks. Stacks are available on the Che user dashboard when selecting Create Workspace. It contains the list of Che technological stack samples with example projects. When built in offline mode it also contains all sample projects referenced in devfiles as zip files.

The plug-in registry

The plug-in registry makes it possible to share a plug-in definition across all the users of the same instance of Che. When built in offline mode it also contains all plug-in or extension artifacts.

Building offline registry images

Building an offline devfile registry image

This section describes how to build an offline devfile registry image. Starting workspaces without relying on resources from the outside Internet requires building this image. The image contains all sample projects referenced in devfiles as zip files.

Prerequisites:
Procedure
  1. Clone the devfile registry repository and check out the version to deploy:

    $ git clone git@github.com:eclipse/che-devfile-registry.git
    $ cd che-devfile-registry
    $ git checkout 7.30.x
  2. Build an offline devfile registry image:

    $ ./build.sh --organization <my-org> \
               --registry <my-registry> \
               --tag <my-tag> \
               --offline

    To display full options for the build.sh script, use the --help parameter.

Additional resources

Building an offline plug-in registry image

This section describes how to build an offline plug-in registry image. Starting workspaces without relying on resources from the outside Internet requires building this image. The image contains plug-in metadata and all plug-in or extension artifacts.

Prerequisites
  • NodeJS 12.x

  • A running version of yarn. See Installing Yarn.

  • ./node_modules/.bin is in the PATH environment variable.

  • A running installation of podman or docker.

Procedure
  1. Clone the plug-in registry repository and check out the version to deploy:

    $ git clone git@github.com:eclipse/che-plugin-registry.git
    $ cd che-plugin-registry
    $ git checkout 7.30.x
  2. Build offline plug-in registry image:

    $ ./build.sh --organization <my-org> \
               --registry <my-registry> \
               --tag <my-tag> \
               --offline

    To display full options for the build.sh script, use the --help parameter.

Additional resources

Preparing a private registry

Che workspaces consist of Pods running in 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

Running any workspace requires these essential images:

Table 1. Images essential to starting workspaces

quay.io/eclipse/che-server

The main Che server image

quay.io/eclipse/che-postgres

The database used by Che

quay.io/eclipse/che-keycloak

Keycloak Pod for user authentication

quay.io/eclipse/che-jwtproxy

JWT proxy image for enabling authentication between services. See Che workspace JWT proxy.

quay.io/eclipse/che-plugin-artifacts-broker
quay.io/eclipse/che-plugin-metadata-broker

Images for adding plug-ins to workspaces. See Che plug-ins broker.

quay.io/eclipse/che-plugin-registry

Plug-in registry that store information about plugins and the runtime containers they require. See Building an offline plug-in registry image.

quay.io/eclipse/che-devfile-registry

Devfile registry that stores descriptions of the sample projects and how to load them as workspaces through the Getting Started tab in the dashboard. See Building an offline devfile registry image.

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 in this section is needed, remove unnecessary plug-ins and devfiles when building custom registries (see Customizing the 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 Building an offline plug-in registry image) 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:

$ 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 projects that are being built. To use the samples, Che pull these images from the references to them in the devfile registry. This is needed because the sample devfiles included in the devfile registry apply to images suited for this purpose.

An offline devfile registry (see Building an offline devfile registry image) contains a file with the list of all images referenced in its devfiles:

$ 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 a restricted environment

This section describes how to configure Che and related containers to use images in a restricted environment rather than the default images in an online registry.

Prerequisites
  • All required images available in an image registry that is accessible from the cluster where Che is to be deployed.

Procedure

This procedure uses the following placeholders:

Table 2. Placeholders used in examples

<my-internal-registry>

a host name of the container-image registry, accessible in the restricted environment, see Preparing a private registry

<my-organization>

organization of the container-image registry

<my-offline-plug-in-registry>

offline plug-in registry, see Building an offline plug-in registry image

<my-offline-devfile-registry>

offline devfile registry, see Building an offline devfile registry image

<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:

# [...]
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:

<my-internal-registry>/<my-organization>/<my-offline-plug-in-registry>:<ver>
<my-internal-registry>/<my-organization>/<my-offline-devfile-registry>:<ver>