Administration Guide

Procedure

1. Identify the workspace components explicitly specified in the components section of the https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.7/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

2. Identify the implicit workspace components:

   1. CodeReady Workspaces implicitly loads the default cheEditor: che-theia, and the chePlugin that allows commands execution: che-machine-exec-plugin. To change the default editor, add a cheEditor component section in the devfile.
   2. When CodeReady Workspaces is running in multiuser mode, it loads the JWT Proxy component. The JWT Proxy is responsible for the authentication and authorization of the external communications of the workspace components.

3. Calculate the requirements for each component:

   1. Default values:

      The following table presents the default requirements for all workspace components. It also presents the corresponding CodeReady Workspaces server property to modify the defaults cluster-wide.

      Expand

      Table 2.2. Default requirements of workspace components by type

      Component types	CodeReady Workspaces server property	Default memory limit	Default memory request
      chePlugin	che.workspace.sidecar.default_memory_limit_mb	128 MiB	64 MiB
      cheEditor	che.workspace.sidecar.default_memory_limit_mb	128 MiB	64 MiB
      kubernetes, openshift, dockerimage	che.workspace.default_memory_limit_mb, che.workspace.default_memory_request_mb	1 Gi	200 MiB
      JWT Proxy	che.server.secure_exposer.jwtproxy.memory_limit, che.server.secure_exposer.jwtproxy.memory_request	128 MiB	15 MiB

      Show more

   2. Custom requirements for chePlugins and cheEditors components:

      1. Custom memory limit and request:

         If present, the memoryLimit and memoryRequest attributes of the containers section of the meta.yaml file define the memory limit of the chePlugins or cheEditors components. CodeReady Workspaces automatically sets the memory request to match the memory limit in case it is not specified explicitly.

         Example 2.1. The chePlugin che-incubator/typescript/latest

         meta.yaml spec section:

         spec:
          containers:
            - image: docker.io/eclipse/che-remote-plugin-node:next
              name: vscode-typescript
              memoryLimit: 512Mi
              memoryRequest: 256Mi

         Copy to Clipboard Toggle word wrap

         It results in a container with the following memory limit and request:

         Expand

         Memory limit	512 MiB
         Memory request	256 MiB

         Show more
         Note

         For IBM Power Systems (ppc64le), the memory limit for some plugins has been increased by up to 1.5G to allow pods sufficient RAM to run. For example, on IBM Power Systems (ppc64le), the Theia editor pod requires 2G; the OpenShift connector pod requires 2.5G. For AMD64 and Intel 64 (x86_64) and IBM Z (s390x), memory requirements remain lower at 512M and 1500M respectively. However, some devfiles may still be configured to set the lower limit valid for AMD64 and Intel 64 (x86_64) and IBM Z (s390x), so to work around this, edit devfiles for workspaces that are crashing to increase the default memoryLimit by at least 1 - 1.5 GB.

         Note

         How to find the meta.yaml file of chePlugin

         Community plug-ins are available in the che-plugin-registry GitHub repository in folder v3/plugins/${organization}/${name}/${version}/.

         For non-community or customized plug-ins, the meta.yaml files are available on the local OpenShift cluster at ${pluginRegistryEndpoint}/v3/plugins/${organization}/${name}/${version}/meta.yaml.

      2. Custom CPU limit and request:

         CodeReady Workspaces does not set CPU limits and requests by default. However, it is possible to configure CPU limits for the chePlugin and cheEditor types in the meta.yaml file or in the devfile in the same way as it done for memory limits.

         Example 2.2. The chePlugin che-incubator/typescript/latest

         meta.yaml spec section:

         spec:
          containers:
            - image: docker.io/eclipse/che-remote-plugin-node:next
              name: vscode-typescript
              cpuLimit: 2000m
              cpuRequest: 500m

         Copy to Clipboard Toggle word wrap

         It results in a container with the following CPU limit and request:

         Expand

         CPU limit	2 cores
         CPU request	0.5 cores

         Show more

1. Custom requirements for dockerimage components

   If present, the memoryLimit and memoryRequest attributes of the devfile define the memory limit of a dockerimage container. CodeReady Workspaces automatically sets the memory request to match the memory limit in case it is not specified explicitly.

     - alias: maven
       type: dockerimage
       image: eclipse/maven-jdk8:latest
       memoryLimit: 1536M

   Copy to Clipboard Toggle word wrap

