APM Javaエージェントをデプロイするには、次のステップを実行します。

1. 続行する前に、前提条件を完了し、APM Javaエージェントをプロビジョニングしたことを確認します。
   ノート
   
   APM Javaエージェントをプロビジョニングする場合は、それをローカル・マシンの任意の場所にプロビジョニングしてから、Dockerイメージにコピーすることをお薦めします。
2. Dockerfileを変更して、APM JavaエージェントをDockerイメージにコピーします:

   COPY <DESTINATION_DIRECTORY>/oracle-apm-agent <Docker_Image_Directory>/oracle-apm-agent/

   <DESTINATION_DIRECTORY>は、APM Javaエージェントをプロビジョニングしたローカル・マシン上の場所を示し、<Docker_Image_Directory>は、APM Javaエージェントのコピー先のDockerイメージ内のディレクトリを示します。Oracle WebLogic Serverを使用している場合は、<Docker_Image_Directory>をDockerのアプリケーション・サーバー宛先ディレクトリ(たとえば、$DOMAIN_HOME)にすることもできます。

3. 次の-javaagentオプションをアプリケーション・サーバーの起動スクリプトに追加します:

   java -javaagent:<Docker_Image_Directory>/oracle-apm-agent/bootstrap/ApmAgent.jar -jar target/<appserver.jar>

4. 組込みのAPM Javaエージェントおよび変更済の起動スクリプトを使用して新しいDockerイメージをビルドし、そのイメージをレジストリにプッシュします。

Kubernetesを使用してDockerコンテナを管理する場合は、新しいDockerイメージを使用するようにKubernetes構成を更新してから、Kubernetesポッドを再起動します。

また、Kubernetesポッドのデプロイメント仕様(yamlファイル)で次の環境およびボリューム設定をコピーすることで、Downward APIを使用してKubernetesポッドからレポートされる追加のディメンションを設定できます。Downward APIの詳細は、KubernetesドキュメントのDownward APIを参照してください。

環境設定

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    env:
      - name: APM_ATTRIBUTES_K8S_POD_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.name
      - name: APM_ATTRIBUTES_K8S_NAMESPACE_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.namespace
      - name: APM_ATTRIBUTES_K8S_NODE_NAME
        valueFrom:
          fieldRef:
            fieldPath: spec.nodeName

ボリューム設定

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    volumeMounts:
      - name: apm-attributes-k8s
        mountPath: /etc/apm-attributes-k8s
    volumes:
      - name: apm-attributes-k8s
        downwardAPI:
         items:
           - path: "labels"
             fieldRef:
               fieldPath: metadata.labels
           - path: "annotations"
             fieldRef:
               fieldPath: metadata.annotations

前提条件: OpenTelemetry OperatorをKubernetesクラスタにインストールします。

Operator release manifest、Operator helm chart、または Operator Hubの3つの異なるオプションを使用できます。

ほとんどの場合、cert-managerをインストールする必要があります。ヘルムチャートオプションを使用する場合は、代わりに自己署名証明書を生成するオプションがあります。

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.2/cert-manager.yaml

OpenTelemetry演算子をインストールするには、次を実行します:

kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

APM Javaエージェントのデプロイ

APM Javaエージェントをデプロイするには、次のステップを実行します。

1. Kubernetesカスタム・リソース(CR)を作成します。

   自動インストゥルメンテーションを管理するには、OpenTelemetry演算子に、カスタム・リソース定義(CRD)を使用して実行されるAPM Javaエージェントとその構成に関する情報を指定する必要があります。

   オペレータがこのカスタム・リソースを使用して、エージェントをポッドにコピーし、必要な構成を追加します。

   CRを作成するには、次を実行します。

   kubectl apply -f - <<EOF
   apiVersion: opentelemetry.io/v1alpha1
   kind: Instrumentation
   metadata:
     name: inst-apm-java
     namespace: opentelemetry-operator-system
   spec:
     java:
       image: container-registry.oracle.com/oci_observability_management/oci-apm-java-agent:1.15.0.516
       env:
         - name: OTEL_com_oracle_apm_agent_data_upload_endpoint
           value: <data-upload-endpoint>
         - name: OTEL_com_oracle_apm_agent_private_data_key
           value: <private-data-key>
   EOF

   説明:

   • <data-upload-endpoint>は、APMドメインの作成時に生成されるデータ・アップロード・エンドポイントURLです。詳細は、データ・アップロード・エンドポイントとデータ・キーの取得を参照してください。
   • <private-data-key>は、APMドメインの作成時に生成されるAPM Javaエージェント・インストールのプライベート・データ・キーです。詳細は、データ・アップロード・エンドポイントとデータ・キーの取得を参照してください。
   作成されたCRは、次のコマンドを実行して問い合せることができます。

   kubectl get otelinst -n opentelemetry-operator-system

   自動インストゥルメンテーションが正しく機能するには、すべてのエンドポイントおよび環境変数が正しい必要があります。
