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.5/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.

      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	128 MiB
      cheEditor	che.workspace.sidecar.default_memory_limit_mb	128 MiB	128 MiB
      kubernetes, openshift, dockerimage	che.workspace.default_memory_limit_mb, che.workspace.default_memory_request_mb	1 Gi	512 MiB
      JWT Proxy	che.server.secure_exposer.jwtproxy.memory_limit	128 MiB	128 MiB

   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

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

         Memory limit	512 MiB
         Memory request	256 MiB

         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

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

         CPU limit	2 cores
         CPU request	0.5 cores

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

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. Clone the devfile registry repository and check out the version to deploy:

   $ git clone git@github.com:redhat-developer/codeready-workspaces.git
   $ cd codeready-workspaces
   $ git checkout crw-2.5-rhel-8

2. In the ./dependencies/che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.

   File organization for a devfile

   ./dependencies/che-devfile-registry/devfiles/
   └── <devfile-name>
       ├── devfile.yaml
       └── meta.yaml

3. Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.5/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

4. Ensure that the meta.yaml file conforms to the following structure:

   Table 3.1. Parameters for a devfile meta.yaml

   Attribute	Description
   description	Description as it appears on the user dashboard.
   displayName	Name as it appears on the user dashboard.
   globalMemoryLimit	The sum of the expected memory consumed by all the components launched by the devfile. This number will be visible on the user dashboard. It is informative and is not taken into account by the CodeReady Workspaces server.
   icon	Link to an .svg file that is displayed on the user dashboard.
   tags	List of tags. Tags usually include the tools included in the stack.

   Example 3.1. Example devfile meta.yaml

   displayName: Rust
   description: Rust Stack with Rust 1.39
   tags: ["Rust"]
   icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
   globalMemoryLimit: 1686Mi

5. In the ./dependencies/che-devfile-registry/devfiles/ directory, create a subdirectory <devfile-name>/ and add the devfile.yaml and meta.yaml files.

   File organization for a devfile

   ./dependencies/che-devfile-registry/devfiles/
   └── <devfile-name>
       ├── devfile.yaml
       └── meta.yaml

6. Add valid content in the devfile.yaml file. For a detailed description of the devfile format, see https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.5/html-single/end-user_guide/index#making-a-workspace-portable-using-a-devfile_crw.

7. Ensure that the meta.yaml file conforms to the following structure:

   Table 3.2. Parameters for a devfile meta.yaml

   Attribute	Description
   description	Description as it appears on the user dashboard.
   displayName	Name as it appears on the user dashboard.
   globalMemoryLimit	The sum of the expected memory consumed by all the components launched by the devfile. This number will be visible on the user dashboard. It is informative and is not taken into account by the CodeReady Workspaces server.
   icon	Link to an .svg file that is displayed on the user dashboard.
   tags	List of tags. Tags usually include the tools included in the stack.

   Example 3.2. Example devfile meta.yaml

   displayName: Rust
   description: Rust Stack with Rust 1.39
   tags: ["Rust"]
   icon: https://www.eclipse.org/che/images/logo-eclipseche.svg
   globalMemoryLimit: 1686Mi

8. Build a custom devfile registry image:

   $ cd dependencies/che-devfile-registry
   $ ./build.sh --organization <my-org> \
              --registry <my-registry> \
              --tag <my-tag> \
              --latest-only
   
   $ cd ../../dependencies/che-devfile-registry
   $ ./build.sh --organization <my-org> \
              --registry <my-registry> \
              --tag <my-tag> \
              --latest-only

   Tip

   To display full options for the build.sh script, use the --help parameter.

   To include the plug-in binaries in the registry image, add the --offline parameter.

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>

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

   $ oc get pods

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

   Example 5.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

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

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

   Example 5.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"

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'

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

   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 7.1. Using Jaeger UI to trace CodeReady Workspaces

   

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 7.2. Expanded tracing tree

   

1. Clone the Kubernetes Image Puller repository:

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

2. Create a new OpenShift project to deploy the puller into:

   $ oc new-project k8s-image-puller

