Chapter 3. Configuring Dev Spaces

Verification

1. Verify the value of the configured property:

   $ oc get configmap che -o jsonpath='{.data.<configured_property>}' \
   -n openshift-devspaces

Procedure

1. Edit the CheCluster Custom Resource on the cluster:

   $ oc edit checluster/devspaces -n openshift-devspaces

2. Save and close the file to apply the changes.

Verification

1. Verify the value of the configured property:

   $ oc get configmap che -o jsonpath='{.data.<configured_property>}' \
   -n openshift-devspaces

Procedure

1. Disable automatic namespace provisioning on the CheCluster level:

   devEnvironments:
     defaultNamespace:
       autoProvision: false

2. Create the <project_name> project for <username> user with the following labels and annotations:

   kind: Namespace
   apiVersion: v1
   metadata:
     name: <project_name> 1
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-namespace
     annotations:
       che.eclipse.org/username: <username>

   1

   Use a project name of your choosing.

Procedure

1. Create an HPA resource for a deployment, specifying the target metrics and desired replica count.

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: scaler
     namespace: openshift-devspaces
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: <deployment_name> 1
     ...

   1

   The <deployment_name> corresponds to the one following deployments:

   • devspaces
   • che-gateway
   • devspaces-dashboard
   • plugin-registry
   • devfile-registry

Procedure

1. Get the name of the OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   $ oc get checluster --all-namespaces \
     -o=jsonpath="{.items[*].metadata.namespace}"

2. Configure the maxNumberOfWorkspacesPerUser:

   $ oc patch checluster/devspaces -n openshift-devspaces \1
   --type='merge' -p \
   '{"spec":{"devEnvironments":{"maxNumberOfWorkspacesPerUser": <kept_workspaces_limit>}}}'2

   1

   The OpenShift Dev Spaces namespace that you got in step 1.

   2

   Your choice of the <kept_workspaces_limit> value.

Procedure

1. Configure the maxNumberOfRunningWorkspacesPerCluster:

   oc patch checluster/devspaces -n openshift-devspaces \
   --type='merge' -p \
   '{"spec":{"devEnvironments":{"maxNumberOfRunningWorkspacesPerCluster": <running_workspaces_limit>}}}'1

   1

   Your choice of the <running_workspaces_limit> value.

Procedure

1. Get the name of the OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   $ oc get checluster --all-namespaces \
     -o=jsonpath="{.items[*].metadata.namespace}"

2. Configure the maxNumberOfRunningWorkspacesPerUser:

   $ oc patch checluster/devspaces -n openshift-devspaces \1
   --type='merge' -p \
   '{"spec":{"devEnvironments":{"maxNumberOfRunningWorkspacesPerUser": <running_workspaces_limit>}}}'2

   1

   The OpenShift Dev Spaces namespace that you got in step 1.

   2

   Your choice of the <running_workspaces_limit> value.

Procedure

1. Create a new ConfigMap with details about the Git server:

   $ oc create configmap che-git-self-signed-cert \
     --from-file=ca.crt=<path_to_certificate> \  1
     --from-literal=githost=<git_server_url> -n openshift-devspaces  2

   1

   Path to the self-signed certificate.

   2

   Optional parameter to specify the Git server URL e.g. https://git.example.com:8443. When omitted, the self-signed certificate is used for all repositories over HTTPS.

   Note
   • Certificate files are typically stored as Base64 ASCII files, such as. .pem, .crt, .ca-bundle. All ConfigMaps that hold certificate files should use the Base64 ASCII certificate rather than the binary data certificate.
   • A certificate chain of trust is required. If the ca.crt is signed by a certificate authority (CA), the CA certificate must be included in the ca.crt file.

2. Add the required labels to the ConfigMap:

   $ oc label configmap che-git-self-signed-cert \
     app.kubernetes.io/part-of=che.eclipse.org -n openshift-devspaces

3. Configure OpenShift Dev Spaces operand to use self-signed certificates for Git repositories. See Section 3.1.2, “Using the CLI to configure the CheCluster Custom Resource”.

   spec:
     devEnvironments:
       trustedCerts:
         gitTrustedCertsConfigMapName: che-git-self-signed-cert

Procedure

1. Using NodeSelector

   OpenShift Dev Spaces uses CheCluster Custom Resource to configure nodeSelector:

   spec:
     devEnvironments:
       nodeSelector:
         key: value

   This section must contain a set of key=value pairs for each node label to form the nodeSelector rule.

2. Using Taints and Tolerations

   This works in the opposite way to nodeSelector. Instead of specifying which nodes the Pod will be scheduled on, you specify which nodes the Pod cannot be scheduled on. For more information, see: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration.

   OpenShift Dev Spaces uses CheCluster Custom Resource to configure tolerations:

   spec:
     devEnvironments:
       tolerations:
         - effect: NoSchedule
           key: key
           value: value
           operator: Equal

Procedure

1. Create the ConfigMap below to replicate it to every user namespace. To enhance the configurability, you can customize the ConfigMap by adding additional labels and annotations. See the Automatically mounting volumes, configmaps, and secrets for other possible labels and annotations.

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: user-configmap
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
   data:
     ...

   Example 3.16. Mounting a settings.xml file to a user workspace:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: user-settings-xml
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/.m2
   data:
     settings.xml: |
       <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
         <localRepository>/home/user/.m2/repository</localRepository>
         <interactiveMode>true</interactiveMode>
         <offline>false</offline>
       </settings>

