Chapter 3. Installing CodeReady Workspaces in a restricted enviroment

By default, Red Hat CodeReady Workspaces uses various external resources, mainly container images available in public registries.

To deploy CodeReady Workspaces in an environment where these external resources are not available (for example, on a cluster that is not exposed to the public Internet):

  1. Identify the image registry used by the OpenShift cluster, and ensure you can push to it.
  2. Push all the images needed for running CodeReady Workspaces to this registry.
  3. Configure CodeReady Workspaces to use the images that have been pushed to the registry.
  4. Proceed to the CodeReady Workspaces installation.

The procedure for installing CodeReady Workspaces in restricted environments is different based on the installation method you use:

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, CodeReady Workspaces works provided that the Routes that are created for CodeReady Workspaces components (codeready-workspaces-server, identity provider, devfile and plugin registries) are accessible from inside the 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 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.

When the restricted network involves a proxy, follow the instructions provided in Section 3.3, “Preparing CodeReady Workspaces Custom Resource for installing behind a proxy”.

3.1. Installing CodeReady Workspaces in a restricted environment using OperatorHub

Prerequisites

On disconnected OpenShift 4 clusters running on restricted networks, an Operator can be successfully installed from OperatorHub only if it meets the additional requirements defined in Enabling your Operator for restricted network environments.

The CodeReady Workspaces operator meets these requirements and is therefore compatible with the official documentation about OLM on a restricted network.

Procedure

To install CodeReady Workspaces from OperatorHub:

  1. Build a redhat-operators catalog image. See Building an Operator catalog image.
  2. Configure OperatorHub to use this catalog image for operator installations. See Configuring OperatorHub for restricted networks.
  3. Proceed to the CodeReady Workspaces installation as usual as described in Section 2.1, “Installing CodeReady Workspaces using the CodeReady Workspaces Operator in OpenShift 4 web console”.

3.2. Installing CodeReady Workspaces in a restricted environment using CLI management tool

Note

Use CodeReady Workspaces CLI management tool to install CodeReady Workspaces on restricted networks if installation through OperatorHub is not available. This method is supported for OpenShift Container Platform 3.11.

Prerequisites

3.2.1. Preparing an image registry for installing CodeReady Workspaces in a restricted environment

Prerequisites

  • The oc tool is installed.
  • The skopeo tool, version 0.1.40 or later, is installed.
  • The podman tool is installed.

  • An image registry that is accessible from the OpenShift cluster and supporting the format of the V2 image manifest, schema version 2. Ensure you can push to it from a location that has, at least temporarily, access to the internet.

    • When pushing to an image registry within the restricted environment, the OpenShift cluster must be able to access it.

The following placeholders are used in this section.

Table 3.1. Placeholders used in examples

<image-registry>

host name and port of the container-image registry accessible in the restricted environment

<organization>

organization of the container-image registry

Procedure

  1. Log into the internal image registry: 

    $ podman login --username <user> --password <password> <image-registry>
    Note

    If you encounter an error, such as x509: certificate signed by unknown authority, when attempting to push to the internal registry, either add the OpenShift cluster’s certificate to /etc/containers/certs.d/<image-registry>, or add the registry as an insecure registry by adding the following lines to the Podman configuration file located at /etc/containers/registries.conf: 

    [registries.insecure]
registries = ['<image-registry>']

To ensure that digests are not changed, use the skopeo copy --all command to copy images without changing them. Repeat this step for every image in the following lists:

+ 

$ skopeo copy --all docker://<image-name>:<image-tag> docker://<image-registry>/<organization>/<image-name>:<image-tag>

  1. Check if the images have the same digests: 

    $ skopeo inspect docker://<image-name>:<image-tag>
