Chapter 4. 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):
- Identify the image registry used by the OpenShift cluster, and ensure you can push to it.
- Push all the images needed for running CodeReady Workspaces to this registry.
- Configure CodeReady Workspaces to use the images that have been pushed to the registry.
- 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 4.3, “Preparing CodeReady Workspaces Custom Resource for installing behing a proxy”.
4.1. Installing CodeReady Workspaces in a restricted enviroment using OperatorHub
Prerequisites
- A running OpenShift cluster. See the OpenShift Container Platform 4.3 documentation for instructions on how to install an OpenShift cluster on a restricted network.
- Access to the mirror registry used to installed the OpenShift disconnected cluster in restricted network. See the Related OpenShift Container Platform 4.3 documentation about creating a mirror registry for installation in a restricted network.
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:
-
Build a
redhat-operators
catalog image. See Building an Operator catalog image. - Configure OperatorHub to use this catalog image for operator installations. See Configuring OperatorHub for restricted networks.
- Proceed to the CodeReady Workspaces installation as usual as described in Section 1.1, “Installing CodeReady Workspaces on OpenShift 4 from OperatorHub”.
4.2. Installing CodeReady Workspaces in a restricted enviroment using CLI management tool
Use CodeReady Workspaces CLI management tool to install CodeReady Workspaces on restricted networks only if installation through OperatorHub is not available. This method is not officially supported for OpenShift Container Platform 4.1 or later.
Prerequisites
- A running OpenShift cluster. See the OpenShift Container Platform 4.2 documentation for instructions on how to install an OpenShift cluster.
4.2.1. Preparing an image registry for installing CodeReady Workspaces in a restricted environment
Prerequisites
-
The
oc
tool is installed. - An image registry that is accessible from the OpenShift cluster. Ensure you can push to it from a location that has, at least temporarily, access to the Internet.
The
podman
tool is installed.NoteWhen pushing images to other registry than the OpenShift internal registry, and the
podman
tool fails to work, use thedocker
tool instead.
The following placeholders are used in this section.
| host name and port of the container-image registry accessible in the restricted environment |
| organization of the container-image registry |
For the OpenShift internal registry, the placeholder values are typically the following:
|
|
|
|
See OpenShift documentation for more details.
Procedure
Define the environment variable with the external endpoint of the image registry:
For the OpenShift internal registry, use:
$ REGISTRY_ENDPOINT=$(oc get route default-route --namespace openshift-image-registry \ --template='{{ .spec.host }}')
For other registries, use the host name and port of the image registry:
$ REGISTRY_ENDPOINT=<internal-registry>
Log into the internal image registry:
$ podman login --username <user> --password <password> <internal-registry>
NoteWhen using the OpenShift internal registry, follow the steps described in the related OpenShift documentation to first expose the internal registry through a route, and then log in to it.
Download, tag, and push the necessary images. Repeat the step for every image in the following lists:
$ podman pull <image_name>:<image_tag> $ podman tag <image_name>:<image_tag> ${REGISTRY_ENDPOINT}/<organization>/<image_name>:<image_tag> $ podman push ${REGISTRY_ENDPOINT}/<organization>/<image_name>:<image_tag>
Essential images
The following infrastructure images are included in every workspace launch:
- registry.redhat.io/codeready-workspaces/crw-2-rhel8-operator:2.1
- registry.redhat.io/codeready-workspaces/server-rhel8:2.1
- registry.redhat.io/codeready-workspaces/pluginregistry-rhel8:2.1
- registry.redhat.io/codeready-workspaces/devfileregistry-rhel8:2.1
- registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8:2.1
- registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8:2.1
- registry.redhat.io/codeready-workspaces/jwtproxy-rhel8:2.1
- registry.redhat.io/codeready-workspaces/machineexec-rhel8:2.1
- registry.redhat.io/codeready-workspaces/theia-rhel8:2.1
- registry.redhat.io/codeready-workspaces/theia-dev-rhel8:2.1
- registry.redhat.io/codeready-workspaces/theia-endpoint-rhel8:2.1
- registry.redhat.io/rhscl/postgresql-96-rhel7:1-47
- registry.redhat.io/redhat-sso-7/sso73-openshift:1.0-15
- registry.redhat.io/ubi8-minimal:8.1-398
Workspace-specific images
These are images that are required for running a workspace. A workspace generally uses only a subset of the images below. It is only necessary to include the images related to required technology stacks.
- registry.redhat.io/codeready-workspaces/stacks-cpp-rhel8:2.1
- registry.redhat.io/codeready-workspaces/stacks-dotnet-rhel8:2.1
- registry.redhat.io/codeready-workspaces/stacks-golang-rhel8:2.1
- registry.redhat.io/codeready-workspaces/stacks-java-rhel8:2.1
- registry.redhat.io/codeready-workspaces/stacks-node-rhel8:2.1
- registry.redhat.io/codeready-workspaces/stacks-php-rhel8:2.1
- registry.redhat.io/codeready-workspaces/stacks-python-rhel8:2.1
- registry.redhat.io/codeready-workspaces/plugin-java11-rhel8:2.1
- registry.redhat.io/codeready-workspaces/plugin-openshift-rhel8:2.1
- registry.redhat.io/codeready-workspaces/plugin-kubernetes-rhel8:2.1
4.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.
4.2.2.1. Downloading the default CheCluster
Custom Resource
Procedure
- Download the default custom resource YAML file.
-
Name the downloaded custom resource
org_v1_che_cr.yaml
. Keep it for further modification and usage.
4.2.2.2. Customizing the CheCluster
Custom Resource for restricted environment
Prerequisites
- All required images available in an image registry that is visible to the OpenShift cluster where CodeReady Workspaces is to be deployed. This is described in Section 4.2.1, “Preparing an image registry for installing CodeReady Workspaces in a restricted environment”, where the placeholders used in the following examples are also defined.
Procedure
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: '<internal-registry>' airGapContainerRegistryOrganization: '<organization>' # [...]
Setting these fields in the Custom Resource uses
<internal-registry>
and<organization>
for all images. This means, for example, that the Operator expects the offline plug-in and devfile registries to be available at:<internal-registry>/<organization>/pluginregistry-rhel8:<ver> <internal-registry>/<organization>/pluginregistry-rhel8:<ver>
For example, to use the OpenShift 4 internal registry as the image registry, define the following fields in the
CheCluster
Custom Resource:# [...] spec: server: airGapContainerRegistryHostname: 'image-registry.openshift-image-registry.svc:5000' airGapContainerRegistryOrganization: 'openshift' # [...]
-
In the downloaded
CheCluster
Custom Resource, add the two fields described above with the proper values according to the container-image registry with all the mirrored container images.
4.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
- CodeReady Workspaces CLI management tool is installed.
-
The
oc
tool is installed. - Access to an OpenShift instance.
Procedure
Log in to OpenShift Container Platform:
$ oc login ${OPENSHIFT_API_URL} --username ${OPENSHIFT_USERNAME} \ --password ${OPENSHIFT_PASSWORD}
Install CodeReady Workspaces with the customized Custom Resource to add fields related to restricted environment:
$ crwctl server:start \ --che-operator-image=<image-registry>/<organization>/server-operator-rhel8:2.1 \ --che-operator-cr-yaml=org_v1_che_cr.yaml
4.3. Preparing CodeReady Workspaces Custom Resource for installing behing a proxy
This procedure describes how to provide necessary additional information to the CheCluster
custom resource when installing CodeReady Workspaces behing a proxy.
Procedure
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>' # [...]
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 isnonProxyHosts
. 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>' # [...]