2. Create the Secret below to replicate it to every user namespace. To enhance the configurability, you can customize the Secret by adding additional labels and annotations. See the Automatically mounting volumes, configmaps, and secrets for other possible labels and annotations.

   kind: Secret
   apiVersion: v1
   metadata:
     name: user-secret
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
   data:
     ...

   Example 3.17. Mounting certificates to a user workspace:

   kind: Secret
   apiVersion: v1
   metadata:
     name: user-certificates
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /etc/pki/ca-trust/source/anchors
   stringData:
     trusted-certificates.crt: |
       ...

   Note

   Run update-ca-trust command on workspace startup to import certificates. It can be achieved manually or by adding this command to a postStart event in a devfile. See the Adding event bindings in a devfile.

   Example 3.18. Mounting environment variables to a user workspace:

   kind: Secret
   apiVersion: v1
   metadata:
     name: user-env
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
     annotations:
       controller.devfile.io/mount-as: env
   stringData:
     ENV_VAR_1: value_1
     ENV_VAR_2: value_2

3. Create the PersistentVolumeClaim below to replicate it to every user namespace.

   To enhance the configurability, you can customize the PersistentVolumeClaim by adding additional labels and annotations. See the Automatically mounting volumes, configmaps, and secrets for other possible labels and annotations.

   To modify the 'PersistentVolumeClaim', delete it and create a new one in openshift-devspaces namespace.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: user-pvc
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
   spec:
     ...

   Example 3.19. Mounting a PersistentVolumeClaim to a user workspace:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: user-pvc
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
       controller.devfile.io/mount-to-devworkspace: 'true'
     annotations:
       controller.devfile.io/mount-path: /home/user/data
       controller.devfile.io/read-only: 'true'
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 5Gi
     volumeMode: Filesystem

1. Configure allowed sources:

   oc patch checluster/devspaces \
       --namespace openshift-devspaces \
       --type='merge' \
       -p \
   '{
      "spec": {
        "devEnvironments": {
          "allowedSources": {
            "urls": ["url_1", "url_2"] 1
          }
        }
      }
    }'

   1

   The array of approved URLs for starting Cloud Development Environments (CDEs). CDEs can only be initiated from these URLs. Wildcards * are supported in URLs. For example, https://example.com/* would allow CDEs to be initiated from any path within example.com.

Procedure

1. Gather a list of relevant container images to pull by navigating to the links:

   • https://<openshift_dev_spaces_fqdn>/plugin-registry/v3/external_images.txt
   • https://<openshift_dev_spaces_fqdn>/devfile-registry/devfiles/external_images.txt

2. Define the memory requests and limits parameters to ensure pulled containers and the platform have enough memory to run.

   When defining the minimal value for CACHING_MEMORY_REQUEST or CACHING_MEMORY_LIMIT, consider the necessary amount of memory required to run each of the container images to pull.

   When defining the maximal value for CACHING_MEMORY_REQUEST or CACHING_MEMORY_LIMIT, consider the total memory allocated to the DaemonSet Pods in the cluster:

   (memory limit) * (number of images) * (number of nodes in the cluster)

   Pulling 5 images on 20 nodes, with a container memory limit of 20Mi requires 2000Mi of memory.

3. Clone the Image Puller repository and get in the directory containing the OpenShift templates:

   $ git clone https://github.com/che-incubator/kubernetes-image-puller
   $ cd kubernetes-image-puller/deploy/openshift

4. Configure the app.yaml, configmap.yaml and serviceaccount.yaml OpenShift templates using following parameters:

   Table 3.37. Image Puller OpenShift templates parameters in app.yaml

   Value	Usage	Default
   DEPLOYMENT_NAME	The value of DEPLOYMENT_NAME in the ConfigMap	kubernetes-image-puller
   IMAGE	Image used for the kubernetes-image-puller deployment	registry.redhat.io/devspaces/imagepuller-rhel8
   IMAGE_TAG	The image tag to pull	latest
   SERVICEACCOUNT_NAME	The name of the ServiceAccount created and used by the deployment	kubernetes-image-puller

   Table 3.38. Image Puller OpenShift templates parameters in configmap.yaml

   Value	Usage	Default
   CACHING_CPU_LIMIT	The value of CACHING_CPU_LIMIT in the ConfigMap	.2
   CACHING_CPU_REQUEST	The value of CACHING_CPU_REQUEST in the ConfigMap	.05
   CACHING_INTERVAL_HOURS	The value of CACHING_INTERVAL_HOURS in the ConfigMap	"1"
   CACHING_MEMORY_LIMIT	The value of CACHING_MEMORY_LIMIT in the ConfigMap	"20Mi"
   CACHING_MEMORY_REQUEST	The value of CACHING_MEMORY_REQUEST in the ConfigMap	"10Mi"
   DAEMONSET_NAME	The value of DAEMONSET_NAME in the ConfigMap	kubernetes-image-puller
   DEPLOYMENT_NAME	The value of DEPLOYMENT_NAME in the ConfigMap	kubernetes-image-puller
   IMAGES	The value of IMAGES in the ConfigMap	{}
   NAMESPACE	The value of NAMESPACE in the ConfigMap	k8s-image-puller
   NODE_SELECTOR	The value of NODE_SELECTOR in the ConfigMap	"{}"

   Table 3.39. Image Puller OpenShift templates parameters in serviceaccount.yaml

   Value	Usage	Default
   SERVICEACCOUNT_NAME	The name of the ServiceAccount created and used by the deployment	kubernetes-image-puller
   KIP_IMAGE	The image puller image to copy the sleep binary from	registry.redhat.io/devspaces/imagepuller-rhel8:latest