2. Kubernetesアノテーションを追加します。

   OpenTelemetry演算子は、Kubernetes注釈を使用して、APM Javaエージェントで自動インジェクトするポッドを決定します。

   注釈はネームスペースに追加できます。その場合、そのネームスペース内のすべてのポッドが注入されます。注釈は、デプロイメント、ステートフルセットおよびその他のリソースの一部として使用可能な個々のPodSpecオブジェクトに追加することもできます。

   注釈:

   instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/inst-apm-java"

   ネームスペースの編集を開始するには、次を実行します:

   • 次のコマンドを実行します:

     kubectl edit namespace <your-namespace-name>

   • エディタを開いたらネームスペースを編集します。たとえば、viエディタなどを使用します。
   • 注釈をネームスペースに追加します。インデントは、有効なYAMLファイルとして作成することが非常に重要です。
   例:

   apiVersion: v1
   kind: Namespace
   metadata:
     labels:
       kubernetes.io/metadata.name: mynamespace
     annotations:
       instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/inst-apm-java"
     name: mynamespace
   spec:

3. Kubernetesポッドを再起動します。

   APM Javaエージェントを自動インジェクトするポッドを再起動するには、次を実行します:

   kubectl delete pod <your-pod-name> -n <your-namespace-name>

4. Kubernetesポッドを確認します。
   再起動後にAPM Javaエージェントでポッドが自動インジェクトされたことを確認するには、次を実行します:

   kubectl get pod <your-pod-name> -n <your-namespace-name> -o yaml

次のステップ(APM Javaエージェント・デプロイメントの検証)に移動できるようになりました。

マウントされたボリュームにAPM Javaエージェントをデプロイするには、次のステップを実行します。

1. APM Javaエージェントの前提条件タスクを完了したことを確認します。

   APMドメインの作成時に、データ・アップロード・エンドポイントおよびデータ・キーをノートにとります。

2. ポッドをマウントする新しいファイルシステムを作成します。

   ファイル・システムを作成する際には、Kubernetesで使用されているものと同じVirtual Cloud Network (VCN)コンパートメントを選択することが重要です。同じことをサブネット・コンパートメントに対して行います。

3. ファイル・システムをポッドにマウントします。

   このステップでは、対応するyamlファイルを編集する必要があります。

   次のyamlファイルを使用して、KubernetesにPersistentVolumeおよび関連エンティティを作成します。環境用に編集する必要があるフィールドmntTargetId、serverおよびpathに注意してください。

   kind: StorageClass
   apiVersion: storage.k8s.io/v1
   metadata:
     name: oci-fss
   provisioner: oracle.com/oci-fss
   parameters:
     mntTargetId: ocid1.mounttarget.oc1.iad.xxxxxxxxxxxxxxxxxxxxxx
   ---
   apiVersion: v1
   kind: PersistentVolume
   metadata:
    name: oke-fsspv
   spec:
    storageClassName: oci-fss
    capacity:
     storage: 10Gi
    accessModes:
     - ReadWriteMany
    mountOptions:
     - nosuid
    nfs:
   # Replace this with the IP of your FSS file system in OCI
     server: 10.0.10.39
   # Replace this with the Path of your FSS file system in OCI
     path: "/fss-for-kub"
     readOnly: false
   ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
    name: oke-fsspvc
   spec:
    storageClassName: oci-fss
    accessModes:
    - ReadWriteMany
    resources:
     requests:
    # Although storage is provided here it is not used for FSS file systems
       storage: 10Gi
    volumeName: oke-fsspv

   変更を適用するには、kubectl apply -f <filename.yaml>を実行します

   次に、ポッドを管理するyamlファイルを更新し、ボリュームとボリュームのマウントを追加します。

   有効にするには、ポッドを再作成します。

4. APM Javaエージェント・ファイルをダウンロードします。

   ファイルをダウンロードし、マウントされたボリュームにコピーします。

   ダウンロード手順については、「APM Java Agentソフトウェアのダウンロード」を参照してください。

   ダウンロード後、マウントされたボリュームにコピーします。

5. APM Javaエージェントのプロビジョニング

   いずれかのコンテナにログインしてAPM Javaエージェントをプロビジョニングし、APM-java-agent-installer jarファイルを見つけて、次を実行します:

   java -jar ./apm-java-agent-installer-<version>.jar provision-agent -service-name=<Name of the Service> -destination=<Destination_Directory> -private-data-key=<Agent installation key generated during APM domain creation> -data-upload-endpoint=<dataUploadEndpoint URL generated during APM domain creation>

   プロビジョニング手順は、APM Javaエージェントのプロビジョニングを参照してください。

6. APM Javaエージェントのデプロイ

   yamlファイルのマイクロサービスにoracle-apm-agentの場所を指定して、APM Javaエージェントをデプロイします。

   -javaagent引数とAPMエージェントのjarファイルの場所を各マイクロサービスのjavaコマンドに追加します。

   java -javaagent:<Mounted Volume>/oracle-apm-agent/bootstrap/ApmAgent.jar

7. Kubernetesを再起動します。

   kubectl apply -f <filename.yaml>を実行して、ポッドを再作成します。

   次のステップ(APM Javaエージェント・デプロイメントの検証)に移動できるようになりました。