Chapter 1. Configuring the CodeReady Workspaces installation

The following section describes configuration options to install Red Hat CodeReady Workspaces using the Operator.

1.1. Understanding the CheCluster Custom Resource

A default deployment of CodeReady Workspaces consist in the application of a parametrized CheCluster Custom Resource by the Red Hat CodeReady Workspaces Operator.

CheCluster Custom Resource
  • A YAML document describing the configuration of the overall CodeReady Workspaces installation.
  • Contains sections to configure each component: auth, database, server, storage.
Role of the Red Hat CodeReady Workspaces Operator
  • To translate the CheCluster Custom Resource into configuration (ConfigMap) usable by each component of the CodeReady Workspaces installation.
Role of OpenShift
  • To apply the configuration (ConfigMap) for each component.
  • To create the necessary Pods.
  • When OpenShift detects a change in the configuration of a component, it restarts the Pods accordingly.

Example 1.1. Configuring the main properties of the CodeReady Workspaces server component

  1. The user applies a CheCluster Custom Resource containing some configuration related to the server.
  2. The Operator generates a necessary ConfigMap, called codeready.
  3. OpenShift detects change in the ConfigMap and triggers a restart of the CodeReady Workspaces Pod.

Additional resources

1.2. CheCluster Custom Resource fields reference

This section describes all fields available to customize the CheCluster Custom Resource.

Example 1.2. A minimal CheCluster Custom Resource example.

apiVersion: org.eclipse.che/v1
kind: CheCluster
metadata:
  name: codeready-workspaces
spec:
  auth:
    externalIdentityProvider: false
  database:
    externalDb: false
  server:
    selfSignedCert: false
    gitSelfSignedCert: false
    tlsSupport: true
  storage:
    pvcStrategy: 'common'
    pvcClaimSize: '1Gi'

Table 1.1. CheCluster Custom Resource server settings, related to the CodeReady Workspaces server component.

PropertyDefault valueDescription

airGapContainerRegistryHostname

omit

An optional host name or URL to an alternative container registry to pull images from. This value overrides the container registry host name defined in all default container images involved in a CodeReady Workspaces deployment. This is particularly useful to install CodeReady Workspaces in an air-gapped environment.

airGapContainerRegistryOrganization

omit

Optional repository name of an alternative container registry to pull images from. This value overrides the container registry organization defined in all the default container images involved in a CodeReady Workspaces deployment. This is particularly useful to install CodeReady Workspaces in an air-gapped environment.

cheDebug

false

Enables the debug mode for CodeReady Workspaces server.

cheFlavor

codeready-workspaces

Flavor of the installation.

cheHost

The Operator automatically sets the value.

A public host name of the installed CodeReady Workspaces server.

cheImagePullPolicy

Always for nightly or latest images, and IfNotPresent in other cases

Overrides the image pull policy used in CodeReady Workspaces deployment.

cheImageTag

omit

Overrides the tag of the container image used in CodeReady Workspaces deployment. Omit it or leave it empty to use the default image tag provided by the Operator.

cheImage

omit

Overrides the container image used in CodeReady Workspaces deployment. This does not include the container image tag. Omit it or leave it empty to use the default container image provided by the Operator.

cheLogLevel

INFO

Log level for the CodeReady Workspaces server: INFO or DEBUG.

cheWorkspaceClusterRole

omit

Custom cluster role bound to the user for the CodeReady Workspaces workspaces. Omit or leave empty to use the default roles.

customCheProperties

omit

Map of additional environment variables that will be applied in the generated codeready-workspaces ConfigMap to be used by the CodeReady Workspaces server, in addition to the values already generated from other fields of the CheCluster Custom Resource (CR). If customCheProperties contains a property that would be normally generated in codeready-workspaces ConfigMap from other CR fields, then the value defined in the customCheProperties will be used instead.

devfileRegistryImage

omit

Overrides the container image used in the Devfile registry deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator.

devfileRegistryMemoryLimit

256Mi

Overrides the memory limit used in the Devfile registry deployment.

devfileRegistryMemoryRequest

16Mi

Overrides the memory request used in the Devfile registry deployment.

devfileRegistryPullPolicy

Always for nightly or latest images, and IfNotPresent in other cases

Overrides the image pull policy used in the Devfile registry deployment.

devfileRegistryUrl

The Operator automatically sets the value.

Public URL of the Devfile registry that serves sample, ready-to-use devfiles. Set it if you use an external devfile registry (see the externalDevfileRegistry field).

externalDevfileRegistry

false

Instructs the Operator to deploy a dedicated Devfile registry server. By default a dedicated devfile registry server is started. If externalDevfileRegistry set to true, the Operator does not start a dedicated registry server automatically and you need to set the devfileRegistryUrl field manually.

externalPluginRegistry

false

