Administration Guide

1. A user starts a CodeReady Workspaces workspace defined by:

   • An editor (the default is Che-Theia)
   • A list of plug-ins (for example, Java and OpenShift tools)
   • A list of runtime applications
2. CodeReady Workspaces server retrieves the editor and plug-in metadata from the plug-in registry.
3. For every plug-in type, CodeReady Workspaces server starts a specific plug-in broker.

4. The CodeReady Workspaces plug-ins broker transforms the plug-in metadata into a Che Plugin definition. It executes the following steps:

   1. Downloads a plug-in and extracts its content.
   2. Processes the plug-in meta.yaml file and sends it back to CodeReady Workspaces server in the format of a Che Plugin.
5. CodeReady Workspaces server starts the editor and the plug-in sidecars.
6. The editor loads the plug-ins from the plug-in persistent volume.

1. Collects the devfile from the Section 1.5.5, “Devfile registries”, when the user is Creating a workspace from a code sample.
2. Sends the repository URL to Section 1.5.6, “CodeReady Workspaces server” and expects a devfile in return, when the user is Creating a workspace from remote devfile.
3. Reads the devfile describing the workspace.
4. Collects the additional metadata from the Section 1.5.8, “Plug-in registry”.
5. Converts the information into a Dev Workspace Custom Resource.
6. Creates the Dev Workspace Custom Resource in the user project using the OpenShift API.
7. Watches the Dev Workspace Custom Resource status.
8. Redirects the user to the running workspace IDE.

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.14-rhel-8

   Copy to Clipboard Toggle word wrap

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

   Example 3.1. File organization for a devfile

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

   Copy to Clipboard Toggle word wrap
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.14/html-single/end-user_guide/index#authoring-devfiles-version-2.adoc.

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

   Expand

   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.
   icon	Link to an .svg file that is displayed on the user dashboard.
   tags	List of tags. Tags typically include the tools included in the stack.
   globalMemoryLimit	Optional parameter: 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.

   Show more

   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

   Copy to Clipboard Toggle word wrap

5. Build a custom devfile registry image:

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

   Copy to Clipboard Toggle word wrap
   Note

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

Procedure

1. Clone the plug-ins 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.14-rhel-8

   Copy to Clipboard Toggle word wrap
2. In the ./dependencies/che-plugin-registry/ directory, edit the che-theia-plugins.yaml file.
3. Add valid content to the che-theia-plugins.yaml file, for detailed information see: https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.14/html-single/end-user_guide/index#adding-a-vs-code-extension-to-the-che-plugin-registry.adoc.

4. Build a custom plug-ins registry image:

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

   Copy to Clipboard Toggle word wrap
   Note

   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.

5. Observe the contents of ./dependencies/che-plugin-registry/v3/plugins/ present in the container after building the registry. All meta.yaml files resulting from a successful plug-ins registry build will be located here.

   ./dependencies/che-plugin-registry/v3/plugins/
   ├── <publisher>
   │   └── <plugin-name>
   │       ├── latest
   │       │   └── meta.yaml
   │       └── latest.txt

   Copy to Clipboard Toggle word wrap

   Additional resources

   • Section 3.3, “Running custom registries”.

1. To deploy the plug-in registry using the OpenShift template, run the following command:

   NAMESPACE=<namespace-name>  

   1

   
   IMAGE_NAME="my-plug-in-registry"
   IMAGE_TAG="latest"
   oc new-app -f openshift/che-plugin-registry.yml \
    -n "$\{NAMESPACE}" \
    -p IMAGE="$\{IMAGE_NAME}" \
    -p IMAGE_TAG="$\{IMAGE_TAG}" \
    -p PULL_POLICY="Always"

   Copy to Clipboard Toggle word wrap

   1

   If installed using crwctl, the default CodeReady Workspaces project is openshift-workspaces. The OperatorHub installation method deploys CodeReady Workspaces to the users current project.