$ skopeo inspect docker://<image-registry>/<organization>/<image-name>:<image-tag>

    • Set the digests explicitly when different: 

      $ skopeo copy --all docker://<image_name>:<image_digest> docker://<image-registry>/<organization>/<image-namename>:<image-digest>

      Essential images

      Every workspace launch requires infrastructure images from the following list:

      • CodeReady Workspaces deployment and workspace support

        • registry.redhat.io/codeready-workspaces/{prod-operator-image-name}:2.3
        • registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator-metadata:2.3
        • registry.redhat.io/codeready-workspaces/devfileregistry-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/server-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/imagepuller-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/jwtproxy-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/pluginregistry-rhel8:2.3
        • registry.redhat.io/rh-sso-7/sso74-openshift-rhel8:7.4
        • registry.redhat.io/ubi8-minimal:8.2
        • registry.redhat.io/rhel8/postgresql-96:1

      • Plugins and editors

        • registry.redhat.io/codeready-workspaces/machineexec-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/theia-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8:2.3

      Workspace-specific images

      CodeReady Workspaces uses a subset of the following images to run a workspace. It is only necessary to include the images related to required technology stacks.

      • Plugins

        • registry.redhat.io/codeready-workspaces/plugin-java8-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/plugin-java11-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8:2.3

      • Stacks

        • registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/stacks-golang-rhel8:2.3
        • registry.redhat.io/codeready-workspaces/stacks-php-rhel8:2.3
        • registry.redhat.io/jboss-eap-7/eap73-openjdk8-openshift-rhel7:7.3.1

      • Workspace tooling

        • registry.redhat.io/rhscl/mongodb-36-rhel7:1-50

3.2.2. Preparing CodeReady Workspaces Custom Resource for restricted environment

When installing CodeReady Workspaces in a restricted environment using crwctl or OperatorHub, provide a CheCluster custom resource with additional information.

3.2.2.1. Downloading the default CheCluster Custom Resource

Procedure

  1. Download the default custom resource YAML file.
  2. Name the downloaded custom resource org_v1_che_cr.yaml. Keep it for further modification and usage.

3.2.2.2. Customizing the CheCluster Custom Resource for restricted environment

Prerequisites

Procedure

  1. In the CheCluster Custom Resource, which is managed by the CodeReady Workspaces Operator, add the fields used to facilitate deploying an instance of CodeReady Workspaces in a restricted environment: 

    # [...]
spec:
  server:
    airGapContainerRegistryHostname: '<image-registry>'
    airGapContainerRegistryOrganization: '<organization>'
# [...]

3.2.3. Starting CodeReady Workspaces installation in a restricted environment using CodeReady Workspaces CLI management tool

This sections describes how to start the CodeReady Workspaces installation in a restricted environment using the CodeReady Workspaces CLI management tool.

Prerequisites

Procedure

  1. Log in to OpenShift Container Platform: 

    $ oc login ${OPENSHIFT_API_URL} --username ${OPENSHIFT_USERNAME} \
                                --password ${OPENSHIFT_PASSWORD}

  2. Install CodeReady Workspaces with a customized Custom Resource to add fields related to the restricted environment: 

    $ crwctl server:start \
  --che-operator-image=<image-registry>/<organization>/crw-2-rhel8-operator:2.3 \
  --che-operator-cr-yaml=org_v1_che_cr.yaml
Note

For slow systems or internet connections, add the --k8spodwaittimeout=1800000 flag option to the crwctl server:start command to extend the Pod timeout period to 1800000 ms or longer.

3.3. Preparing CodeReady Workspaces Custom Resource for installing behind a proxy

This procedure describes how to provide necessary additional information to the CheCluster custom resource when installing CodeReady Workspaces behind a proxy.

Procedure

  1. In the CheCluster Custom Resource, which is managed by the CodeReady Workspaces Operator, add the fields used to facilitate deploying an instance of CodeReady Workspaces in a restricted environment: 

    # [...]
spec:
  server:
    proxyURL: '<URL of the proxy, with the http protocol, and without the port>'
    proxyPort: '<Port of proxy, typically 3128>'
# [...]

  2. In addition to those basic settings, the proxy configuration usually requires adding the host of the external OpenShift cluster API URL in the list of the hosts to be accessed from CodeReady Workspaces without using the proxy.

    To retrieve this cluster API host, run the following command against the OpenShift cluster: 

    $ oc whoami --show-server | sed 's#https://##' | sed 's#:.*$##'

    The corresponding field of the CheCluster Custom Resource is nonProxyHosts. If a host already exists in this field, use | as a delimiter to add the cluster API host: 

    # [...]
spec:
  server:
    nonProxyHosts: 'anotherExistingHost|<cluster api host>'
# [...]