管理ガイド

1. イベントを受信するサーバープロセスの作成
2. イベントをサーバーに送信するバックエンドを作成する OpenShift Dev Spaces ライブラリーの拡張
3. コンテナーでの Telemetry バックエンドのパッケージ化およびイメージレジストリーへのデプロイ
4. バックエンドのプラグインを追加し、OpenShift Dev Space に Dev Workspaces にプラグインを読み込むよう指示

1. Maven Quarkus プロジェクトのスキャフォールディング:

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

2. src/main/java/mygroup と src/test/java/mygroup の下にあるファイルを削除します。
3. backend-base の最新バージョンおよび Maven コーディネートについては、GitHub パッケージ を参照してください。

4. 以下の依存関係を pom.xml に追加します。

   例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. read:packages パーミッションでパーソナルアクセストークンを作成し、GitHub パッケージ から org.eclipse.che.incubator.workspace-telemetry:backend-base 依存関係をダウンロードします。

6. GitHub ユーザー名、個人アクセストークン、che-incubator リポジトリーの詳細を ~/.m2/settings.xml ファイルに追加します。

   例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. Dev Workspace に DEVWORKSPACE_TELEMETRY_BACKEND_PORT 環境変数を設定します。ここで、値は 4167 に設定されます。

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

2. Red Hat OpenShift Dev Spaces ダッシュボードから Dev Workspace を再起動します。

3. Dev Workspace のターミナルウィンドウ内で以下のコマンドを実行し、アプリケーションを起動します。--settings フラグを使用して、GitHub アクセストークンが含まれる settings.xml ファイルの場所へのパスを指定します。

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

   アプリケーションは、フロントエンドプラグインからポート 4167 を使用して Telemetry イベントを受け取るようになりました。

検証手順

1. 以下の出力がログに記録されていることを確認します。

   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. AnalyticsManager の onEvent() メソッドがフロントエンドプラグインからイベントを受信することを確認するには、l キーを押して Quarkus ライブコーディングを無効にし、IDE 内のファイルを編集します。以下の出力がログに記録されるはずです。

   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. TelemetryService.java を作成して RESTEasy REST Client を設定します。

   例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

   POST リクエストを行うエンドポイント。

2. src/main/resources/application.properties ファイルで TelemetryService のベース URL を指定します。

   例3.20 application.properties

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

3. TelemetryService を AnalyticsManager に挿入し、onEvent() で POST リクエストを送信します

   例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);
   }

   これにより、HTTP 要求が Telemetry サーバーに送信され、短期間同じイベントが自動的に遅延します。デフォルトの期間は 1500 ミリ秒です。

1. 以下を既存の Dev Workspace の components フィールドに追加します。

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

2. OpenShift Dev Spaces ダッシュボードから Dev Workspace を起動します。

検証手順

1. Telemetry-plug-in コンテナーが Dev Workspace Pod で稼働していることを確認します。ここでは、これはエディターで Workspace ビューをチェックして検証されます。

   
2. エディター内のファイルを編集し、Telemetry サーバーのログのサンプルでイベントを確認します。

検証手順

1. Red Hat OpenShift Dev Spaces ダッシュボードから新規または既存の Dev Workspace を起動します。
2. 「Dev Workspace での Telemetry プラグインの指定」 の検証手順に従って、Telemetry プラグインが機能していることを確認します。

手順

1. ClusterRoleBinding を作成して、Prometheus に関連付けられた ServiceAccount を devworkspace-controller-metrics-reader ClusterRole にバインドします。監視スタックの例 では、使用される ServiceAccount の名前は prometheus です。

   注記

   Dev Workspace メトリクスへのアクセスはロールベースアクセスコントロール (RBAC) で保護されているため、ClusterRoleBinding がないとアクセスできません。

   例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. Prometheus は、devworkspace-controller-metrics サービスが公開するポート 8443 と、devworkspace-webhookserver サービスが公開するポート 9443 からメトリクスを収集するように設定します。

   注記

   モニターリングスタックのサンプル では、空の設定で prometheus-config ConfigMap がすでに作成されています。Prometheus 設定の詳細を指定するには、ConfigMap の data フィールドを編集します。

   例3.32 Prometheus の設定

   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

   ターゲットが収集されるレート。

   2

   記録およびアラートルールを再チェックするレート。

   3

   Prometheus が監視するリソースデフォルトの設定では、2 つのジョブ (DevWorkspace および DevWorkspace webhooks) が、devworkspace-controller-metrics サービスおよび devworkspace-webhookserver サービスによって公開された時系列データを収集します。

   4

   ポート 8443 からのメトリクスのスクレイプターゲット。<DWO_project> を、devworkspace-controller-metrics Service が置かれているプロジェクトに置き換えます。

   5

   ポート 9443 からのメトリクスのスクレイプターゲット。<DWO_project> を、devworkspace-webhookserver Service が置かれているプロジェクトに置き換えます。