5. Create an OpenShift project to host the Image Puller:

   $ oc new-project <k8s-image-puller>

6. Process and apply the templates to install the puller:

   $ oc process -f serviceaccount.yaml | oc apply -f -
   $ oc process -f configmap.yaml | oc apply -f -
   $ oc process -f app.yaml | oc apply -f -

Verification steps

1. Verify the existence of a <kubernetes-image-puller> deployment and a <kubernetes-image-puller> DaemonSet. The DaemonSet needs to have a Pod for each node in the cluster:

   $ oc get deployment,daemonset,pod --namespace <k8s-image-puller>

2. Verify the values of the <kubernetes-image-puller> ConfigMap.

   $ oc get configmap <kubernetes-image-puller> --output yaml

Procedure

1. Install the community supported Kubernetes Image Puller Operator. See Installing from OperatorHub using the web console.
2. Create a kubernetes-image-puller KubernetesImagePuller operand from the community supported Kubernetes Image Puller Operator. See Creating applications from installed Operators.

Procedure

1. Configure the Image Puller to pre-pull OpenShift Dev Spaces images.

   oc patch checluster/devspaces \
       --namespace openshift-devspaces \
       --type='merge' \
       --patch '{
                 "spec": {
                   "components": {
                     "imagePuller": {
                       "enable": true
                     }
                   }
                 }
               }'

Procedure

1. Configure the Image Puller to pre-pull custom images.

   oc patch checluster/devspaces \
       --namespace openshift-devspaces \
       --type='merge' \
       --patch '{
                 "spec": {
                   "components": {
                     "imagePuller": {
                       "enable": true,
                       "spec": {
                         "images": "NAME-1=IMAGE-1;NAME-2=IMAGE-2" 1
                       }
                     }
                   }
                 }
               }'

   1

   The semicolon separated list of images

Procedure

1. Create k8s-image-puller namespace:

   oc create namespace k8s-image-puller

2. Create KubernetesImagePuller Custom Resource:

   oc apply -f - <<EOF
   apiVersion: che.eclipse.org/v1alpha1
   kind: KubernetesImagePuller
   metadata:
     name: k8s-image-puller-images
     namespace: k8s-image-puller
   spec:
     images: "__NAME-1__=__IMAGE-1__;__NAME-2__=__IMAGE-2__" 1
   EOF

   1

   The semicolon separated list of images

Procedure

1. Pre-create a project for OpenShift Dev Spaces:

   $ oc create project openshift-devspaces

2. Create a TLS secret:

   $ oc create secret TLS <tls_secret_name> \ 1
   --key <key_file> \ 2
   --cert <cert_file> \ 3
   -n openshift-devspaces

   1

   The TLS secret name

   2

   A file with the private key

   3

   A file with the certificate

3. Add the required labels to the secret:

   $ oc label secret <tls_secret_name> \ 1
   app.kubernetes.io/part-of=che.eclipse.org -n openshift-devspaces

   1

   The TLS secret name

4. Configure the CheCluster Custom Resource. See Section 3.1.2, “Using the CLI to configure the CheCluster Custom Resource”.

   spec:
     networking:
       hostname: <hostname>     1
       tlsSecretName: <secret>  2

   1

   Custom Red Hat OpenShift Dev Spaces server hostname

   2

   The TLS secret name

5. If OpenShift Dev Spaces has been already deployed, wait until the rollout of all OpenShift Dev Spaces components finishes.

Procedure

1. Concatenate all CA chains PEM files to import, into the custom-ca-certificates.pem file, and remove the return character that is incompatible with the Java truststore.

   $ cat ca-cert-for-devspaces-*.pem | tr -d '\r' > custom-ca-certificates.pem

2. Create the custom-ca-certificates config map with the required TLS certificates:

   $ oc create configmap custom-ca-certificates \
       --from-file=custom-ca-certificates.pem \
       --namespace=openshift-devspaces

3. Label the custom-ca-certificates config map:

   $ oc label configmap custom-ca-certificates \
       app.kubernetes.io/component=ca-bundle \
       app.kubernetes.io/part-of=che.eclipse.org \
       --namespace=openshift-devspaces

4. Deploy OpenShift Dev Spaces if it hasn’t been deployed before. Otherwise, wait until the rollout of OpenShift Dev Spaces components finishes.
5. Restart running workspaces for the changes to take effect.

Verification steps

1. Verify that the config map contains your custom CA certificates. This command returns your custom CA certificates in PEM format:

   $ oc get configmap \
       --namespace=openshift-devspaces \
       --output='jsonpath={.items[0:].data.custom-ca-certificates\.pem}' \
       --selector=app.kubernetes.io/component=ca-bundle,app.kubernetes.io/part-of=che.eclipse.org