2. Custom requirements for kubernetes or openshift components:

   The referenced manifest may define the memory requirements and limits.

   1. Add all requirements previously calculated.

Procedure

1. In the left panel of the OpenShift web console, click the Home → Events.
2. To view the list of all events for a particular project, select the project from the list.
3. The details of the events for the current project are displayed.

Procedure

1. Run the following commands to select the crw project:

   $ oc project <project_name>

   Copy to Clipboard Toggle word wrap

2. Run the following commands to get the name and status of the Pods running in the selected project:

   $ oc get pods

   Copy to Clipboard Toggle word wrap

3. Check that the status of all the Pods is Running.

   Example 4.1. Pods with status Running

   NAME                            READY     STATUS    RESTARTS   AGE
   codeready-8495f4946b-jrzdc            0/1       Running   0          86s
   codeready-operator-578765d954-99szc   1/1       Running   0          42m
   keycloak-74fbfb9654-g9vp5       1/1       Running   0          4m32s
   postgres-5d579c6847-w6wx5       1/1       Running   0          5m14s

   Copy to Clipboard Toggle word wrap

4. To see the state of the CodeReady Workspaces cluster deployment, run:

   $ oc logs --tail=10 -f `(oc get pods -o name | grep operator)`

   Copy to Clipboard Toggle word wrap

   Example 4.2. Logs of the Operator:

   time="2019-07-12T09:48:29Z" level=info msg="Exec successfully completed"
   time="2019-07-12T09:48:29Z" level=info msg="Updating eclipse-che CR with status: provisioned with OpenShift identity provider: true"
   time="2019-07-12T09:48:29Z" level=info msg="Custom resource eclipse-che updated"
   time="2019-07-12T09:48:29Z" level=info msg="Creating a new object: ConfigMap, name: che"
   time="2019-07-12T09:48:29Z" level=info msg="Creating a new object: ConfigMap, name: custom"
   time="2019-07-12T09:48:29Z" level=info msg="Creating a new object: Deployment, name: che"
   time="2019-07-12T09:48:30Z" level=info msg="Updating eclipse-che CR with status: CodeReady Workspaces API: Unavailable"
   time="2019-07-12T09:48:30Z" level=info msg="Custom resource eclipse-che updated"
   time="2019-07-12T09:48:30Z" level=info msg="Waiting for deployment che. Default timeout: 420 seconds"

   Copy to Clipboard Toggle word wrap

1. Start a CodeReady Workspaces workspace.
2. From the main OpenShift Container Platform screen, go to Workload → Pods.
3. Use the OpenShift terminal console located in the Pod’s Terminal tab

Procedure

1. Set the CHE_METRICS_ENABLED=true environment variable, which will expose the 8087 port as a service on the che-master host.

1. In the yaml source code of the CodeReady Workspaces deployment, add the following configuration variables under spec.server.customCheProperties.

   customCheProperties:
         CHE_TRACING_ENABLED: 'true'
         JAEGER_SAMPLER_TYPE: const
         DEFAULT_JAEGER_REPORTER_MAX_QUEUE_SIZE: '10000'
         JAEGER_SERVICE_NAME: che-server
         JAEGER_ENDPOINT: 'http://jaeger-collector:14268/api/traces'
         JAEGER_SAMPLER_MANAGER_HOST_PORT: 'jaeger:5778'
         JAEGER_SAMPLER_PARAM: '1'

   Copy to Clipboard Toggle word wrap

2. Edit the JAEGER_ENDPOINT value to match the name of the Jaeger collector service in your deployment.

   From the left menu of the main OpenShift Container Platform screen, obtain the value of JAEGER_ENDPOINT by navigation to Networking → Services. Alternatively, execute the following oc command:

   $ oc get services

   Copy to Clipboard Toggle word wrap

   The requested value is included in the service name that contains the collector string.

1. In the Search panel on the left, filter spans by the operation name (span name), tags, or time and duration.

   Figure 6.1. Using Jaeger UI to trace CodeReady Workspaces

   

   View larger image

   

2. Select the trace to expand it and show the tree of nested spans and additional information about the highlighted span, such as tags or durations.

   Figure 6.2. Expanded tracing tree

   

   View larger image

   

Procedure