2. The devfile registry has an OpenShift template in the deploy/openshift/ directory of the GitHub repository. To deploy it, run the command:

   NAMESPACE=<namespace-name>  

   1

   
   IMAGE_NAME="my-devfile-registry"
   IMAGE_TAG="latest"
   oc new-app -f openshift/che-devfile-registry.yml \
    -n "$\{NAMESPACE}" \
    -p IMAGE="$\{IMAGE_NAME}" \
    -p IMAGE_TAG="$\{IMAGE_TAG}" \
    -p PULL_POLICY="Always"

   Copy to Clipboard Toggle word wrap

   1

   If installed using crwctl, the default CodeReady Workspaces project is openshift-workspaces. The OperatorHub installation method deploys CodeReady Workspaces to the users current project.

Verification steps

1. The <plug-in> plug-in is available in the plug-in registry.

   Example 3.3. Find <plug-in> requesting the plug-in registry API.

   $ URL=$(oc  get route -l app=che,component=plugin-registry \
     -o 'custom-columns=URL:.spec.host' --no-headers)
   $ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
   $ echo ${INDEX_JSON} | jq '.[] | select(.name == "<plug-in>")'

   Copy to Clipboard Toggle word wrap

2. The <devfile> devfile is available in the devfile registry.

   Example 3.4. Find <devfile> requesting the devfile registry API.

   $ URL=$(oc  get route -l app=che,component=devfile-registry \
     -o 'custom-columns=URL:.spec.host' --no-headers)
   $ INDEX_JSON=$(curl -sSL http://${URL}/v3/plugins/index.json)
   $ echo ${INDEX_JSON} | jq '.[] | select(.name == "<devfile>")'

   Copy to Clipboard Toggle word wrap

3. CodeReady Workspaces server points to the URL of the plug-in registry.

   Example 3.5. Compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap with the URL of the plug-in registry route.

   Get the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the che ConfigMap.

   $ oc  get cm/che \
     -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" \
     --no-headers

   Copy to Clipboard Toggle word wrap

   Get the URL of the plug-in registry route.

   $ oc  get route -l app=che,component=plugin-registry \
     -o 'custom-columns=URL: .spec.host' --no-headers

   Copy to Clipboard Toggle word wrap

4. CodeReady Workspaces server points to the URL of the devfile registry.

   Example 3.6. Compare the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap with the URL of the devfile registry route.

   Get the value of the CHE_WORKSPACE_DEVFILE__REGISTRY__URL parameter in the che ConfigMap.

   $ oc  get cm/che \
     -o "custom-columns=URL:.data['CHE_WORKSPACE_DEVFILE__REGISTRY__URL']" \
     --no-headers

   Copy to Clipboard Toggle word wrap

   Get the URL of the devfile registry route.

   $ oc  get route -l app=che,component=devfile-registry \
     -o 'custom-columns=URL: .spec.host' --no-headers

   Copy to Clipboard Toggle word wrap

5. If the values do not match, update the ConfigMap and restart the CodeReady Workspaces server.

   $ oc  edit cm/codeready
   (...)
   $ oc  scale --replicas=0 deployment/codeready
   $ oc  scale --replicas=1 deployment/codeready

   Copy to Clipboard Toggle word wrap

Procedure

1. In the terminal, run the following command to get the Pods:

   $ oc get pods

   Copy to Clipboard Toggle word wrap

   Example

   $ oc get pods
   NAME            READY  STATUS   RESTARTS  AGE
   codeready-11-j4w2b    1/1    Running  0         3m

   Copy to Clipboard Toggle word wrap

2. To get the logs for a deployment, run the following command:

   $ oc logs <name-of-pod>

   Copy to Clipboard Toggle word wrap

   Example

   $ oc logs codeready-11-j4w2b

   Copy to Clipboard Toggle word wrap

Procedure

1. In the OpenShift Web Console, click Deployments.

2. In the Find by label search field, type:

   • app=che and press Enter

   • component=postgres and press Enter

     The OpenShift Web Console is searching base on those two keys and displays PostgreSQL logs.

3. Click postgres deployment to open it.

4. Click the View log link for the active PostgreSQL deployment.

   The OpenShift Web Console displays the database logs.

Procedure

1. Open the OpenShift Container Platform console.
2. From the left menu of the main OpenShift Container Platform screen, navigate to Operators → OperatorHub.
3. In the Search by keyword search bar, type Jaeger Operator.
4. Click the Jaeger Operator tile.
5. Click the Install button in the Jaeger Operator pop-up window.
6. Select the installation method: A specific project on the cluster where the CodeReady Workspaces is deployed and leave the rest in its default values.
7. Click the Subscribe button.
8. From the left menu of the main OpenShift Container Platform screen, navigate to the Operators → Installed Operators section.
9. Red Hat CodeReady Workspaces is displayed as an Installed Operator, as indicated by the InstallSucceeded status.
10. Click the Jaeger Operator name in the list of installed Operators.
11. Navigate to the Overview tab.
12. In the Conditions sections at the bottom of the page, wait for this message: install strategy completed with no errors.
13. Jaeger Operator and additional Elasticsearch Operator is installed.
14. Navigate to the Operators → Installed Operators section.
15. Click Jaeger Operator in the list of installed Operators.
16. The Jaeger Cluster page is displayed.
17. In the lower left corner of the window, click Create Instance
18. Click Save.
19. OpenShift creates the Jaeger cluster jaeger-all-in-one-inmemory.
20. Follow the steps in Enabling metrics collection to finish the procedure.

Procedure

1. In the CodeReady Workspaces installation project of the OpenShift Container Platform cluster, use the oc client to create a new application for the Jaeger deployment.

   $ oc new-app -f / ${CHE_LOCAL_GIT_REPO}/deploy/openshift/templates/jaeger-all-in-one-template.yml:
   
   --> Deploying template "<project_name>/jaeger-template-all-in-one" for "/home/user/crw-projects/crw/deploy/openshift/templates/jaeger-all-in-one-template.yml" to project <project_name>
   
        Jaeger (all-in-one)
        ---------
        Jaeger Distributed Tracing Server (all-in-one)
   
        * With parameters:
           * Jaeger Service Name=jaeger
           * Image version=latest
           * Jaeger Zipkin Service Name=zipkin
   
   --> Creating resources ...
       deployment.apps "jaeger" created
       service "jaeger-query" created
       service "jaeger-collector" created
       service "jaeger-agent" created
       service "zipkin" created
       route.route.openshift.io "jaeger-query" created
   --> Success
       Access your application using the route: 'jaeger-query-<project_name>.apps.ci-ln-whx0352-d5d6b.origin-ci-int-aws.dev.rhcloud.com'
       Run 'oc status' to view your app.

   Copy to Clipboard Toggle word wrap
2. Using the Workloads → Deployments from the left menu of main OpenShift Container Platform screen, monitor the Jaeger deployment until it finishes successfully.
3. Select Networking → Routes from the left menu of the main OpenShift Container Platform screen, and click the URL link to access the Jaeger dashboard.
4. Follow the steps in Enabling metrics collection to finish the procedure.

1. To create a backup snapshot and send it to a pre-configured backup server:

   $ crwctl server:backup --repository-url=<repository-url> --repository-password=<repository-password>

   Copy to Clipboard Toggle word wrap
   • You can create other backups to the same backup server using the server:backup command with no arguments.
   • Using the server:backup command with no arguments for the first time will configure and use an internal backup server.

1. Create a CheClusterBackup object to create a new backup:

   apiVersion: org.eclipse.che/v1
   kind: CheClusterBackup
   metadata:
     name: CodeReady Workspaces-backup
   spec:
     backupServerConfigRef: backup-server-configuration 

   1

   Copy to Clipboard Toggle word wrap

1. Create a new object of CheClusterRestore to recover a CodeReady Workspaces installation from a backup:

   apiVersion: org.eclipse.che/v1
   kind: CheClusterRestore
   metadata:
     name: CodeReady Workspaces-restore
   spec:
     backupServerConfigRef: backup-server-configuration 

   1

   
     snapshotId: ba92c7e0                               

   2

   Copy to Clipboard Toggle word wrap

Verification

1. Verify backup process state:

   1. Read the status section of the CheClusterBackup object to check the backup process:

      status:
        message: 'Backup is in progress. Start time: <timestamp>' 

      1

      
        stage: Collecting CodeReady Workspaces installation data          

      2

      
        state: InProgress                                         

      3

      
        snapshotId: ba92c7e0                                      

      4

      Copy to Clipboard Toggle word wrap

      1

      Displays the overall state or error message.

      2

      Current phase of the backup process in a human-readable format.

      3

      Backup process state. One of InProgress, Succeeded, or Failed.

      4

      ID of the created backup snapshot. The field appears only when state is Succeeded.

2. Verify recovery process state

   1. Read the status section of the CheClusterRestore object to check the recovery process:

      status:
        message: 'Restore is in progress. Start time: <timestamp>' 

      1

      
        stage: Restoring CodeReady Workspaces related cluster objects      

      2

      
        state: InProgress                                          

      3

      Copy to Clipboard Toggle word wrap

      1

      Overall state or error message.

      2

      Current phase of the recovery process in a human-readable format.

      3

      Recovery process state. One of InProgress, Succeeded, or Failed.

Procedure

1. Define the values of the following placeholders:

   • <database-user> is the CodeReady Workspaces server database user name
   • <database-password> is the CodeReady Workspaces server database password
   • <database> is the CodeReady Workspaces server database name

2. Use the following SQL script to create a user and a database for the CodeReady Workspaces server to make workspace metadata persistent:

   CREATE USER <database-user> WITH PASSWORD '<database-password>'
   CREATE DATABASE <database>
   GRANT ALL PRIVILEGES ON DATABASE <database> TO <database-user>
   ALTER USER <database-user> WITH SUPERUSER

   Copy to Clipboard Toggle word wrap

3. Define the value of the following placeholder:

   • <identity-database-password> is the RH-SSO database password

4. Use the following SQL script to create a database for the RH-SSO back end to make the user information persistent:

   CREATE USER keycloak WITH PASSWORD '<identity-database-password>'
   CREATE DATABASE keycloak
   GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak

   Copy to Clipboard Toggle word wrap

Procedure

1. Pre-create a project for CodeReady Workspaces:

   $ oc create namespace openshift-workspaces

   Copy to Clipboard Toggle word wrap

2. Create a secret to store CodeReady Workspaces server database credentials:

   $ oc create secret generic <server-database-credentials> \ 

   1

   
   --from-literal=user=<database-user> \ 

   2

   
   --from-literal=password=<database-password> \ 

   3

   
   -n openshift-workspaces

   Copy to Clipboard Toggle word wrap

   1

   Secret name to store CodeReady Workspaces server database credentials

   2

   CodeReady Workspaces server database username

   3

   CodeReady Workspaces server database password

3. Add the required labels to the CodeReady Workspaces server database credentials secret:

   $ oc label secret <server-database-credentials> \ 

   1

   
    app.kubernetes.io/part-of=che.eclipse.org -n openshift-workspaces

   Copy to Clipboard Toggle word wrap

   1

   Secret name to store CodeReady Workspaces server database credentials

4. Create a secret to store RH-SSO database credentials:

   $ oc create secret generic <identity-database-credentials> \ 

   1

   
   --from-literal=password=<identity-database-password> \ 

   2

   
   -n openshift-workspaces

   Copy to Clipboard Toggle word wrap

   1

   Secret name to store RH-SSO database credentials

   2

   RH-SSO database password

5. Add the required labels to the RH-SSO database credentials secret:

   $ oc label secret <identity-database-credentials> \ 

   1

   
   app.kubernetes.io/part-of=che.eclipse.org -n openshift-workspaces

   Copy to Clipboard Toggle word wrap

   1

   Secret name to store RH-SSO database credentials

6. Deploy Red Hat CodeReady Workspaces by executing the crwctl command with applying a patch. For example:

   $ crwctl server:deploy --che-operator-cr-patch-yaml=patch.yaml ...

   Copy to Clipboard Toggle word wrap