3. Prometheus Deployment をスケールダウンおよびスケールアップし、直前の手順で更新された ConfigMap を読み取ります。

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

検証

1. ポート転送を使用して、ローカルで Prometheus サービスにアクセスします。

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

2. localhost:9090/targets でターゲットエンドポイントを表示して、すべてのターゲットが稼働していることを確認します。

3. Prometheus コンソールを使用して、メトリクスを表示および照会します。

   • localhost:9090/metrics でメトリクスを表示します。

   • localhost:9090/graph からメトリクスをクエリーします。

     詳細は、Using the expression browser を参照してください。

手順

1. Prometheus インスタンスのデータソースを追加します。Creating a Prometheus data source を参照してください。
2. example grafana-dashboard.json ダッシュボードをインポートします。

手順

1. ポート 8087 からメトリクスを収集するように Prometheus を設定します。

   注記

   モニターリングスタックのサンプル では、空の設定で prometheus-config ConfigMap がすでに作成されています。Prometheus 設定の詳細を指定するには、ConfigMap の data フィールドを編集します。

   例3.33 Prometheus の設定

   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

   ターゲットが収集されるレート。

   2

   記録およびアラートルールを再チェックするレート。

   3

   Prometheus が監視するリソースデフォルト設定では、OpenShift Dev Spaces Server という単一のジョブが、OpenShift Dev Spaces Server によって公開された時系列データをスクレイピングします。

   4

   ポート 8087 からのメトリクスのスクレイプターゲット。<OpenShift Dev Spaces_project> を OpenShift Dev Spaces プロジェクトに置き換えます。デフォルトの OpenShift Dev Spaces プロジェクトは openshift-devspaces です。

2. Prometheus Deployment をスケールダウンおよびスケールアップし、直前の手順で更新された ConfigMap を読み取ります。

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

検証

1. ポート転送を使用して、ローカルで Prometheus サービスにアクセスします。

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

2. localhost:9090/targets で targets エンドポイントを表示して、すべてのターゲットが稼働していることを確認します。

3. Prometheus コンソールを使用して、メトリクスを表示および照会します。

   • localhost:9090/metrics でメトリクスを表示します。

   • localhost:9090/graph からメトリクスをクエリーします。

     詳細は、Using the expression browser を参照してください。

手順

1. Prometheus インスタンスのデータソースを追加します。Creating a Prometheus data source を参照してください。
2. サンプル ダッシュボード をインポートします。Import dashboard を参照してください。

3. Grafana コンソールで OpenShift Dev Spaces メトリクスを表示します。

   図3.4 OpenShift Dev Spaces サーバーの JVM ダッシュボード

   

   図3.5 クイックファクト

   

   図3.6 JVM メモリー

   

   図3.7 JVM Misc

   

   図3.8 JVM メモリープール (ヒープ)

   

   図3.9 JVM メモリープール (非ヒープ)

   

   図3.10 ガベージコレクション

   

   図3.11 クラ出力ディング

   

   図3.12 バッファープール

   

手順

1. https://github.com/settings/applications/new にアクセスします。

2. 以下の値を設定します。

   1. アプリケーション名: OpenShift Dev Spaces
   2. ホームページ URL:"https://devspaces-<openshift_deployment_name>.<domain_name>"/
   3. 認証コールバック URL:"https://devspaces-<openshift_deployment_name>.<domain_name>"/api/oauth/callback
3. Register application をクリックします。
4. Generate new client secret をクリックします。

5. GitHub OAuth アプリケーションシークレットを適用する際に使用する GitHub OAuth クライアント ID をコピーし、これを Base64 にエンコードします。

   $ echo -n '<github_oauth_client_id>' | base64

6. GitHub OAuth クライアントシークレットをコピーし、GitHub OAuth App Secret を適用する際に使用する Base64 にエンコードします。

   $ echo -n '<github_oauth_client_secret>' | base64

手順

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

   OpenShift Dev Spaces 名前空間。デフォルトは openshift-devspaces です。

   2

   GitHub Enterprise Server URL。デフォルトでは、https://github.com は SAAS バージョンに使用されます。

   3

   Base64 でエンコードされた GitHubOAuth クライアント ID。

   4

   base64 でエンコードされた GitHub OAuth クライアントシークレット。

2. シークレットを適用します。

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

3. 出力に Secret が作成されたことを確認します。

手順

