Chapter 3. Configuring Dev Spaces

1. Creating a server process that receives events
2. Extending OpenShift Dev Spaces libraries to create a backend that sends events to the server
3. Packaging the telemetry backend in a container and deploying it to an image registry
4. Adding a plugin for your backend and instructing OpenShift Dev Spaces to load the plugin in your Dev Workspaces

1. Maven Quarkus project scaffolding:

   mvn io.quarkus:quarkus-maven-plugin:2.7.1.Final:create \
       -DprojectGroupId=mygroup -DprojectArtifactId=devworkspace-telemetry-example-plugin \
   -DprojectVersion=1.0.0-SNAPSHOT

2. Remove the files under src/main/java/mygroup and src/test/java/mygroup.
3. Consult the GitHub packages for the latest version and Maven coordinates of backend-base.

4. Add the following dependencies to your pom.xml:

   Example 3.13. pom.xml

   <!-- Required -->
   <dependency>
       <groupId>org.eclipse.che.incubator.workspace-telemetry</groupId>
       <artifactId>backend-base</artifactId>
       <version>LATEST VERSION FROM PREVIOUS STEP</version>
   </dependency>
   
   
   <!-- Used to make http requests to the telemetry server -->
   <dependency>
       <groupId>io.quarkus</groupId>
       <artifactId>quarkus-rest-client</artifactId>
   </dependency>
   <dependency>
       <groupId>io.quarkus</groupId>
       <artifactId>quarkus-rest-client-jackson</artifactId>
   </dependency>

5. Create a personal access token with read:packages permissions to download the org.eclipse.che.incubator.workspace-telemetry:backend-base dependency from GitHub packages.

6. Add your GitHub username, personal access token and che-incubator repository details in your ~/.m2/settings.xml file:

   Example 3.14. 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
   http://maven.apache.org/xsd/settings-1.0.0.xsd">
      <servers>
         <server>
            <id>che-incubator</id>
            <username>YOUR GITHUB USERNAME</username>
            <password>YOUR GITHUB TOKEN</password>
         </server>
      </servers>
   
      <profiles>
         <profile>
            <id>github</id>
            <activation>
               <activeByDefault>true</activeByDefault>
            </activation>
            <repositories>
               <repository>
                  <id>central</id>
                  <url>https://repo1.maven.org/maven2</url>
                  <releases><enabled>true</enabled></releases>
                  <snapshots><enabled>false</enabled></snapshots>
                  </repository>
                  <repository>
                  <id>che-incubator</id>
                  <url>https://maven.pkg.github.com/che-incubator/che-workspace-telemetry-client</url>
               </repository>
            </repositories>
         </profile>
      </profiles>
   </settings>

1. Set the DEVWORKSPACE_TELEMETRY_BACKEND_PORT environment variable in the Dev Workspace. Here, the value is set to 4167.

   spec:
     template:
       attributes:
         workspaceEnv:
           - name: DEVWORKSPACE_TELEMETRY_BACKEND_PORT
             value: '4167'

2. Restart the Dev Workspace from the Red Hat OpenShift Dev Spaces dashboard.

3. Run the following command within a Dev Workspace’s terminal window to start the application. Use the --settings flag to specify path to the location of the settings.xml file that contains the GitHub access token.

   $ mvn --settings=settings.xml quarkus:dev -Dquarkus.http.port=${DEVWORKSPACE_TELEMETRY_BACKEND_PORT}

   The application now receives telemetry events through port 4167 from the front-end plugin.

Verification steps

1. Verify that the following output is logged:

   INFO  [org.ecl.che.inc.AnalyticsManager] (Quarkus Main Thread) No welcome message provided
   INFO  [io.quarkus] (Quarkus Main Thread) devworkspace-telemetry-example-plugin 1.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 0.323s. Listening on: http://localhost:4167
   INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
   INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, kubernetes-client, rest-client, rest-client-jackson, resteasy, resteasy-jsonb, smallrye-context-propagation, smallrye-openapi, swagger-ui, vertx]

2. To verify that the onEvent() method of AnalyticsManager receives events from the front-end plugin, press the l key to disable Quarkus live coding and edit any file within the IDE. The following output should be logged:

   INFO  [io.qua.dep.dev.RuntimeUpdatesProcessor] (Aesh InputStream Reader) Live reload disabled
   INFO  [org.ecl.che.inc.AnalyticsManager] (executor-thread-2) The received event is: Edit Workspace File in Che

1. Set up the RESTEasy REST Client by creating TelemetryService.java

   Example 3.19. TelemetryService.java

   package org.my.group;
   
   import java.util.Map;
   
   import javax.ws.rs.Consumes;
   import javax.ws.rs.POST;
   import javax.ws.rs.Path;
   import javax.ws.rs.core.MediaType;
   import javax.ws.rs.core.Response;
   
   import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
   
   @RegisterRestClient
   public interface TelemetryService {
       @POST
       @Path("/event") 1
       @Consumes(MediaType.APPLICATION_JSON)
       Response sendEvent(Map<String, Object> payload);
   }

   1

   The endpoint to make the POST request to.

2. Specify the base URL for TelemetryService in the src/main/resources/application.properties file:

   Example 3.20. application.properties

   org.my.group.TelemetryService/mp-rest/url=http://little-telemetry-server-che.apps-crc.testing

3. Inject TelemetryService into AnalyticsManager and send a POST request in onEvent()

   Example 3.21. AnalyticsManager.java

   @Dependent
   @Alternative
   public class AnalyticsManager extends AbstractAnalyticsManager {
       @Inject
       @RestClient
       TelemetryService telemetryService;
   
   ...
   
   @Override
   public void onEvent(AnalyticsEvent event, String ownerId, String ip, String userAgent, String resolution, Map<String, Object> properties) {
       Map<String, Object> payload = new HashMap<String, Object>(properties);
       payload.put("event", event);
       telemetryService.sendEvent(payload);
   }

   This sends an HTTP request to the telemetry server and automatically delays identical events for a small period of time. The default duration is 1500 milliseconds.

1. Add the following to the components field of an existing Dev Workspace:

   components:
     ...
     - name: telemetry-plugin
       plugin:
         uri: http://apache-che.apps-crc.testing/plugin.yaml

2. Start the Dev Workspace from the OpenShift Dev Spaces dashboard.

Verification steps

1. Verify that the telemetry plugin container is running in the Dev Workspace pod. Here, this is verified by checking the Workspace view within the editor.

   
2. Edit files within the editor and observe their events in the example telemetry server’s logs.

Verification steps

1. Start a new or existing Dev Workspace from the Red Hat OpenShift Dev Spaces dashboard.
2. Verify that the telemetry plugin is working by following the verification steps for Section 3.6.1.6.12, “Specifying the telemetry plugin in a Dev Workspace”.

Procedure

1. Create a ClusterRoleBinding to bind the ServiceAccount associated with Prometheus to the devworkspace-controller-metrics-reader ClusterRole. For the example monitoring stack, the name of the ServiceAccount to be used is prometheus.

   Note

   Without the ClusterRoleBinding, you cannot access Dev Workspace metrics because access is protected with role-based access control (RBAC).

   Example 3.31. ClusterRoleBinding

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: devworkspace-controller-metrics-binding
   subjects:
     - kind: ServiceAccount
       name: prometheus
       namespace: monitoring
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: devworkspace-controller-metrics-reader

2. Configure Prometheus to scrape metrics from port 8443 exposed by the devworkspace-controller-metrics Service and from port 9443 exposed by the devworkspace-webhookserver Service.

   Note

   The example monitoring stack already creates the prometheus-config ConfigMap with an empty configuration. To provide the Prometheus configuration details, edit the data field of the ConfigMap.

   Example 3.32. Prometheus configuration

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: prometheus-config
     namespace: monitoring
   data:
     prometheus.yml: |-
         global:
           scrape_interval: 5s 1
           evaluation_interval: 5s 2
         scrape_configs: 3
           - job_name: 'DevWorkspace'
             scheme: https
             authorization:
               type: Bearer
               credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token'
             tls_config:
               insecure_skip_verify: true
             static_configs:
               - targets: ['devworkspace-controller-metrics.<DWO_project>:8443'] 4
           - job_name: 'DevWorkspace webhooks'
             scheme: https
             authorization:
               type: Bearer
               credentials_file: '/var/run/secrets/kubernetes.io/serviceaccount/token'
             tls_config:
               insecure_skip_verify: true
             static_configs:
               - targets: ['devworkspace-webhookserver.<DWO_project>:9443'] 5

   1

   The rate at which a target is scraped.

   2

   The rate at which the recording and alerting rules are re-checked.

   3

   The resources that Prometheus monitors. In the default configuration, two jobs, DevWorkspace and DevWorkspace webhooks, scrape the time series data exposed by the devworkspace-controller-metrics and devworkspace-webhookserver Services.

   4

   The scrape target for the metrics from port 8443. Replace <DWO_project> with the project where the devworkspace-controller-metrics Service is located.

   5

   The scrape target for the metrics from port 9443. Replace <DWO_project> with the project where the devworkspace-webhookserver Service is located.

3. Scale the Prometheus Deployment down and up to read the updated ConfigMap from the previous step.

   $ oc scale --replicas=0 deployment/prometheus -n monitoring && oc scale --replicas=1 deployment/prometheus -n monitoring

Verification

1. Use port forwarding to access the Prometheus Service locally:

   $ oc port-forward svc/prometheus 9090:9090 -n monitoring

2. Verify that all targets are up by viewing the targets endpoint at localhost:9090/targets.

3. Use the Prometheus console to view and query metrics:

   • View metrics at localhost:9090/metrics.

   • Query metrics from localhost:9090/graph.

     For more information, see Using the expression browser.

Procedure

1. Add the data source for the Prometheus instance. See Creating a Prometheus data source.
2. Import the example grafana-dashboard.json dashboard.

Procedure

1. Configure Prometheus to scrape metrics from port 8087.

   Note

   The example monitoring stack already creates the prometheus-config ConfigMap with an empty configuration. To provide the Prometheus configuration details, edit the data field of the ConfigMap.

   Example 3.33. Prometheus configuration

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: prometheus-config
   data:
     prometheus.yml: |-
         global:
           scrape_interval:     5s             1
           evaluation_interval: 5s             2
         scrape_configs:                       3
           - job_name: 'OpenShift Dev Spaces Server'
             static_configs:
               - targets: ['che-host.<OpenShift Dev Spaces_project>:8087']  4

   1

   The rate at which a target is scraped.

   2

   The rate at which the recording and alerting rules are re-checked.

   3

   The resources that Prometheus monitors. In the default configuration, a single job, OpenShift Dev Spaces Server, scrapes the time series data exposed by OpenShift Dev Spaces Server.

   4

   The scrape target for the metrics from port 8087. Replace <OpenShift Dev Spaces_project> with the OpenShift Dev Spaces project. The default OpenShift Dev Spaces project is openshift-devspaces.

2. Scale the Prometheus Deployment down and up to read the updated ConfigMap from the previous step.

   $ oc scale --replicas=0 deployment/prometheus -n monitoring && oc scale --replicas=1 deployment/prometheus -n monitoring

Verification

1. Use port forwarding to access the Prometheus Service locally:

   $ oc port-forward svc/prometheus 9090:9090 -n monitoring

2. Verify that all targets are up by viewing the targets endpoint at localhost:9090/targets.

3. Use the Prometheus console to view and query metrics:

   • View metrics at localhost:9090/metrics.

   • Query metrics from localhost:9090/graph.

     For more information, see Using the expression browser.

Procedure

1. Add the data source for the Prometheus instance. See Creating a Prometheus data source.
2. Import the example dashboard. See Import dashboard.

3. View the OpenShift Dev Spaces JVM metrics in the Grafana console:

   Figure 3.4. OpenShift Dev Spaces server JVM dashboard

   

   Figure 3.5. Quick Facts

   

   Figure 3.6. JVM Memory

   

   Figure 3.7. JVM Misc

   

   Figure 3.8. JVM Memory Pools (heap)

   

   Figure 3.9. JVM Memory Pools (Non-Heap)

   

   Figure 3.10. Garbage Collection

   

   Figure 3.11. Class loading

   

   Figure 3.12. Buffer Pools

   

Procedure

1. Go to https://github.com/settings/applications/new.

2. Enter the following values:

   1. Application name: OpenShift Dev Spaces
   2. Homepage URL: https://devspaces-<openshift_deployment_name>.<domain_name>/
   3. Authorization callback URL: https://devspaces-<openshift_deployment_name>.<domain_name>/api/oauth/callback
3. Click Register application.
4. Click Generate new client secret.

5. Copy the GitHub OAuth Client ID and encode it to Base64 for use when applying the GitHub OAuth App Secret:

   $ echo -n '<github_oauth_client_id>' | base64

6. Copy the GitHub OAuth Client Secret and encode it to Base64 for use when applying the GitHub OAuth App Secret:

   $ echo -n '<github_oauth_client_secret>' | base64

Procedure

1. Prepare the Secret:

   kind: Secret
   apiVersion: v1
   metadata:
     name: github-oauth-config
     namespace: openshift-devspaces 1
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: oauth-scm-configuration
     annotations:
       che.eclipse.org/oauth-scm-server: github
       che.eclipse.org/scm-server-endpoint: <github_server_url> 2
   type: Opaque
   data:
     id: <Base64_GitHub_OAuth_Client_ID> 3
     secret: <Base64_GitHub_OAuth_Client_Secret> 4

   1

   The OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   2

   A GitHub Enterprise Server URL. By default https://github.com is used for the SAAS version.

   3

   The Base64-encoded GitHub OAuth Client ID.

   4

   The Base64-encoded GitHub OAuth Client Secret.

2. Apply the Secret:

   $ oc apply -f - <<EOF
   <Secret_prepared_in_the_previous_step>
   EOF

3. Verify in the output that the Secret is created.

Procedure

1. Click your avatar and go to Edit profile Applications.
2. Enter OpenShift Dev Spaces as the Name.
3. Enter https://devspaces-<openshift_deployment_name>.<domain_name>/api/oauth/callback as the Redirect URI.
4. Check the Confidential and Expire access tokens checkboxes.
5. Under Scopes, check the api, write_repository, and openid checkboxes.
6. Click Save application.

7. Copy the GitLab Application ID and encode it to Base64 for use when applying the GitLab-authorized application Secret:

   $ echo -n '<gitlab_application_id>' | base64

8. Copy the GitLab Client Secret and encode it to Base64 for use when applying the GitLab-authorized application Secret:

   $ echo -n '<gitlab_client_secret>' | base64

Procedure

1. Prepare the Secret:

   kind: Secret
   apiVersion: v1
   metadata:
     name: gitlab-oauth-config
     namespace: openshift-devspaces 1
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: oauth-scm-configuration
     annotations:
       che.eclipse.org/oauth-scm-server: gitlab
       che.eclipse.org/scm-server-endpoint: <gitlab_server_url> 2
   type: Opaque
   data:
     id: <Base64_GitLab_Application_ID> 3
     secret: <Base64_GitLab_Client_Secret> 4

   1

   The OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   2

   The GitLab server URL. Use https://gitlab.com for the SAAS version.

   3

   The Base64-encoded GitLab Application ID.

   4

   The Base64-encoded GitLab Client Secret.

2. Apply the Secret:

   $ oc apply -f - <<EOF
   <Secret_prepared_in_the_previous_step>
   EOF

3. Verify in the output that the Secret is created.

Procedure

1. On a command line, run the commands to create the necessary files for the next steps and for use when applying the application link Secret:

   $ openssl genrsa -out private.pem 2048 && \
   openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in private.pem -out privatepkcs8.pem && \
   cat privatepkcs8.pem | sed 's/-----BEGIN PRIVATE KEY-----//g' | sed 's/-----END PRIVATE KEY-----//g' | tr -d '\n' | base64 | tr -d '\n' > privatepkcs8-stripped.pem && \
   openssl rsa -in private.pem -pubout > public.pub && \
   cat public.pub | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > public-stripped.pub && \
   openssl rand -base64 24 > bitbucket-consumer-key && \
   openssl rand -base64 24 > bitbucket-shared-secret

2. Go to Administration Application Links.
3. Enter https://devspaces-<openshift_deployment_name>.<domain_name>/ into the URL field and click Create new link.
4. Under The supplied Application URL has redirected once, check the Use this URL checkbox and click Continue.
5. Enter OpenShift Dev Spaces as the Application Name.
6. Select Generic Application as the Application Type.
7. Enter OpenShift Dev Spaces as the Service Provider Name.
8. Paste the content of the bitbucket-consumer-key file as the Consumer key.
9. Paste the content of the bitbucket-shared-secret file as the Shared secret.
10. Enter <bitbucket_server_url>/plugins/servlet/oauth/request-token as the Request Token URL.
11. Enter <bitbucket_server_url>/plugins/servlet/oauth/access-token as the Access token URL.
12. Enter <bitbucket_server_url>/plugins/servlet/oauth/authorize as the Authorize URL.
13. Check the Create incoming link checkbox and click Continue.
14. Paste the content of the bitbucket-consumer-key file as the Consumer Key.
15. Enter OpenShift Dev Spaces as the Consumer name.
16. Paste the content of the public-stripped.pub file as the Public Key and click Continue.

Procedure

1. Encode the content of the bitbucket-consumer-key file to Base64:

   $ echo -n '<bitbucket-consumer-key file content>' | base64

2. Encode the content of the bitbucket-shared-secret file to Base64:

   $ echo -n '<bitbucket-shared-secret file content>' | base64

3. Prepare the Secret:

   kind: Secret
   apiVersion: v1
   metadata:
     name: bitbucket-oauth-config
     namespace: openshift-devspaces 1
     labels:
       app.kubernetes.io/component: oauth-scm-configuration
       app.kubernetes.io/part-of: che.eclipse.org
     annotations:
       che.eclipse.org/oauth-scm-server: bitbucket
       che.eclipse.org/scm-server-endpoint: <bitbucket_server_url> 2
   type: Opaque
   data:
     private.key: <Base64_content_of_privatepkcs8-stripped.pem> 3
     consumer.key: <Base64_content_of_bitbucket-consumer-key> 4
     shared_secret: <Base64_content_of_bitbucket-shared-secret> 5

   1

   The OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   2

   The URL of the Bitbucket Server.

   3

   The content of the privatepkcs8-stripped.pem file, which was Base64-encoded when the file was generated.

   4

   The content of the bitbucket-consumer-key file that you manually encoded to Base64 in step 1.

   5

   The content of the bitbucket-shared-secret file that you manually encoded to Base64 in step 2.

4. Apply the Secret:

   $ oc apply -f - <<EOF
   <Secret_prepared_in_the_previous_step>
   EOF

5. Verify in the output that the Secret is created.

Procedure

1. Click your avatar and go to the All workspaces page.
2. Select a workspace and click it.
3. Go to Settings OAuth consumers Add consumer.
4. Enter OpenShift Dev Spaces as the Name.
5. Enter https://devspaces-<openshift_deployment_name>.<domain_name>/api/oauth/callback as the Callback URL.
6. Under Permissions, check all of the Account and Repositories checkboxes, and click Save.

7. Expand the added consumer and then copy the Key value and encode it to Base64 for use when applying the Bitbucket OAuth consumer Secret:

   $ echo -n '<bitbucket_oauth_consumer_key>' | base64

8. Copy the Secret value and encode it to Base64 for use when applying the Bitbucket OAuth consumer Secret:

   $ echo -n '<bitbucket_oauth_consumer_secret>' | base64

Procedure

1. Prepare the Secret:

   kind: Secret
   apiVersion: v1
   metadata:
     name: bitbucket-oauth-config
     namespace: openshift-devspaces 1
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: oauth-scm-configuration
     annotations:
       che.eclipse.org/oauth-scm-server: bitbucket
   type: Opaque
   data:
     id: <Base64_Bitbucket_Oauth_Consumer_Key> 2
     secret: <Base64_Bitbucket_Oauth_Consumer_Secret> 3

   1

   The OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   2

   The Base64-encoded Bitbucket OAuth consumer Key.

   3

   The Base64-encoded Bitbucket OAuth consumer Secret.

2. Apply the Secret:

   $ oc apply -f - <<EOF
   <Secret_prepared_in_the_previous_step>
   EOF

3. Verify in the output that the Secret is created.

Procedure

1. Visit https://app.vsaex.visualstudio.com/app/register/.

2. Enter the following values:

   1. Company name: OpenShift Dev Spaces
   2. Application name: OpenShift Dev Spaces
   3. Application website: https://devspaces-<openshift_deployment_name>.<domain_name>/
   4. Authorization callback URL: https://devspaces-<openshift_deployment_name>.<domain_name>/api/oauth/callback
3. In Select Authorized scopes, select Code (read and write).
4. Click Create application.

5. Copy the App ID and encode it to Base64 for use when applying the Microsoft Azure DevOps Services OAuth App Secret:

   $ echo -n '<microsoft_azure_devops_services_oauth_app_id>' | base64

6. Click Show to display the Client Secret.

7. Copy the Client Secret and encode it to Base64 for use when applying the Microsoft Azure DevOps Services OAuth App Secret:

   $ echo -n '<microsoft_azure_devops_services_oauth_client_secret>' | base64

Procedure

1. Prepare the Secret:

   kind: Secret
   apiVersion: v1
   metadata:
     name: azure-devops-oauth-config
     namespace: openshift-devspaces1
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
       app.kubernetes.io/component: oauth-scm-configuration
     annotations:
       che.eclipse.org/oauth-scm-server: azure-devops
   type: Opaque
   data:
     id: <Base64_Microsoft_Azure_DevOps_Services_OAuth_App_ID>2
     secret: <Base64_Microsoft_Azure_DevOps_Services_OAuth_Client_Secret>3

   1

   The OpenShift Dev Spaces namespace. The default is openshift-devspaces.

   2

   The Base64-encoded Microsoft Azure DevOps Services OAuth App ID.

   3

   The Base64-encoded Microsoft Azure DevOps Services OAuth Client Secret.

2. Apply the Secret:

   $ oc apply -f - <<EOF
   <Secret_prepared_in_the_previous_step>
   EOF

3. Verify in the output that the Secret is created.