Amazon EKS クラスターでアプリケーションを有効にする

既存の Amazon EKS クラスターで稼働するアプリケーション向けに Application Signals を有効にするには

1. CloudWatch コンソールの https://console.aws.amazon.com/cloudwatch/ を開いてください。

2. [Application Signals] を選択します。

3. [プラットフォームの指定] では、[EKS] を選択します。

4. [EKS クラスターを選択] では、Application Signals を有効にするクラスターを選択します。

5. このクラスターで Amazon CloudWatch Observability EKS アドオンが有効になっていない場合は、有効にするよう求められます。このような場合は、次の操作を行います。

   1. [CloudWatch Observability EKS アドオンの追加] を選択します。Amazon EKS コンソールが表示されます。

   2. [Amazon CloudWatch Observability] のチェックボックスをオンにして [次へ] を選択します。

      CloudWatch Observability EKS アドオンにより、Application Signals と CloudWatch Container Insights の両方で、Amazon EKS のオブザーバビリティが向上します。コンテナインサイトの詳細については、Container Insightsを参照してください。

   3. インストールするアドオンの最新バージョンを選択します。

   4. アドオンに使用する IAM ロールを選択します。[ノードから継承] を選択した場合は、ワーカーノードで使用する IAM ロールに適切なアクセス権限をアタッチします。my-worker-node-role を Kubernetes ワーカーノードが使用する IAM ロールに置き換えます。

      aws iam attach-role-policy \
      --role-name my-worker-node-role \
      --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
      --policy-arn arn:aws:iam::aws:policy/AWSXRayWriteOnlyAccess

   5. アドオンを使用するサービスロールを作成する場合は、「Amazon CloudWatch Observability EKS アドオンまたは Helm チャートを使用して CloudWatch エージェントをインストールする」を参照してください。

   6. [次へ] を選択し、画面に表示される情報を確認して [作成] を選択します。

   7. 次の画面で、[CloudWatch Application Signals を有効にする] を選択して CloudWatch コンソールに戻り、この有効化のプロセスを終了します。