Instructs the Operator to deploy a dedicated Plugin registry server. By default, a dedicated plug-in registry server is started. If externalPluginRegistry set to true, the Operator does not deploy a dedicated server automatically and you need to set the pluginRegistryUrl field manually.

nonProxyHosts

omit

List of hosts that will not use the configured proxy. Use |` as delimiter, for example localhost|my.host.com|123.42.12.32 Only use when configuring a proxy is required (see also the proxyURL field).

pluginRegistryImage

omit

Overrides the container image used in the Plugin registry deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator.

pluginRegistryMemoryLimit

256Mi

Overrides the memory limit used in the Plugin registry deployment.

pluginRegistryMemoryRequest

16Mi

Overrides the memory request used in the Plugin registry deployment.

pluginRegistryPullPolicy

Always for nightly or latest images, and IfNotPresent in other cases

Overrides the image pull policy used in the Plugin registry deployment.

pluginRegistryUrl

the Operator sets the value automatically

Public URL of the Plugin registry that serves sample ready-to-use devfiles. Set it only when using an external devfile registry (see the externalPluginRegistry field).

proxyPassword

omit

Password of the proxy server. Only use when proxy configuration is required.

proxyPort

omit

Port of the proxy server. Only use when configuring a proxy is required (see also the proxyURL field).

proxyURL

omit

URL (protocol+host name) of the proxy server. This drives the appropriate changes in the JAVA_OPTS and https(s)_proxy variables in the CodeReady Workspaces server and workspaces containers. Only use when configuring a proxy is required.

proxyUser

omit

User name of the proxy server. Only use when configuring a proxy is required (see also the proxyURL field).

selfSignedCert

false

Enables the support of OpenShift clusters with routers that use self-signed certificates. When enabled, the Operator retrieves the default self-signed certificate of OpenShift routes and adds it to the Java trust store of the CodeReady Workspaces server. Required when activating the tlsSupport field on demo OpenShift clusters that have not been setup with a valid certificate for the routes.

serverMemoryLimit

1Gi

Overrides the memory limit used in the CodeReady Workspaces server deployment.

serverMemoryRequest

512Mi

Overrides the memory request used in the CodeReady Workspaces server deployment.

tlsSupport

true

Instructs the Operator to deploy CodeReady Workspaces in TLS mode. Enabling TLS requires enabling the selfSignedCert field.

Table 1.2. CheCluster Custom Resource database configuration settings related to the database used by CodeReady Workspaces

PropertyDefault valueDescription

chePostgresDb

dbche

PostgreSQL database name that the CodeReady Workspaces server uses to connect to the database.

chePostgresHostName

the Operator sets the value automatically

PostgreSQL Database host name that the CodeReady Workspaces server uses to connect to. Defaults to postgres. Override this value only when using an external database. (See the field externalDb.)

chePostgresPassword

auto-generated value

PostgreSQL password that the CodeReady Workspaces server uses to connect to the database.

chePostgresPort

5432

PostgreSQL Database port that the CodeReady Workspaces server uses to connect to. Override this value only when using an external database (see field externalDb).

chePostgresUser

pgche

PostgreSQL user that the CodeReady Workspaces server uses to connect to the database.

externalDb

false

Instructs the Operator to deploy a dedicated database. By default, a dedicated PostgreSQL database is deployed as part of the CodeReady Workspaces installation. If set to true, the Operator does not deploy a dedicated database automatically, you need to provide connection details to an external database. See all the fields starting with: chePostgres.

postgresImagePullPolicy

Always` for nightly or latest images, and IfNotPresent in other cases

Overrides the image pull policy used in the PostgreSQL database deployment.

postgresImage

omit

Overrides the container image used in the PostgreSQL database deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator.

Table 1.3. CheCluster Custom Resource auth configuration settings related to authentication used by CodeReady Workspaces installation

PropertyDefault valueDescription

externalIdentityProvider

false

By default, a dedicated Identity Provider server is deployed as part of the CodeReady Workspaces installation. But if externalIdentityProvider is true, then no dedicated identity provider will be deployed by the Operator and you might need to provide details about the external identity provider you want to use. See also all the other fields starting with: identityProvider.

identityProviderAdminUserName

admin

Overrides the name of the Identity Provider admin user.

identityProviderClientId

omit

Name of an Identity provider (Keycloak / RH SSO) client-id that must be used for CodeReady Workspaces. This is useful to override it ONLY if you use an external Identity Provider (see the externalIdentityProvider field). If omitted or left blank, it will be set to the value of the flavor field suffixed with -public.

identityProviderImagePullPolicy

Always for nightly or latest images, and IfNotPresent in other cases

Overrides the image pull policy used in the Identity Provider (Keycloak / RH SSO) deployment.

identityProviderImage

omit

Overrides the container image used in the Identity Provider (Keycloak / RH SSO) deployment. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator.

identityProviderPassword

omit