1. Get the list of relevant container images.

   Example 8.1. Getting the list of all relevant images for CodeReady Workspaces

   $ curl -sSLo- https://raw.githubusercontent.com/redhat-developer/codeready-workspaces-operator/crw-2.7-rhel-8/manifests/codeready-workspaces.csv.yaml | \
     yq -r '.spec.relatedImages[]'

   Copy to Clipboard Toggle word wrap

2. Exclude from the list the container images not containing the sleep command.

   Example 8.2. Images incompatibles with {image-puller-short}, missing the sleep command

   • FROM scratch images.
   • che-machine-exec
3. Exclude from the list the container images mounting volumes in Dockerfile.

Procedure

1. To define 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.

2. To define 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.

Procedure

1. Edit the CheCluster Custom Resource and set .spec.imagePuller.enable to true

   Example 8.3. Enabling Image Puller in the CheCluster Custom Resource

   apiVersion: org.eclipse.che/v1
   kind: CheCluster
   metadata:
     name: codeready-workspaces
   spec:
     # ...
     imagePuller:
       enable: true

   Copy to Clipboard Toggle word wrap
   Uninstalling Image Puller using CodeReady Workspaces Operator
   • Edit the CheCluster Custom Resource and set .spec.imagePuller.enable to false.

2. Edit the CheCluster Custom Resource and set the .spec.imagePuller.spec to configure the optional Image Puller parameters for the CodeReady Workspaces Operator.

   Example 8.4. Configuring Image Puller in the CheCluster Custom Resource

   apiVersion: org.eclipse.che/v1
   kind: CheCluster
   metadata:
     name: codeready-workspaces
   spec:
     ...
     imagePuller:
       enable: true
       spec:
           configMapName: <kubernetes-image-puller>
           daemonsetName: <kubernetes-image-puller>
           deploymentName: <kubernetes-image-puller>
           images: <{image-puller-images}>

   Copy to Clipboard Toggle word wrap

Verification steps

1. OpenShift creates a {image-puller-operator-id} Subscription.

2. The eclipse-che namespace contains a community supported Kubernetes Image Puller Operator ClusterServiceVersion:

   $ oc get clusterserviceversions

   Copy to Clipboard Toggle word wrap

3. The eclipse-che namespace contains these deployments: kubernetes-image-puller and {image-puller-deployment-id}.

   $ oc get deployments

   Copy to Clipboard Toggle word wrap

4. The community supported Kubernetes Image Puller Operator creates a KubernetesImagePuller Custom Resource:

   $ oc get kubernetesimagepullers

   Copy to Clipboard Toggle word wrap

Procedure

1. To create an OpenShift project <kubernetes-image-puller> to host the Image Puller, open the OpenShift web console, navigate to the Home → Projects section and click Create Project.

2. Specify the project details:

   • Name: <kubernetes-image-puller>
   • Display Name: <Image Puller>
   • Description: <Kubernetes Image Puller>
3. Navigate to Operators → OperatorHub.
4. Use the Filter by keyword box to search for community supported Kubernetes Image Puller Operator. Click the community supported Kubernetes Image Puller Operator.
5. Read the description of the Operator. Click Continue → Install.
6. Select A specific project on the cluster for the Installation Mode. In the drop-down find the OpenShift project <kubernetes-image-puller>. Click Subscribe.
7. Wait for the community supported Kubernetes Image Puller Operator to install. Click the KubernetesImagePuller → Create instance.
8. In a redirected window with a YAML editor, make modifications to the KubernetesImagePuller Custom Resource and click Create.
9. Navigate to the Workloads and Pods menu in the <kubernetes-image-puller> OpenShift project. Verify that the Image Puller is available.

Procedure

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

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

   Expand

   Table 8.2. 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/codeready-workspaces/imagepuller-rhel8:2.7
   IMAGE_TAG	The image tag to pull	latest
   SERVICEACCOUNT_NAME	The name of the ServiceAccount created and used by the deployment	{image-puller-serviceaccount-name}

   Show more
   Expand

   Table 8.3. 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	{image-puller-images}
   NODE_SELECTOR	The value of NODE_SELECTOR in the ConfigMap	"{}"

   Show more
   Expand

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

   Value	Usage	Default
   SERVICEACCOUNT_NAME	The name of the ServiceAccount created and used by the deployment	{image-puller-serviceaccount-name}

   Show more

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

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

   Copy to Clipboard Toggle word wrap

4. 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 <kubernetes-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