2. Verify OpenShift Dev Spaces pod contains a volume mounting the ca-certs-merged config map:

   $ oc get pod \
       --selector=app.kubernetes.io/component=devspaces \
       --output='jsonpath={.items[0].spec.volumes[0:].configMap.name}' \
       --namespace=openshift-devspaces \
       | grep ca-certs-merged

3. Verify the OpenShift Dev Spaces server container has your custom CA certificates. This command returns your custom CA certificates in PEM format:

   $ oc exec -t deploy/devspaces \
       --namespace=openshift-devspaces \
       -- cat /public-certs/custom-ca-certificates.pem

4. Verify in the OpenShift Dev Spaces server logs that the imported certificates count is not null:

   $ oc logs deploy/devspaces --namespace=openshift-devspaces \
       | grep custom-ca-certificates.pem

5. List the SHA256 fingerprints of your certificates:

   $ for certificate in ca-cert*.pem ;
     do openssl x509 -in $certificate -digest -sha256 -fingerprint -noout | cut -d= -f2;
     done

6. Verify that OpenShift Dev Spaces server Java truststore contains certificates with the same fingerprint:

   $ oc exec -t deploy/devspaces --namespace=openshift-devspaces -- \
       keytool -list -keystore /home/user/cacerts \
       | grep --after-context=1 custom-ca-certificates.pem

7. Start a workspace, get the project name in which it has been created: <workspace_namespace>, and wait for the workspace to be started.

8. Verify that the che-trusted-ca-certs config map contains your custom CA certificates. This command returns your custom CA certificates in PEM format:

   $ oc get configmap che-trusted-ca-certs \
       --namespace=<workspace_namespace> \
       --output='jsonpath={.data.custom-ca-certificates\.custom-ca-certificates\.pem}'

9. Verify that the workspace pod mounts the che-trusted-ca-certs config map:

   $ oc get pod \
       --namespace=<workspace_namespace> \
       --selector='controller.devfile.io/devworkspace_name=<workspace_name>' \
       --output='jsonpath={.items[0:].spec.volumes[0:].configMap.name}' \
       | grep che-trusted-ca-certs

10. Verify that the universal-developer-image container (or the container defined in the workspace devfile) mounts the che-trusted-ca-certs volume:

    $ oc get pod \
        --namespace=<workspace_namespace> \
        --selector='controller.devfile.io/devworkspace_name=<workspace_name>' \
        --output='jsonpath={.items[0:].spec.containers[0:]}' \
        | jq 'select (.volumeMounts[].name == "che-trusted-ca-certs") | .name'

11. Get the workspace pod name <workspace_pod_name>:

    $ oc get pod \
        --namespace=<workspace_namespace> \
        --selector='controller.devfile.io/devworkspace_name=<workspace_name>' \
        --output='jsonpath={.items[0:].metadata.name}' \

12. Verify that the workspace container has your custom CA certificates. This command returns your custom CA certificates in PEM format:

    $ oc exec <workspace_pod_name> \
        --namespace=<workspace_namespace> \
        -- cat /public-certs/custom-ca-certificates.custom-ca-certificates.pem

1. Define storage class names: configure the CheCluster Custom Resource, and install OpenShift Dev Spaces. See Section 3.1.1, “Using dsc to configure the CheCluster Custom Resource during installation”.

   spec:
     devEnvironments:
       storage:
         perUserStrategyPvcConfig:
           claimSize: <claim_size> 1
           storageClass: <storage_class_name> 2
         perWorkspaceStrategyPvcConfig:
           claimSize: <claim_size> 3
           storageClass: <storage_class_name> 4
         pvcStrategy: <pvc_strategy> 5

   1 3

   Persistent Volume Claim size.

   2 4

   Storage class for the Persistent Volume Claim. When omitted or left blank, a default storage class is used.

   5

   Persistent volume claim strategy. The supported strategies are: per-user (all workspaces Persistent Volume Claims in one volume), per-workspace (each workspace is given its own individual Persistent Volume Claim) and ephemeral (non-persistent storage where local changes will be lost when the workspace is stopped.)

Procedure

1. Set the pvcStrategy field in the Che Cluster Custom Resource to per-user, per-workspace or ephemeral.

Procedure

1. Set the appropriate claimSize field for the desired storage strategy in the Che Cluster Custom Resource.

Procedure

1. Create a JSON file with the samples configuration. The file must contain an array of objects, where each object represents a sample.

   cat > my-samples.json <<EOF
   [
     {
       "displayName": "<display_name>", 1
       "description": "<description>", 2
       "tags": <tags>, 3
       "url": "<url>", 4
       "icon": {
         "base64data": "<base64data>", 5
         "mediatype": "<mediatype>" 6
       }
     }
   ]
   EOF

   1

   The display name of the sample.

   2

   The description of the sample.

   3

   The JSON array of tags, for example, ["java", "spring"].

   4

   The URL to the repository containing the devfile.

   5

   The base64-encoded data of the icon.

   6

   The media type of the icon. For example, image/png.

2. Create a ConfigMap with the samples configuration:

   oc create configmap getting-started-samples --from-file=my-samples.json -n openshift-devspaces