3. Process and apply the templates to deploy the puller:

   In CodeReady Workspaces you must use custom values to deploy the image puller. To set custom values, add to the oc process an option: -p <parameterName>=<value>:

   $ oc process -f deploy/openshift/serviceaccount.yaml \
       | oc apply -f -
   $ oc process -f deploy/openshift/configmap.yaml \
       -p IMAGES='plugin-java8-rhel8=registry.redhat.io/codeready-workspaces/plugin-java8-rhel8:2.5;\
       theia-rhel8=registry.redhat.io/codeready-workspaces/theia-rhel8:2.5;\
       stacks-golang-rhel8=registry.redhat.io/codeready-workspaces/stacks-golang-rhel8:2.5;\
       plugin-java11-rhel8=registry.redhat.io/codeready-workspaces/plugin-java11-rhel8:2.5;\
       theia-endpoint-rhel8=registry.redhat.io/codeready-workspaces/theia-rhel8:2.5;\
       pluginbroker-metadata-rhel8=registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8:2.5;\
       pluginbroker-artifacts-rhel8=registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8:2.5;' \
       | oc apply -f -
   $ oc process -f deploy/openshift/app.yaml \
       -p IMAGE=registry.redhat.io/codeready-workspaces/imagepuller-rhel8 \
       -p IMAGE_TAG='2.5' \
       | oc apply -f -

1. Confirm that a new deployment, kubernetes-image-puller, and a DaemonSet (named based on the value of the DAEMONSET_NAME parameter) exist. The DaemonSet needs to have a Pod for each node in the cluster:

   $ oc get deployment,daemonset,pod --namespace k8s-image-puller
   deployment.extensions/kubernetes-image-puller   1/1       1            1           2m19s
   
   NAME                                           DESIRED   CURRENT   READY     UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
   daemonset.extensions/kubernetes-image-puller   1         1         1         1            1           <none>          2m10s
   
   NAME                                           READY     STATUS    RESTARTS   AGE
   pod/kubernetes-image-puller-5495f46497-mkd4p   1/1       Running   0          2m18s
   pod/kubernetes-image-puller-n8bmf              3/3       Running   0          2m10s

2. Check that the ConfigMap named k8s-image-puller has the values you specified in your parameter substitution, or that they contain the default values:

   $ oc get configmap k8s-image-puller --output yaml
   apiVersion: v1
   data:
     CACHING_INTERVAL_HOURS: "1"
     CACHING_MEMORY_LIMIT: 20Mi
     CACHING_MEMORY_REQUEST: 10Mi
     DAEMONSET_NAME: kubernetes-image-puller
     IMAGES: |
       theia-rhel8=registry.redhat.io/codeready-workspaces/theia-rhel8:{prod-ver};
       theia-endpoint-rhel8=registry.redhat.io/codeready-workspaces/theia-rhel8:{prod-ver};
       pluginbroker-metadata-rhel8=registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8:{prod-ver};
       pluginbroker-artifacts-rhel8=registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8:{prod-ver};
       plugin-java8-rhel8=registry.redhat.io/codeready-workspaces/plugin-java8-rhel8:{prod-ver};
       plugin-java11-rhel8=registry.redhat.io/codeready-workspaces/plugin-java11-rhel8:{prod-ver};
       stacks-golang-rhel8=registry.redhat.io/codeready-workspaces/stacks-golang-rhel8:{prod-ver};
     NAMESPACE: k8s-image-puller
     NODE_SELECTOR: '{}'
   kind: ConfigMap
   metadata:
     annotations:
       kubectl.kubernetes.io/last-applied-configuration: |
         {"apiVersion":"v1","data":{"CACHING_INTERVAL_HOURS":"1","CACHING_MEMORY_LIMIT":"20Mi","CACHING_MEMORY_REQUEST":"10Mi","DAEMONSET_NAME":"kubernetes-image-puller","IMAGES":"theia-rhel8=registry.redhat.io/codeready-workspaces/theia-rhel8:{prod-ver}; theia-endpoint-rhel8=registry.redhat.io/codeready-workspaces/theia-rhel8:{prod-ver}; pluginbroker-metadata-rhel8=registry.redhat.io/codeready-workspaces/pluginbroker-metadata-rhel8:{prod-ver}; pluginbroker-artifacts-rhel8=registry.redhat.io/codeready-workspaces/pluginbroker-artifacts-rhel8:{prod-ver}; plugin-java8-rhel8=registry.redhat.io/codeready-workspaces/plugin-java8-rhel8:{prod-ver}; plugin-java11-rhel8=registry.redhat.io/codeready-workspaces/plugin-java11-rhel8:{prod-ver}; stacks-golang-rhel8=registry.redhat.io/codeready-workspaces/stacks-golang-rhel8:{prod-ver};\n","NAMESPACE":"k8s-image-puller","NODE_SELECTOR":"{}"},"kind":"ConfigMap","metadata":{"annotations":{},"name":"k8s-image-puller","namespace":"k8s-image-puller"},"type":"Opaque"}
     creationTimestamp: 2020-02-17T22:40:13Z
     name: k8s-image-puller
     namespace: k8s-image-puller
     resourceVersion: "72250"
     selfLink: /api/v1/namespaces/k8s-image-puller/configmaps/k8s-image-puller
     uid: 76430ed6-51d6-11ea-9c19-52fdfc072182