Installing Che in restricted environment | Eclipse Che Documentation

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.

Notes on network connectivity in restricted environments

Restricted network environments range from a private subnet 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.

Take into account 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 hostnames. 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 registry

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

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

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:

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

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:

Table 1. Images essential to starting workspaces
`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 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 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 Building offline versions of the plug-in and devfile registry 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 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 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 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 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 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:

Table 2. Placeholders used in examples
`<my-internal-registry>`	hostname 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 registry)
`<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>/che-plug-in-registry:<ver>
<my-internal-registry>/<my-organization>/che-devfile-registry:<ver>

Tags: