Administration Guide

1. To deploy the plug-in registry using the Helm chart, run the following command:

   NAMESPACE=<namespace-name>     

   1

   
   DOMAIN=<kubernetes-cluster-domain> 

   2

   
   IMAGE="my-plug-in-registry"
   helm upgrade --install che-plugin-registry \
    --debug \
    --namespace $\{NAMESPACE} \
    --set global.ingressDomain=$\{DOMAIN} \
    --set chePluginRegistryImage=$\{IMAGE} \
    --set chePluginRegistryImagePullPolicy="IfNotPresent" \
    ./kubernetes/che-plugin-registry/

   Copy to Clipboard Toggle word wrap

   1

   The default CodeReady Workspaces namespace is workspaces.

   2

   On Minikube, use $(minikube ip).mycluster.mycompany.com

2. The devfile registry also has a Helm chart in the deploy/kubernetes/che-devfile-registry/ directory of the GitHub repository. To deploy it, run the command:

   NAMESPACE=<namespace-name>     

   1

   
   DOMAIN=<kubernetes-cluster-domain> 

   2

   
   IMAGE="my-devfile-registry"
   helm upgrade --install che-devfile-registry \
    --debug \
    --namespace $\{NAMESPACE} \
    --set global.ingressDomain=$\{DOMAIN} \
    --set cheDevfileRegistryImage=$\{IMAGE} \
    --set cheDevfileRegistryImagePullPolicy="IfNotPresent" \
    ./deploy/kubernetes/che-devfile-registry/

   Copy to Clipboard Toggle word wrap

   1

   The default CodeReady Workspaces namespace is workspaces.

   2

   On Minikube, use $(minikube ip).mycluster.mycompany.com

3. The Helm chart creates a pod, a service, and an Ingress. To get them, use app=che-plugin-registry (or app=che-plugin-registry for the devfile registry).

   $ oc get -o custom-columns=TYPE:.kind,NAME:.metadata.name \
     -l app=che-plugin-registry pod,svc,ingress
   TYPE      NAME
   Pod       che-plugin-registry-5c7cd8d5c9-zlqlz
   Service   che-plugin-registry
   Ingress   che-plugin-registry

   Copy to Clipboard Toggle word wrap