Overrides the password of Keycloak admin user. Override it only when using an external Identity Provider (see the externalIdentityProvider field). Omit or leave empty to set an auto-generated password.

identityProviderPostgresPassword

the Operator sets the value automatically

Password for The Identity Provider (Keycloak / RH SSO) to connect to the database. This is useful to override it ONLY if you use an external Identity Provider (see the externalIdentityProvider field).

identityProviderRealm

omit

Name of an Identity provider (Keycloak / RH SSO) realm. Override it only when using an external Identity Provider (see the externalIdentityProvider field). Omit or leave empty blank to set it to the value of the flavor field.

identityProviderURL

the Operator sets the value automatically

Instructs the Operator to deploy a dedicated Identity Provider (Keycloak or RH SSO instance). Public URL of the Identity Provider server (Keycloak / RH SSO server). Set it only when using an external Identity Provider (see the externalIdentityProvider field).

oAuthClientName

the Operator sets the value automatically

Name of the OpenShift OAuthClient resource used to setup identity federation on the OpenShift side. See also the OpenShiftoAuth field.

oAuthSecret

the Operator sets the value automatically

Name of the secret set in the OpenShift OAuthClient resource used to setup identity federation on the OpenShift side. See also the OAuthClientName field.

openShiftoAuth

true on OpenShift

Enables the integration of the identity provider (Keycloak / RHSSO) with OpenShift OAuth. This allows users to log in with their OpenShift login and have their workspaces created under personal OpenShift projects. The kubeadmin user is not supported, and logging through does not allow access to the CodeReady Workspaces Dashboard.

updateAdminPassword

false

Forces the default admin CodeReady Workspaces user to update password on first login.

Table 1.4. CheCluster Custom Resource storage configuration settings related to persistent storage used by CodeReady Workspaces

PropertyDefault valueDescription

postgresPVCStorageClassName

omit

Storage class for the Persistent Volume Claim dedicated to the PostgreSQL database. Omitted or leave empty to use a default storage class.

preCreateSubPaths

false

Instructs the CodeReady Workspaces server to launch a special Pod to pre-create a subpath in the Persistent Volumes. Enable it according to the configuration of your K8S cluster.

pvcClaimSize

1Gi

Size of the persistent volume claim for workspaces.

pvcJobsImage

omit

Overrides the container image used to create sub-paths in the Persistent Volumes. This includes the image tag. Omit it or leave it empty to use the default container image provided by the Operator. See also the preCreateSubPaths field.

pvcStrategy

common

Available options:`common` (all workspaces PVCs in one volume), per-workspace (one PVC per workspace for all declared volumes) and unique (one PVC per declared volume).

workspacePVCStorageClassName

omit

Storage class for the Persistent Volume Claims dedicated to the CodeReady Workspaces workspaces. Omit or leave empty to use a default storage class.

Table 1.5. CheCluster Custom Resource k8s configuration settings specific to CodeReady Workspaces installations on OpenShift

PropertyDefault valueDescription

ingressClass

nginx

Ingress class that defines which controller manages ingresses.

ingressDomain

omit

Global ingress domain for a K8S cluster. This field must be explicitly specified. This drives the is kubernetes.io/ingress.class annotation on CodeReady Workspaces-related ingresses.

ingressStrategy

multi-host

Strategy for ingress creation. This can be multi-host (host is explicitly provided in ingress), single-host (host is provided, path-based rules) and default-host.*(no host is provided, path-based rules).

securityContextFsGroup,omitempty

1724

FSGroup the CodeReady Workspaces Pod and Workspace Pods containers run in.

securityContextRunAsUser

1724

ID of the user the CodeReady Workspaces Pod and Workspace Pods containers run as.

tlsSecretName

omit

Name of a secret that is used to set ingress TLS termination if TLS is enabled. See also the tlsSupport field.

Table 1.6. CheCluster Custom Resource status defines the observed state of CodeReady Workspaces installation

PropertyDescription

cheClusterRunning

Status of a CodeReady Workspaces installation. Can be Available, Unavailable, or Available, Rolling Update in Progress.

cheURL

Public URL to the CodeReady Workspaces server.

cheVersion

Currently installed CodeReady Workspaces version.

dbProvisioned

Indicates whether a PostgreSQL instance has been correctly provisioned.

devfileRegistryURL

Public URL to the Devfile registry.

helpLink

A URL to where to find help related to the current Operator status.

keycloakProvisioned

Indicates whether an Identity Provider instance (Keycloak / RH SSO) has been provisioned with realm, client and user.

keycloakURL

Public URL to the Identity Provider server (Keycloak / RH SSO).

message

A human-readable message with details about why the Pod is in this state.

openShiftoAuthProvisioned

Indicates whether an Identity Provider instance (Keycloak / RH SSO) has been configured to integrate with the OpenShift OAuth.

pluginRegistryURL

Public URL to the Plugin registry.

reason

A brief CamelCase message with details about why the Pod is in this state.