3. Add the required labels to the ConfigMap:

   oc label configmap getting-started-samples app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=getting-started-samples -n openshift-devspaces

4. Refresh the OpenShift Dev Spaces Dashboard page to see the new samples.

Procedure

1. Create the my-editor-definition-devfile.yaml YAML file with the editor definition configuration.

   Important

   Make sure you provide the actual values for publisher and version under metadata.attributes. They are used to construct the editor id along with editor name in the following format publisher/name/version.

   Below you can find the supported values, including optional ones:

   # Version of the devile schema
   schemaVersion: 2.2.2
   # Meta information of the editor
   metadata:
     # (MANDATORY) The editor name
     # Must consist of lower case alphanumeric characters, '-' or '.'
     name: editor-name
     displayName: Display Name
     description: Run Editor Foo on top of Eclipse Che
     # (OPTIONAL) Array of tags of the current editor. The Tech-Preview tag means the option is considered experimental and is not recommended for production environments. While it can include new features and improvements, it may still contain bugs or undergo significant changes before reaching a stable version.
     tags:
       - Tech-Preview
     # Additional attributes
     attributes:
       title: This is my editor
       # (MANDATORY) The publisher name
       publisher: publisher
       # (MANDATORY) The editor version
       version: version
       repository: https://github.com/editor/repository/
       firstPublicationDate: '2024-01-01'
       iconMediatype: image/svg+xml
       iconData: |
         <icon-content>
   # List of editor components
   components:
     # Name of the component
     - name: che-code-injector
       # Configuration of devworkspace-related container
       container:
         # Image of the container
         image: 'quay.io/che-incubator/che-code:insiders'
         # The command to run in the dockerimage component instead of the default one provided in the image
         command:
           - /entrypoint-init-container.sh
         # (OPTIONAL) List of volumes mounts that should be mounted in this container
         volumeMounts:
             # The name of the mount
           - name: checode
             # The path of the mount
             path: /checode
         # (OPTIONAL) The memory limit of the container
         memoryLimit: 256Mi
         # (OPTIONAL) The memory request of the container
         memoryRequest: 32Mi
         # (OPTIONAL) The CPU limit of the container
         cpuLimit: 500m
         # (OPTIONAL) The CPU request of the container
         cpuRequest: 30m
     # Name of the component
     - name: che-code-runtime-description
       # (OPTIONAL) Map of implementation-dependant free-form YAML attributes
       attributes:
         # The component within the architecture
         app.kubernetes.io/component: che-code-runtime
         # The name of a higher level application this one is part of
         app.kubernetes.io/part-of: che-code.eclipse.org
         # Defines a container component as a "container contribution". If a flattened DevWorkspace has a container component with the merge-contribution attribute, then any container contributions are merged into that container component
         controller.devfile.io/container-contribution: true
       container:
         # Can be a dummy image because the component is expected to be injected into workspace dev component
         image: quay.io/devfile/universal-developer-image:latest
         # (OPTIONAL) List of volume mounts that should be mounted in this container
         volumeMounts:
             # The name of the mount
           - name: checode
             # (OPTIONAL) The path in the component container where the volume should be mounted. If no path is defined, the default path is the is /<name>
             path: /checode
         # (OPTIONAL) The memory limit of the container
         memoryLimit: 1024Mi
         # (OPTIONAL) The memory request of the container
         memoryRequest: 256Mi
         # (OPTIONAL) The CPU limit of the container
         cpuLimit: 500m
         # (OPTIONAL) The CPU request of the container
         cpuRequest: 30m
         # (OPTIONAL) Environment variables used in this container
         env:
           - name: ENV_NAME
             value: value
         # Component endpoints
         endpoints:
           # Name of the editor
           - name: che-code
             # (OPTIONAL) Map of implementation-dependant string-based free-form attributes
             attributes:
               # Type of the endpoint. You can only set its value to main, indicating that the endpoint should be used as the mainUrl in the workspace status (i.e. it should be the URL used to access the editor in this context)
               type: main
               # An attribute that instructs the service to automatically redirect the unauthenticated requests for current user authentication. Setting this attribute to true has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute is false.
               cookiesAuthEnabled: true
               # Defines an endpoint as "discoverable", meaning that a service should be created using the endpoint name (i.e. instead of generating a service name for all endpoints, this endpoint should be statically accessible)
               discoverable: false
               # Used to secure the endpoint with authorization on OpenShift, so that not anyone on the cluster can access the endpoint, the attribute enables authentication.
               urlRewriteSupported: true
             # Port number to be used within the container component
             targetPort: 3100
             # (OPTIONAL) Describes how the endpoint should be exposed on the network (public, internal, none)
             exposure: public
             # (OPTIONAL) Describes whether the endpoint should be secured and protected by some authentication process
             secure: true
             # (OPTIONAL) Describes the application and transport protocols of the traffic that will go through this endpoint
             protocol: https
       # Mandatory name that allows referencing the component from other elements
     - name: checode
       # (OPTIONAL) Allows specifying the definition of a volume shared by several other components. Ephemeral volumes are not stored persistently across restarts. Defaults to false
       volume: {ephemeral: true}
   # (OPTIONAL) Bindings of commands to events. Each command is referred-to by its name
   events:
     # IDs of commands that should be executed before the devworkspace start. These commands would typically be executed in an init container
     preStart:
       - init-container-command
     # IDs of commands that should be executed after the devworkspace has completely started. In the case of Che-Code, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE within the browser
     postStart:
       - init-che-code-command
   # (OPTIONAL) Predefined, ready-to-use, devworkspace-related commands
   commands:
       # Mandatory identifier that allows referencing this command
     - id: init-container-command
       apply:
         # Describes the component for the apply command
         component: che-code-injector
       # Mandatory identifier that allows referencing this command
     - id: init-che-code-command
       # CLI Command executed in an existing component container
       exec:
         # Describes component for the exec command
         component: che-code-runtime-description
         # The actual command-line string
         commandLine: 'nohup /checode/entrypoint-volume.sh > /checode/entrypoint-logs.txt
           2>&1 &'