4. To verify that the new plug-in is correctly published to the plug-in registry, make a request to the registry path /v3/plugins/index.json (or /devfiles/index.json for the devfile registry).

   $ URL=$(oc get -o 'custom-columns=URL:.spec.rules[0].host' \
     -l app=che-plugin-registry ingress --no-headers)
   $ INDEX_JSON=$(curl -sSL http://$\{URL}/v3/plugins/index.json)
   $ echo $\{INDEX_JSON} | grep -A 4 -B 5 "\"name\":\"my-plug-in\""
   ,\{
    "id": "my-org/my-plug-in/1.0.0",
    "displayName":"This is my first {prod-short} plug-in",
    "version":"1.0.0",
    "type":"VS Code extension",
    "name":"my-plug-in",
    "description":"This plugins shows that we are able to add plugins to the registry...",
    "publisher":"my-org",
    "links": \{"self":"/v3/plugins/my-org/my-plug-in/1.0.0" }
   }
   --
   --
   ,\{
    "id": "my-org/my-plug-in/latest",
    "displayName":"This is my first {prod-short} plug-in",
    "version":"latest",
    "type":"VS Code extension",
    "name":"my-plug-in",
    "description":"This plugins shows that we are able to add plugins to the registry...",
    "publisher":"my-org",
    "links": \{"self":"/v3/plugins/my-org/my-plug-in/latest" }
   }

   Copy to Clipboard Toggle word wrap

5. Verify that the CodeReady Workspaces server points to the URL of the registry. To do this, compare the value of the CHE_WORKSPACE_PLUGIN__REGISTRY__URL parameter in the workspaces ConfigMap (or CHE_WORKSPACE_DEVFILE__REGISTRY__URL for the devfile registry):

   $ oc get \
     -o "custom-columns=URL:.data['CHE_WORKSPACE_PLUGIN__REGISTRY__URL']" \
     --no-headers cm/che
   URL
   http://che-plugin-registry-che.192.168.99.100.mycluster.mycompany.com/v3

   Copy to Clipboard Toggle word wrap

   with the URL of the Ingress:

   $ oc get -o 'custom-columns=URL:.spec.rules[0].host' \
     -l app=che-plugin-registry ingress --no-headers
   che-plugin-registry-che.192.168.99.100.mycluster.mycompany.com

   Copy to Clipboard Toggle word wrap

6. If they do not match, update the ConfigMap and restart the CodeReady Workspaces server.

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

   Copy to Clipboard Toggle word wrap

   When the new registries are deployed and the CodeReady Workspaces server is configured to use them, the new plug-ins are available in the Plugin view of a workspace.

   

   View larger image

   

   The new stacks are displayed in the New Workspace tab of the user dashboard.

   

   View larger image

   

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="IfNotPresent"

   Copy to Clipboard Toggle word wrap

   1

   The default CodeReady Workspaces namespace is workspaces.

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="IfNotPresent"

   Copy to Clipboard Toggle word wrap

   1

   The default CodeReady Workspaces namespace is workspaces.

3. Check if the registries are deployed successfully on OpenShift. The steps to check are similar to the OpenShift steps. For details, see the Section 1.1.3.1, “Deploying registries in OpenShift” section. The only difference is that, on OpenShift, Ingresses are replaced with routes.

Procedure

1. In the OpenShift Web Console, click Deployments.
2. In the Filter by label search field, type keycloak to see the Keycloak logs.
3. In the Deployment Configs section, click on the keycloak link to open it.
4. In the History tab, click the View log link for the active Keycloak deployment.
5. The Keycloak logs are displayed.

6. To view the Keycloak IDE server diagnostics or error related messages, search for keycloak in the log.

   

   View larger image

   

Procedure

1. Click on Menu > More Tools > Developer Tools.

2. Click on the Console tab.

   

   View larger image

   

Procedure

1. Run the following command to get the list of all the pods:

   $ oc get pods

   Copy to Clipboard Toggle word wrap
   Example

   $ oc get pods
   NAME                                              READY  STATUS   RESTARTS  AGE
   che-9-xz6g8                                       1/1    Running  1         15h
   workspace0zqb2ew3py4srthh.go-cli-549cdcf69-9n4w2  4/4    Running  0         1h

   Copy to Clipboard Toggle word wrap

2. Run the following command to get the list of all the containers in the particular pod:

   $ oc get pods <name-of-pod> -o

   Copy to Clipboard Toggle word wrap
   Example

   $ oc get pods workspace0zqb2ew3py4srthh.go-cli-549cdcf69-9n4w2 -o
   jsonpath='\{.spec.containers[*].name}'
   > go-cli che-machine-exechr7 theia-idexzb vscode-gox3r

   Copy to Clipboard Toggle word wrap

3. Get logs from the theia/ide container:

   $ oc logs -f <name-of-container> -c

   Copy to Clipboard Toggle word wrap
   Example

   $ oc logs -f workspace0zqb2ew3py4srthh.go-cli-549cdcf69-9n4w2 -c
   theia-idexzb

   Copy to Clipboard Toggle word wrap

1. In the OpenShift Web Console, click Overview.

2. Search for the particular deployment, click on the context menu on the right side of the deployment, and click View Logs.

   

   View larger image

   

3. In the drop-down list, click theia-ide.

   

   View larger image

   

Procedure

1. In the OpenShift web console, click Applications → Pods to see a list of all the active workspaces.
2. Click on the name of the running pod where the workspace is running. The pod screen contains the list of all containers with additional information.

3. Choose a container and click on the container name.

   Tip

   The most important logs are the theia-ide container and the plug-ins container logs.

4. On the container screen, navigate to the Logs section.

   Example

   The following is an output log of the sidecar container running the Java plug-in.

   

   View larger image

   

Procedure

1. Click File → Settings and then open Preferences.
2. Expand the Debug section in the Preferences view.
3. Set the trace preference value to true (default is false).
4. All the communication events are now logged.

5. To watch these events, click View → Output and select Debug adapters from the drop-down list at the top-right corner of the Output view.

   

   View larger image

   

Procedure

1. In the launch.json file, add the "log": true attribute to the selected launch configuration.
2. Start the debug session.

3. The diagnostic messages are printed into the Debug Console view along with the application output.

   

   View larger image

   

1. Request the OpenID settings service where clients can find all the necessary URLs and properties of the OpenId provider, such as jwks.endpoint, token.endpoint, logout.endpoint, realm.name, or client_id returned in the JSON format.

2. The service URL is <che.host>:<che.port>/api/keycloak/settings, and it is only available in the CodeReady Workspaces multi-user mode. The presence of the service in the URL confirms that the authentication is enabled in the current deployment.

   Example output:

   {
       "che.keycloak.token.endpoint": "http://172.19.20.9:5050/auth/realms/che/protocol/openid-connect/token",
       "che.keycloak.profile.endpoint": "http://172.19.20.9:5050/auth/realms/che/account",
       "che.keycloak.client_id": "che-public",
       "che.keycloak.auth_server_url": "http://172.19.20.9:5050/auth",
       "che.keycloak.password.endpoint": "http://172.19.20.9:5050/auth/realms/che/account/password",
       "che.keycloak.logout.endpoint": "http://172.19.20.9:5050/auth/realms/che/protocol/openid-connect/logout",
       "che.keycloak.realm": "che"
   }

   Copy to Clipboard Toggle word wrap

   The service allows downloading the JavaScript client library to interact with the provider using the <che.host>:<che.port>/api/keycloak/OIDCKeycloak.js URL.

3. Redirect the user to the appropriate provider’s login page with all the necessary parameters, including client_id and the return redirection path. This can be done with any client library (JS or Java).
4. When the user is logged in to the provider, the client side-code is obtained, and the JWT token has validated the token, the creation of the subject begins.

1. Authentication: The token is extracted from the Authorization header or from the token query parameter and is parsed using the public key retrieved from the provider. In case of expired, invalid, or malformed tokens, a 403 error is sent to the user. The use of the query parameter should be minimised because its support may be limited or removed in future versions.

   If the validation is successful, the parsed form of the token is passed to the environment initialization step:

2. Environment initialization: The filter extracts data from the JWT token claims, creates the user in the local database if it is not yet present, and constructs the subject object and sets it into the per-request EnvironmentContext object, which is statically accessible everywhere.

   If the request was made using only a machine token, the following single authentication filter is used:

   org.eclipse.che.multiuser.machine.authentication.server.MachineLoginFilter: The filter finds the user that the userId token belongs to, retrieves the user instance, and sets the principal to the session. The CodeReady Workspaces server-to-server requests are performed using a dedicated request factory that signs every request with the current subject token obtained from the EnvironmentContext object.

Procedure

1. Update the authentication configuration parameters that are stored in the multiuser.properties file (such as client ID, authentication URL, realm name).
2. Write a single filter or a chain of filters to validate tokens, create the user in the CodeReady Workspaces dashboard, and compose the subject object.
3. If the new authorization provider supports the OpenID protocol, use the OIDC JS client library available at the settings endpoint because it is decoupled from specific implementations.
4. If the selected provider stores additional data about the user (first and last name, job title), it is recommended to write a provider-specific ProfileDao implementation that provides this information.