Administration guide

Procedure

1. Optional: If you previously deployed OpenShift Dev Spaces on this OpenShift cluster, ensure that the previous OpenShift Dev Spaces instance is removed:

   $ dsc server:delete

   Copy to Clipboard Toggle word wrap

2. Create the OpenShift Dev Spaces instance:

   $ dsc server:deploy --platform openshift

   Copy to Clipboard Toggle word wrap

Verification steps

1. Verify the OpenShift Dev Spaces instance status:

   $ dsc server:status

   Copy to Clipboard Toggle word wrap

2. Navigate to the OpenShift Dev Spaces cluster instance:

   $ dsc dashboard:open

   Copy to Clipboard Toggle word wrap

Procedure

1. In the Administrator view of the OpenShift web console, go to Operators → OperatorHub and search for Red Hat OpenShift Dev Spaces.

2. Install the Red Hat OpenShift Dev Spaces Operator.

   Tip

   See Installing from OperatorHub using the web console.

   Important

   The Red Hat OpenShift Dev Spaces Operator depends on the Dev Workspace Operator. If you install the Red Hat OpenShift Dev Spaces Operator manually to a non-default namespace, ensure that the Dev Workspace Operator is also installed in the same namespace. This is required as the Operator Lifecycle Manager will attempt to install the Dev Workspace Operator as a dependency within the Red Hat OpenShift Dev Spaces Operator namespace, potentially resulting in two conflicting installations of the Dev Workspace Operator if the latter is installed in a different namespace.

1. Create the openshift-devspaces project in OpenShift as follows:

   oc create namespace openshift-devspaces

   Copy to Clipboard Toggle word wrap
2. Go to Operators → Installed Operators → Red Hat OpenShift Dev Spaces instance Specification → Create CheCluster → YAML view.
3. In the YAML view, replace namespace: openshift-operators with namespace: openshift-devspaces.

4. Select Create.

   Tip

   See Creating applications from installed Operators.

1. In Red Hat OpenShift Dev Spaces instance Specification, go to devspaces, landing on the Details tab.

1. Under Message, check that there is None, which means no errors.
2. Under Red Hat OpenShift Dev Spaces URL, wait until the URL of the OpenShift Dev Spaces instance appears, and then open the URL to check the OpenShift Dev Spaces dashboard.
3. In the Resources tab, view the resources for the OpenShift Dev Spaces deployment and their status.

Procedure

1. Download and execute the mirroring script to install a custom Operator catalog and mirror the related images: prepare-restricted-environment.sh.

   $ bash prepare-restricted-environment.sh \
     --devworkspace_operator_index registry.redhat.io/redhat/redhat-operator-index:v4.15\
     --devworkspace_operator_version "v0.27.0" \
     --prod_operator_index "registry.redhat.io/redhat/redhat-operator-index:v4.15" \
     --prod_operator_package_name "devspaces" \
     --prod_operator_bundle_name "devspacesoperator" \
     --prod_operator_version "v3.13.0" \
     --my_registry "<my_registry>" 

   1

   Copy to Clipboard Toggle word wrap

   1

   The private Docker registry where the images will be mirrored

2. Install OpenShift Dev Spaces with the configuration set in the che-operator-cr-patch.yaml during the previous step:

   $ dsc server:deploy \
     --platform=openshift \
     --olm-channel stable \
     --catalog-source-name=devspaces-disconnected-install \
     --catalog-source-namespace=openshift-marketplace \
     --skip-devworkspace-operator \
     --che-operator-cr-patch-yaml=che-operator-cr-patch.yaml

   Copy to Clipboard Toggle word wrap
3. Allow incoming traffic from the OpenShift Dev Spaces namespace to all Pods in the user projects. See: Section 3.7.1, “Configuring network policies”.

Verification

1. Verify the value of the configured property:

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

   Copy to Clipboard Toggle word wrap

Procedure

1. Edit the CheCluster Custom Resource on the cluster:

   $ oc edit checluster/devspaces -n openshift-devspaces

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap

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

   
     ...

   Copy to Clipboard Toggle word wrap

   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}"

   Copy to Clipboard Toggle word wrap

2. Configure the maxNumberOfWorkspacesPerUser:

   $ oc patch checluster/devspaces -n openshift-devspaces \

   1

   
   --type='merge' -p \
   '{"spec":{"devEnvironments":{"maxNumberOfWorkspacesPerUser": <kept_workspaces_limit>}}}'

   2

   Copy to Clipboard Toggle word wrap

   1

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

   2

   Your choice of the <kept_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}"

   Copy to Clipboard Toggle word wrap

2. Configure the maxNumberOfRunningWorkspacesPerUser:

   $ oc patch checluster/devspaces -n openshift-devspaces \

   1

   
   --type='merge' -p \
   '{"spec":{"devEnvironments":{"maxNumberOfRunningWorkspacesPerUser": <running_workspaces_limit>}}}'

   2

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

Procedure

1. Using NodeSelector

   OpenShift Dev Spaces uses CheCluster Custom Resource to configure nodeSelector:

   spec:
     devEnvironments:
       nodeSelector:
         key: value

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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>

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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)

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Expand

   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

   Show more
   Expand

   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	"{}"

   Show more
   Expand

   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

   Show more

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

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

   Copy to Clipboard Toggle word wrap

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 -

   Copy to Clipboard Toggle word wrap

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>

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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
                     }
                   }
                 }
               }'

   Copy to Clipboard Toggle word wrap

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

   
                       }
                     }
                   }
                 }
               }'

   Copy to Clipboard Toggle word wrap

   1

   The semicolon separated list of images

Procedure

1. Create k8s-image-puller namespace:

   oc create namespace k8s-image-puller

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   1

   The semicolon separated list of images