6. アプリケーションを Application Signals で有効にするには、2 つのオプションがあります。一貫性を保つために、クラスターごとに 1 つのオプションを選択することをお勧めします。

   • [コンソール] オプションの方が簡単です。この方法を使用すると、直ちにポッドが再起動されます。

   • [マニフェストファイルに注釈を付ける] メソッドを使用すると、ポッドがいつ再起動するかをより細かく制御でき、モニタリングを一元化したくない場合は、より分散的な方法でモニタリングを管理できます。

   注記

   ESM を使用する Node.js アプリケーションの Application Signals を有効にしている場合は、ESM モジュール形式を使用する Node.js アプリケーションをセットアップする のセクションに進んでください。

   Console

   [コンソール] オプションでは、Amazon CloudWatch Observability EKS アドオンの詳細設定を使用して、サービスの Application Signals を設定します。アドオンの詳細については、「(オプション) その他の設定」を参照してください。

   ワークロードと名前空間のリストが表示されない場合は、このクラスターでそれらを表示するための適切なアクセス許可があることを確認してください。詳細については、「必要なアクセス許可」を参照してください。

   すべてのサービスワークロードをモニタリングするには、[自動モニター] チェックボックスを選択するか、モニタリングする具体的なワークロードや名前空間を選択します。

   自動モニターですべてのサービスワークロードをモニタリングするには、次の手順を実施します。

   1. [自動モニター] チェックボックスをオンにすると、クラスター内のすべてのサービスワークロードが自動的に選択されます。

   2. [自動再起動] を選択してすべてのワークロードポッドを再起動すると、Application Signals が直ちに有効になり、AWS Distro for OpenTelemetry の自動計測 (ADOT) SDK がポッドに挿入されます。

   3. [完了] をクリックします。[自動再起動] を選択すると、CloudWatch Observability EKS アドオンによって Application Signals が直ちに有効になります。自動再起動を選択しない場合は、各ワークロードの次回のデプロイ時に Application Signals が有効になります。

   単一のワークロードをモニタリングすることも、名前空間全体をモニタリングすることもできます。

   単一のワークロードをモニタリングするには:

   1. モニタリングするワークロードの横にあるチェックボックスをオンにします。

   2. [言語を選択] ドロップダウンリストを使用して、ワークロードの言語を選択します。Application Signals を有効にする言語を選択し、チェックマークアイコン (✓) を選択してこの選択を保存します。

      Python アプリケーションの場合は、次に進む前にアプリケーションが必要な前提条件を満たしていることを確認してください。詳細については、「Application Signals を有効にしたが、その後、Python アプリケーションを起動できない」を参照してください。

   3. [完了] をクリックします。Amazon CloudWatch オブザーバビリティ EKS アドオンは、AWS Distro for OpenTelemetry 自動計測 (ADOT) SDK をすぐにポッドに挿入し、ポッドの再起動をトリガーしてアプリケーションメトリクスとトレースの収集を可能にします。

   名前空間全体をモニタリングするには:

   1. モニタリングする名前空間の横にあるチェックボックスをオンにします。

   2. [言語の選択] ドロップダウンリストを使用して、名前空間の言語を選択します。Application Signals を有効にする言語を選択し、チェックマークアイコン (✓) を選択してこの選択を保存します。これは、現在デプロイされているか、将来デプロイされるかに関係なく、この名前空間のすべてのワークロードに適用されます。

      Python アプリケーションの場合は、次に進む前にアプリケーションが必要な前提条件を満たしていることを確認してください。詳細については、「Application Signals を有効にしたが、その後、Python アプリケーションを起動できない」を参照してください。

   3. [完了] をクリックします。Amazon CloudWatch オブザーバビリティ EKS アドオンは、AWS Distro for OpenTelemetry 自動計測 (ADOT) SDK をすぐにポッドに挿入し、ポッドの再起動をトリガーしてアプリケーションメトリクスとトレースの収集を可能にします。

   別の Amazon EKS クラスターで Application Signals を有効にするには、[サービス] 画面から [Application Signals を有効にする] を選択します。

   Annotate manifest file

   CloudWatch コンソールの [サービスのモニタリング] セクションには、クラスターのマニフェスト YAML にアノテーションの追加が必要との説明があります。このアノテーションを追加すると、アプリケーションで自動的に計測が開始され、メトリクス、トレース、ログが Application Signals に送信されます。

   アノテーションには次の 2 つのオプションがあります。

   • ワークロードへのアノテーション: クラスター内の 1 つのワークロードに対し自動的に計測を開始します。

   • 名前空間へのアノテーション: 選択した名前空間にデプロイしたすべてのワークロードに対し自動的に計測を開始します。

   これらのオプションのどちらかを選択し、次の適切な手順に従います。

   • 単一のワークロードにアノテーションを付けるには:

     1. [ワークロードへのアノテーション] を選択します。

     2. 次のいずれかの行をワークロードマニフェストの PodTemplate セクションに貼り付けます。

        • Java ワークロードの場合:annotations: instrumentation.opentelemetry.io/inject-java: "true"

        • Python ワークロードの場合:annotations: instrumentation.opentelemetry.io/inject-python: "true"

          Python アプリケーションには、追加で必要な設定があります。詳細については、「Application Signals を有効にしたが、その後、Python アプリケーションを起動できない」を参照してください。

        • [.NET ワークロードの場合] annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"

          注記

          Alpine Linux (linux-musl-x64) ベースのイメージでの .NET ワークロードに対して Application Signals を有効にするには、以下の注釈を追加します。

          instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"

        • Node.js ワークロードの場合: annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"

     3. ターミナルで、kubectl apply -f your_deployment_yaml と入力して変更を適用します。

   • 名前空間内のすべてのワークロードにアノテーションを付けるには:

     1. [名前空間へのアノテーション] を選択します。

     2. 次のいずれかの行を名前空間マニフェストファイルのメタデータセクションに貼り付けます。名前空間に Java、Python、.NET のワークロードが含まれている場合は、次のすべての行を名前空間マニフェストファイルに貼り付けます。

        • 名前空間に Java ワークロードがある場合:annotations: instrumentation.opentelemetry.io/inject-java: "true"

        • 名前空間に Python ワークロードがある場合:annotations: instrumentation.opentelemetry.io/inject-python: "true"

          Python アプリケーションには、追加で必要な設定があります。詳細については、「Application Signals を有効にしたが、その後、Python アプリケーションを起動できない」を参照してください。

        • [名前空間に .NET ワークロードがある場合:]annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"

        • 名前空間に Node.js ワークロードがある場合:annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"

     3. ターミナルで、kubectl apply -f your_namespace_yaml と入力して変更を適用します。

     4. ターミナルで、名前空間のすべてのポッドを再起動するコマンドを入力します。デプロイメントのワークロードを再起動するコマンド例を次にしめします: kubectl rollout restart deployment -n namespace_name

7. [完了後にサービスを表示] を選択します。Application Signals のビューが開き、Application Signals によって収集されているデータが表示されます。データが表示されるまでに数分かかる場合があります。

   別の Amazon EKS クラスターで Application Signals を有効にするには、[サービス] 画面から [Application Signals を有効にする] を選択します。

   [サービス] ビューの詳細については、「Application Signals を使用したアプリケーションの運用状態のモニタリング」を参照してください。