1. アバターをクリックして、プロファイル → アプリケーション の編集に移動します。
2. Name に OpenShift Dev Spaces を入力します。
3. "https://devspaces-<openshift_deployment_name>.<domain_name>"/api/oauth/callback を Redirect URI として入力します。
4. Confidential および Expire access tokens のチェックボックスを選択します。
5. Scopes の下で、api、write_repository、および openid のチェックボックスにチェックを入れます。
6. Save application をクリックします。

7. GitLab アプリケーション ID をコピーし、GitLab で承認されたアプリケーションシークレットを適用するときに使用する Base64 にエンコードします。

   $ echo -n '<gitlab_application_id>' | base64

8. GitLab クライアントシークレット をコピーし、GitLab で承認されたアプリケーションシークレットを適用するときに使用する Base64 にエンコードします。

   $ echo -n '<gitlab_client_secret>' | base64

手順

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

   OpenShift Dev Spaces 名前空間。デフォルトは openshift-devspaces です。

   2

   GitLab サーバーの URL です。SAAS バージョンには https://gitlab.com を使用します。

   3

   Base64 でエンコードされた GitLab アプリケーション ID。

   4

   Base64 でエンコードされた GitLab クライアントシークレット。

2. シークレットを適用します。

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

3. 出力に Secret が作成されたことを確認します。

手順

1. コマンドラインでコマンドを実行して、次の手順に必要なファイルを作成し、アプリケーションリンクシークレットを適用するときに使用します。

   $ 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. Administration → Application Links に移動します。
3. URL フィールドに "https://devspaces-<openshift_deployment_name&gt:.<domain_name>"/ と入力し、Create new link をクリックします。
4. 提供されたアプリケーション URL が一度リダイレクトされました で、この URL を使用する チェックボックスをオンにして、続行 をクリックします。
5. Application Name に OpenShift Dev Spaces を入力します。
6. Application Type として Generic Application を選択します。
7. OpenShift Dev Spaces を Service Provider Name として入力します。
8. bitbucket-consumer-key ファイルの内容を Consumer キー として貼り付けます。
9. bitbucket-shared-secret ファイルの内容を Shared シークレット として貼り付けます。
10. リクエストトークンの URL として <bitbucket_server_url>/plugins/servlet/oauth/request-token と入力します。
11. アクセストークンの URL として <bitbucket_server_url>/plugins/servlet/oauth/access-token と入力します。
12. Authorize URL として <bitbucket_server_url>/plugins/servlet/oauth/authorize と入力します。
13. 受信リンクの作成 チェックボックスをオンにして、続行 をクリックします。
14. bitbucket_consumer_key ファイルの内容を Consumer キー として貼り付けます。
15. コンシューマー名 として OpenShift Dev Spaces を入力します。
16. public-stripped.pub ファイルの内容を 公開鍵 として貼り付け、Continue をクリックします。

手順

1. 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_server_consumer_key> 4
     shared_secret: <Base64_content_of_bitbucket-shared-secret> 5

   1

   OpenShift Dev Spaces 名前空間。デフォルトは openshift-devspaces です。

   2

   Bitbucket Server の URL。

   3

   privatepkcs8-stripped.pem ファイルの Base64 でエンコードされたコンテンツ。

   4

   bitbucket_consumer_key ファイルの Base64 でエンコードされたコンテンツ。

   5

   bitbucket-shared-secret ファイルの Base64 でエンコードされたコンテンツ。

2. シークレットを適用します。

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

3. 出力に Secret が作成されたことを確認します。

手順

1. アバターをクリックして、All workspaces ページに移動します。
2. ワークスペースを選択してクリックします。
3. Settings → OAuth consumers → Add consumer に移動します。
4. Name に OpenShift Dev Spaces を入力します。
5. "https://devspaces-<openshift_deployment_name>.<domain_name>"/api/oauth/callback を Callback URL として入力します。
6. Permissions で、Account と Repositories のすべてのチェックボックスをオンにして、Save をクリックします。

7. 追加したコンシューマーを展開してから、キー 値をコピーして Base64 にエンコードし、Bitbucket OAuth コンシューマーシークレットを適用するときに使用します。

   $ echo -n '<bitbucket_oauth_consumer_key>' | base64

8. Bitbucket OAuth コンシューマーシークレットを適用するときに使用するために、Secret 値をコピーして Base64 にエンコードします。

   $ echo -n '<bitbucket_oauth_consumer_secret>' | base64

手順

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

   OpenShift Dev Spaces 名前空間。デフォルトは openshift-devspaces です。

   2

   Base64 でエンコードされた Bitbucket OAuth コンシューマーキー。

   3

   Base64 でエンコードされた Bitbucket OAuth コンシューマーシークレット。

2. シークレットを適用します。

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

3. 出力に Secret が作成されたことを確認します。