Installing Che in a restricted environment

The following sections describe how to deploy Che in a Kubernetes or OpenShift cluster in a restricted environment (also called offline mode or air-gap scenario).

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.

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.

Network connectivity in restricted environments

Restricted network environments range from a private subnetwork in a cloud provider to a separate network owned by a company, disconnected from the public Internet. Regardless of the network configuration, Che works provided that the Ingress and Routes that are created for Che components (che-server, keycloak, devfile-registry, plugin-registry) are accessible from inside the Kubernetes or OpenShift cluster.

Consider the network topology of the environment to determine how best to accomplish this. For example, on a network owned by a company or an organization, the network administrators must ensure that traffic bound from the cluster can be routed to Ingress and Route host names. In other cases, for example, on AWS, create a proxy configuration allowing the traffic to leave the node to reach an external-facing Load Balancer.

Building offline versions of the plug-in and devfile registries

This section describes how to build offline registry images. For additional information, see 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.

Building offline devfile registry

  1. Clone the devfile registry repository:

    $ git clone https://github.com/eclipse/che-devfile-registry.git
    $ cd che-devfile-registry
  2. Check out version of the registry to be deployed:

    $ git checkout 7.3.0
  3. Build the devfile registry image:

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

Building offline plug-in registry

  1. Clone the plug-in registry repository:

    $ git clone https://github.com/eclipse/che-plugin-registry.git
    $ cd che-plugin-registry
  2. Check out version of the registry to be deployed:

    $ git checkout 7.3.0
  3. Build the plug-in registry image:

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

Pulling images used by Che to 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

The images essential for starting a workspace are infrastructure images that are included in every workspace launch:

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
quay.io/eclipse/che-devfile-registry

Plug-in and devfile registries that store metadata for workspaces. See Building offline versions of the plug-in and devfile registries for information about 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 in this section is needed, remove unnecessary plug-ins and devfiles when building custom registries (see Customizing the 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 Building offline plug-in registry) 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, pull these images from the offline 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 offline devfile registry) 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 (which is accessible in the restricted environment, see Pulling images used by Che to a private registry)

<my-organization>

organization of the container-image registry

<my-offline-devfile-registry>
<my-offline-plug-in-registry>

offline plug-in and devfile registries (see Building offline versions of the plug-in and devfile registries)

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