ESM を使用する Node.js アプリケーションの Application Signals を有効にするには

1. 自動計測のために、関連する依存関係を Node.js アプリケーションにインストールします。

   npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
   npm install @opentelemetry/instrumentation@0.54.0

2. アプリケーションの Dockerfile に以下の環境変数を追加して、イメージを構築します。

   ...
   ENV OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
   ENV OTEL_TRACES_SAMPLER_ARG='endpoint=http://cloudwatch-agent.amazon-cloudwatch:2000'
   ENV OTEL_TRACES_SAMPLER='xray'
   ENV OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/traces'
   ENV OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/metrics'
   ENV OTEL_METRICS_EXPORTER='none'
   ENV OTEL_LOGS_EXPORTER='none'
   ENV NODE_OPTIONS='--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs'
   ENV OTEL_SERVICE_NAME='YOUR_SERVICE_NAME' #replace with a proper service name
   ENV OTEL_PROPAGATORS='tracecontext,baggage,b3,xray'
   ...
   
   # command to start the application
   # for example
   # CMD ["node", "index.mjs"]

3. 環境変数 OTEL_RESOURCE_ATTRIBUTES_POD_NAME、OTEL_RESOURCE_ATTRIBUTES_NODE_NAME、OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME、POD_NAMESPACE、OTEL_RESOURCE_ATTRIBUTES をアプリケーションのデプロイ yaml ファイルに追加します。例:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nodejs-app
     labels:
       app: nodejs-app
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: nodejs-app
     template:
       metadata:
         labels:
           app: nodejs-app
         # annotations:
         # make sure this annotation doesn't exit
         #   instrumentation.opentelemetry.io/inject-nodejs: 'true'
       spec:
         containers:
         - name: nodejs-app
           image:your-nodejs-application-image #replace with a proper image uri
           imagePullPolicy: Always
           ports:
           - containerPort: 8000
           env:
             - name: OTEL_RESOURCE_ATTRIBUTES_POD_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.name
             - name: OTEL_RESOURCE_ATTRIBUTES_NODE_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: spec.nodeName
             - name: OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.labels['app'] # Assuming 'app' label is set to the deployment name
             - name: POD_NAMESPACE
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.namespace
             - name: OTEL_RESOURCE_ATTRIBUTES
               value: "k8s.deployment.name=$(OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME)"

4. Node.js アプリケーションをクラスターにデプロイします。

1. アプリケーション向けに Application Signals を有効にします。

   import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';
   
   const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
     'ApplicationSignalsServiceRole', { }
   );

   Discovery CloudFormation リソースは、Application Signals に次のアクセス許可を付与します。

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   このロールの詳細については、「CloudWatch Application Signals のサービスリンクロールのアクセス許可」を参照してください。

2. amazon-cloudwatch-observability アドオンをインストールします。

   1. クラスターに関連付けられた CloudWatchAgentServerPolicy と OIDC を使用して IAM ロールを作成します。

      const cloudwatchRole = new Role(this, 'CloudWatchAgentAddOnRole', {
          assumedBy: new OpenIdConnectPrincipal(cluster.openIdConnectProvider),
          managedPolicies: [ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')],
      });

3. 前の手順で作成した IAM ロールを使用してアドオンをインストールします。

   new CfnAddon(this, 'CloudWatchAddon', {
       addonName: 'amazon-cloudwatch-observability',
       clusterName: cluster.clusterName,
       serviceAccountRoleArn: cloudwatchRole.roleArn
   });

4. 次のいずれかをワークロードマニフェストファイルの PodTemplate セクションに追加します。

   言語	ファイル
   Java	instrumentation.opentelemetry.io/inject-java: "true"
   Python	instrumentation.opentelemetry.io/inject-python: "true"
   .Net	instrumentation.opentelemetry.io/inject-dotnet: "true"
   Node.js	instrumentation.opentelemetry.io/inject-nodejs: "true"

   const deployment = {
     apiVersion: "apps/v1",
     kind: "Deployment",
     metadata: { name: "sample-app" },
     spec: {
       replicas: 3,
       selector: {
         matchLabels: {
           "app": "sample-app"
         }
       },
       template: {
         metadata: {
           labels: {
             "app": "sample-app"
           },
           annotations: {
             "instrumentation.opentelemetry.io/inject-$LANG": "true"
           }
         },
         spec: {...},
       },
     },
   };
   
   cluster.addManifest('sample-app', deployment)