2. Create a ConfigMap with the editor definition content:

   oc create configmap my-editor-definition --from-file=my-editor-definition-devfile.yaml -n openshift-devspaces

3. Add the required labels to the ConfigMap:

   oc label configmap my-editor-definition app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=editor-definition -n openshift-devspaces

4. Refresh the OpenShift Dev Spaces Dashboard page to see new available editor.

Procedure

1. Find out the IDs of the available editors:

   oc exec deploy/devspaces-dashboard -n openshift-devspaces  \
       -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '.[] | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"'

2. Configure the defaultEditor:

   oc patch checluster/devspaces \
       --namespace openshift-devspaces \
       --type='merge' \
       -p '{"spec":{"devEnvironments":{"defaultEditor": "<default_editor>"}}}'1

   1

   The default editor for creating a workspace can be specified using either a plugin ID or a URI. The plugin ID should follow the format: publisher/name/version. See available editors IDs in the first step.

Procedure

1. Find out the namespace where the OpenShift Dev Spaces Operator is deployed:

   OPERATOR_NAMESPACE=$(oc get pods -l app.kubernetes.io/component=devspaces-operator -o jsonpath={".items[0].metadata.namespace"} --all-namespaces)

2. Find out the available editors definitions files:

   oc exec -n $OPERATOR_NAMESPACE deploy/devspaces-operator -- ls /tmp/editors-definitions

   The output should look similar to the following example:

   che-code-insiders.yaml
   che-code-latest.yaml
   che-idea-latest.yaml
   che-idea-next.yaml

3. Choose an editor definition to conceal. For example, to conceal the che-idea-next.yaml editor definition, set the editor definition file name:

   CHE_EDITOR_CONCEAL_FILE_NAME=che-idea-next.yaml

4. Define the ConfigMap name for the concealed editor definition:

   CHE_EDITOR_CONCEAL_CONFIGMAP_NAME=che-conceal-$CHE_EDITOR_CONCEAL_FILE_NAME

5. Create the ConfigMap:

   oc create configmap $CHE_EDITOR_CONCEAL_CONFIGMAP_NAME \
       --namespace $OPERATOR_NAMESPACE \
       --from-literal=$CHE_EDITOR_CONCEAL_FILE_NAME=""

6. Find out the Operator subscription name and namespace (if it exists):

   SUBSCRIPTION=$(oc get subscriptions \
       --all-namespaces \
       --output json \
           | jq -r '.items[] | select(.spec.name=="devspaces")')
   SUBSCRIPTION_NAMESPACE=$(echo $SUBSCRIPTION | jq -r '.metadata.namespace')
   SUBSCRIPTION_NAME=$(echo $SUBSCRIPTION | jq -r '.metadata.name')

7. Patch the Kubernetes resource to mount the ConfigMap with the empty editor definition. The resource to patch depends on the existence of the Operator subscription. If the subscription exists, then the subscription should be patched. If not, patch the Operator deployment:

   if [[ -n $SUBSCRIPTION_NAMESPACE ]]; then
       if [[ $(oc get subscription $SUBSCRIPTION_NAME --namespace $SUBSCRIPTION_NAMESPACE --output jsonpath='{.spec.config}') == "" ]]; then
           oc patch subscription $SUBSCRIPTION_NAME \
             --namespace $SUBSCRIPTION_NAMESPACE \
             --type json \
             --patch '[{
                   "op":"add",
                   "path":"/spec/config",
                   "value": {}
               }]'
       fi
   
       if [[ $(oc get subscription $SUBSCRIPTION_NAME --namespace $SUBSCRIPTION_NAMESPACE --output jsonpath='{.spec.config.volumes}') == "" ]]; then
           oc patch subscription $SUBSCRIPTION_NAME \
             --namespace $SUBSCRIPTION_NAMESPACE \
             --type json \
             --patch '[{
                   "op":"add",
                   "path":"/spec/config/volumes",
                   "value": []
               }]'
       fi
   
       if [[ $(oc get subscription $SUBSCRIPTION_NAME --namespace $SUBSCRIPTION_NAMESPACE --output jsonpath='{.spec.config.volumeMounts}') == "" ]]; then
           oc patch subscription $SUBSCRIPTION_NAME \
             --namespace $SUBSCRIPTION_NAMESPACE \
             --type json \
             --patch '[{
                   "op":"add",
                   "path":"/spec/config/volumeMounts",
                   "value": []
               }]'
       fi
   
       oc patch subscription $SUBSCRIPTION_NAME \
         --namespace $SUBSCRIPTION_NAMESPACE \
         --type json \
         --patch '[{
           "op":"add",
           "path":"/spec/config/volumes/-",
           "value": {
               "name":"'$(echo ${CHE_EDITOR_CONCEAL_FILE_NAME%.*})'",
               "configMap": {
                   "name": "'$CHE_EDITOR_CONCEAL_CONFIGMAP_NAME'"
               }
           }
         },
         {
           "op":"add",
           "path":"/spec/config/volumeMounts/-",
           "value":{
               "name": "'$(echo ${CHE_EDITOR_CONCEAL_FILE_NAME%.*})'",
               "subPath":"'$CHE_EDITOR_CONCEAL_FILE_NAME'",
               "mountPath": "/tmp/editors-definitions/'$CHE_EDITOR_CONCEAL_FILE_NAME'"
           }
         }]'
   else
       oc patch deployment devspaces-operator \
         --namespace $OPERATOR_NAMESPACE \
         --type json \
         --patch '[{
           "op":"add",
           "path":"/spec/template/spec/volumes/-",
           "value": {
               "name":"'$(echo ${CHE_EDITOR_CONCEAL_FILE_NAME%.*})'",
               "configMap": {
                   "name": "'$CHE_EDITOR_CONCEAL_CONFIGMAP_NAME'"
               }
           }
       },
       {
           "op":"add",
           "path":"/spec/template/spec/containers/0/volumeMounts/-",
           "value":{
               "name": "'$(echo ${CHE_EDITOR_CONCEAL_FILE_NAME%.*})'",
               "subPath":"'$CHE_EDITOR_CONCEAL_FILE_NAME'",
               "mountPath": "/tmp/editors-definitions/'$CHE_EDITOR_CONCEAL_FILE_NAME'"
           }
       }
   ]'
   fi

Procedure

1. Create a Secret:

   oc apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: devspaces-dashboard-customization
     namespace: openshift-devspaces
     annotations:
       che.eclipse.org/mount-as: subpath
       che.eclipse.org/mount-path: /public/dashboard/assets/branding
     labels:
       app.kubernetes.io/component: devspaces-dashboard-secret
       app.kubernetes.io/part-of: che.eclipse.org
   data:
     loader.svg: <Base64_encoded_content_of_the_image> 1
   type: Opaque
   EOF

   1

   Base64 encoding with disabled line wrapping.

2. Wait until the rollout of devspaces-dashboard finishes.

Procedure

1. Define the user roles name:

   $ USER_ROLES=<name> 1

   1

   Unique resource name.

2. Find out the namespace where the OpenShift Dev Spaces Operator is deployed:

   $ OPERATOR_NAMESPACE=$(oc get pods -l app.kubernetes.io/component=devspaces-operator -o jsonpath={".items[0].metadata.namespace"} --all-namespaces)

3. Create needed roles:

   $ kubectl apply -f - <<EOF
   kind: ClusterRole
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     name: ${USER_ROLES}
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
   rules:
     - verbs:
         - <verbs> 1
       apiGroups:
         - <apiGroups> 2
       resources:
         - <resources> 3
   EOF

   1

   As <verbs>, list all Verbs that apply to all ResourceKinds and AttributeRestrictions contained in this rule. You can use * to represent all verbs.

   2

   As <apiGroups>, name the APIGroups that contain the resources.

   3

   As <resources>, list all resources that this rule applies to. You can use * to represent all verbs.

4. Delegate the roles to the OpenShift Dev Spaces Operator:

   $ kubectl apply -f - <<EOF
   kind: ClusterRoleBinding
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     name: ${USER_ROLES}
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
   subjects:
     - kind: ServiceAccount
       name: devspaces-operator
       namespace: ${OPERATOR_NAMESPACE}
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: ${USER_ROLES}
   EOF

5. Configure the OpenShift Dev Spaces Operator to delegate the roles to the che service account:

   $ kubectl patch checluster devspaces \
     --patch '{"spec": {"components": {"cheServer": {"clusterRoles": ["'${USER_ROLES}'"]}}}}' \
     --type=merge -n openshift-devspaces

6. Configure the OpenShift Dev Spaces server to delegate the roles to a user:

   $ kubectl patch checluster devspaces \
     --patch '{"spec": {"devEnvironments": {"user": {"clusterRoles": ["'${USER_ROLES}'"]}}}}' \
     --type=merge -n openshift-devspaces

7. Wait for the rollout of the OpenShift Dev Spaces server components to be completed.
8. Ask the user to log out and log in to have the new roles applied.

Procedure

1. Configure the CheCluster Custom Resource. See Section 3.1.2, “Using the CLI to configure the CheCluster Custom Resource”.

   spec:
     networking:
       auth:
         advancedAuthorization:
           allowUsers:
             - <allow_users> 1
           allowGroups:
             - <allow_groups> 2
           denyUsers:
             - <deny_users> 3
           denyGroups:
             - <deny_groups> 4

   1

   List of users allowed to access Red Hat OpenShift Dev Spaces.

   2

   List of groups of users allowed to access Red Hat OpenShift Dev Spaces (for OpenShift Container Platform only).

   3

   List of users denied access to Red Hat OpenShift Dev Spaces.

   4

   List of groups of users denied to access Red Hat OpenShift Dev Spaces (for OpenShift Container Platform only).

2. Wait for the rollout of the OpenShift Dev Spaces server components to be completed.

Procedure

1. List all the users in the OpenShift cluster using the following command:

   $ oc get users

2. Delete the user entry:

Procedure

1. Set the environment variable based on the type of your OpenShift cluster: a single node cluster, or a multi node cluster with separate control plane and worker nodes.

   • For a single node cluster, set:

     $ NODE_ROLE=master

   • For a multi node cluster, set:

     $ NODE_ROLE=worker

2. Set the environment variable for the OpenShift Butane config version. This variable is the major and minor version of the OpenShift cluster. For example, 4.12.0, 4.13.0, or 4.14.0.

   $ VERSION=4.12.0

3. Create a MachineConfig resource that creates a drop-in CRI-O configuration file named 99-podman-fuse in the NODE_ROLE nodes. This configuration file makes access to the /dev/fuse device possible for certain pods.

   cat << EOF | butane | oc apply -f -
   variant: openshift
   version: ${VERSION}
   metadata:
     labels:
       machineconfiguration.openshift.io/role: ${NODE_ROLE}
     name: 99-podman-dev-fuse-${NODE_ROLE}
   storage:
     files:
     - path: /etc/crio/crio.conf.d/99-podman-fuse 1
       mode: 0644
       overwrite: true
       contents: 2
         inline: |
           [crio.runtime.workloads.podman-fuse] 3
           activation_annotation = "io.openshift.podman-fuse" 4
           allowed_annotations = [
             "io.kubernetes.cri-o.Devices" 5
           ]
           [crio.runtime]
           allowed_devices = ["/dev/fuse"] 6
   EOF

   1

   The absolute file path to the new drop-in configuration file for CRI-O.

   2

   The content of the new drop-in configuration file.

   3

   Define a podman-fuse workload.

   4

   The pod annotation that activates the podman-fuse workload settings.

   5

   List of annotations the podman-fuse workload is allowed to process.

   6

   List of devices on the host that a user can specify with the io.kubernetes.cri-o.Devices annotation.

4. After applying the MachineConfig resource, scheduling will be temporarily disabled for each node with the worker role as changes are applied. View the nodes' statuses.

   $ oc get nodes

   Example output:

   NAME                           STATUS                     ROLES    AGE   VERSION
   ip-10-0-136-161.ec2.internal   Ready                      worker   28m   v1.27.9
   ip-10-0-136-243.ec2.internal   Ready                      master   34m   v1.27.9
   ip-10-0-141-105.ec2.internal   Ready,SchedulingDisabled   worker   28m   v1.27.9
   ip-10-0-142-249.ec2.internal   Ready                      master   34m   v1.27.9
   ip-10-0-153-11.ec2.internal    Ready                      worker   28m   v1.27.9
   ip-10-0-153-150.ec2.internal   Ready                      master   34m   v1.27.9

5. Once all nodes with the worker role have a status Ready, /dev/fuse will be available to any pod with the following annotations.

   io.openshift.podman-fuse: ''
   io.kubernetes.cri-o.Devices: /dev/fuse

Verification steps

1. Get the name of a node with a worker role:

   $ oc get nodes

2. Open an oc debug session to a worker node.

   $ oc debug node/<nodename>

3. Verify that a new CRI-O config file named 99-podman-fuse exists.

   sh-4.4# stat /host/etc/crio/crio.conf.d/99-podman-fuse

Procedure

1. Create a ConfigMap that mounts the storage.conf file for all user workspaces.

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: fuse-overlay
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: workspaces-config
     annotations:
       controller.devfile.io/mount-as: subpath
       controller.devfile.io/mount-path: /home/user/.config/containers/
   data:
     storage.conf: |
       [storage]
       driver = "overlay"
   
       [storage.options.overlay]
       mount_program="/usr/bin/fuse-overlayfs"

   Warning

   Creating this ConfigMap will cause all running workspaces to restart.

2. Set the necessary annotation in the spec.devEnvironments.workspacesPodAnnotations field of the CheCluster custom resource.

   kind: CheCluster
   apiVersion: org.eclipse.che/v2
   spec:
     devEnvironments:
       workspacesPodAnnotations:
         io.kubernetes.cri-o.Devices: /dev/fuse

   Note

   For OpenShift versions before 4.15, the io.openshift.podman-fuse: "" annotation is also required.

Verification steps

1. Start a workspace and verify that the storage driver is overlay.

   $ podman info | grep overlay

   Example output:

   graphDriverName: overlay
     overlay.mount_program:
       Executable: /usr/bin/fuse-overlayfs
       Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64
         fuse-overlayfs: version 1.12
     Backing Filesystem: overlayfs

   Note

   The following error might occur for existing workspaces:

   ERRO[0000] User-selected graph driver "overlay" overwritten by graph driver "vfs" from database - delete libpod local files ("/home/user/.local/share/containers/storage") to resolve.  May prevent use of images created by other tools

   In this case, delete the libpod local files as mentioned in the error message.