# Kubernetes でアプリケーションを有効にする Kubernetes で CloudWatch Application Signals を有効にするには、このセクションに記載されているカスタムセットアップの手順を実行します。 アプリケーションを Kubernetes で実行する場合は、CloudWatch エージェントと AWS Distro for OpenTelemetry を自分でインストールして設定します。カスタム Application Signals セットアップで有効になったこれらのアーキテクチャでは、サービス名や、サービスが稼働しているホスト名またはクラスター名が Application Signals によって自動検出されません。これらの名前をカスタムセットアップの際に指定する必要があります。ここで指定した名前が Application Signals ダッシュボードに表示されことになります。 **要件** + Kubernetes クラスター上で、Application Signals を有効にできる管理者アクセス許可が付与されていること。 + Kubernetes クラスターが実行されている環境に AWS CLI がインストールされていること。AWS CLI のインストールについては、「[AWS CLI の最新バージョンを使用してインストールまたは更新を行う](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)」で詳しく確認できます。 + kubectl と Helm がローカルターミナルにインストールされていること。詳細については、[ kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) と [ Helm](https://helm.sh/) のドキュメントを参照してください。 ## ステップ 1: アカウントで Application Signals を有効にする まず、アカウントで Application Signals を有効にする必要があります。まだ有効にしていない場合は、「[アカウントで Application Signals を有効にする](CloudWatch-Application-Signals-Enable.md)」を参照してください。 ## ステップ 2: クラスターに CloudWatch エージェントオペレータをインストールする CloudWatch エージェントオペレータをインストールすると、オペレータや CloudWatch エージェント、その他の自動計測機能がクラスターにインストールされます。これを行うには、次のコマンドを入力します。*\$1REGION* を AWS リージョンに置き換えます。*\$1YOUR\$1CLUSTER\$1NAME* を、Application Signals ダッシュボードでのクラスターの表示名に置き換えます。 ``` helm repo add aws-observability https://aws-observability.github.io/helm-charts helm install amazon-cloudwatch-operator aws-observability/amazon-cloudwatch-observability \ --namespace amazon-cloudwatch --create-namespace \ --set region=$REGION \ --set clusterName=$YOUR_CLUSTER_NAME ``` 詳細については、GitHub の「[amazon-cloudwatch-observability](https://github.com/aws-observability/helm-charts/tree/main/charts/amazon-cloudwatch-observability)」を参照してください。 ## ステップ 3: Kubernetes クラスターの AWS 認証情報を設定する **重要** Kubernetes クラスターが Amazon EC2 上にホストされている場合は、このセクションをスキップして [ステップ 4: アノテーションを追加する](#Application-Signals-Enable-Kubernetes-annotations) に進むことができます。 Kubernetes クラスターがオンプレミスにホストされている場合は、このセクションの手順を使用して Kubernetes 環境に AWS 認証情報を追加する必要があります。 **オンプレミスの Kubernetes クラスターのアクセス許可を設定するには** 1. オンプレミスホストにアクセス許可を付与するために使用する IAM ユーザーを作成します。 1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。 1. **[ユーザー]**、**[ユーザーの作成]** の順に選択します。 1. **[ユーザー詳細]** で、**[ユーザー名]** に新しい IAM ユーザーの名前を入力します。これは、ホストの認証に使用される AWS のサインイン名です。その後、**[Next]** (次へ) を選択します。 1. **[アクセス許可の設定]** ページの **[権限オプション]** で、**[ポリシーを直接アタッチする]** を選択します。 1. **[アクセス許可ポリシー]** リストから、**CloudWatchAgentServerPolicy** ポリシーを選択して、ユーザーに追加します。次に、**[次へ]** を選択します。 1. **[確認と作成]** ページで、ユーザー名に問題がなく、**CloudWatchAgentServerPolicy** ポリシーが **[許可の概要]** に含まれていることを確認します。 1. **ユーザーの作成** を選択します。 1. AWS アクセスキーとシークレットキーを作成して取得します。 1. IAM コンソールのナビゲーションペインで、**[ユーザー]** を選択し、前のステップで作成したユーザーのユーザー名を選択します。 1. ユーザーのページで、**[セキュリティ認証情報]** タブを選択します。次に、**[アクセスキー]** セクションで、**[アクセスキーを作成]** を選択します。 1. **[アクセスキーの作成ステップ 1]** で、**[コマンドラインインターフェイス (CLI)]** を選択します。 1. **[アクセスキーの作成ステップ 2]** で、必要に応じてタグを入力して **[次へ]** を選択します。 1. **[アクセスキーの作成ステップ 3]** で、**[.csv ファイルをダウンロード]** を選択し、.csv ファイルに IAM ユーザーのアクセスキーとシークレットアクセスキーを含めて保存します。この情報は、次のステップで必要になります。 1. **[Done]** (完了) をクリックします。 1. 次のコマンドを入力して、オンプレミスホストで AWS 認証情報を設定します。*ACCESS\$1KEY\$1ID* と *SECRET\$1ACCESS\$1ID* を、前のステップでダウンロードした .csv ファイルに新しく生成したアクセスキーとシークレットアクセスキーに置き換えます。デフォルトでは、認証情報ファイルは `/home/user/.aws/credentials.` に保存されます。 ``` $ aws configure --profile AmazonCloudWatchAgent AWS Access Key ID [None]: ACCESS_KEY_ID AWS Secret Access Key [None]: SECRET_ACCESS_ID Default region name [None]: MY_REGION Default output format [None]: json ``` 1. Helm チャートを使用して、新規に作成した AWS 認証情報シークレットを、CloudWatch エージェントがインストールしたカスタムリソースに追加します。 ``` kubectl edit amazoncloudwatchagent cloudwatch-agent -n amazon-cloudwatch ``` 1. ファイルエディタを開いたままにして、デプロイの上部に次の設定を追加して、CloudWatch エージェントコンテナに AWS 認証情報をマウントします。パス `/home/user/.aws/credentials` をローカルの AWS ファイルシステム上の場所に置き換えます。 ``` apiVersion: cloudwatch.aws.amazon.com/v1alpha1 kind: AmazonCloudWatchAgent metadata: name: cloudwatch-agent namespace: amazon-cloudwatch spec: volumeMounts: - mountPath: /rootfs volumeMounts: - name: aws-credentials mountPath: /root/.aws readOnly: true volumes: - hostPath: path: /home/user/.aws/credentials name: aws-credentials --- ``` ## ステップ 4: アノテーションを追加する **注記** ESM を使用する Node.js アプリケーションの Application Signals を有効にする場合は、このセクションの手順をスキップし、代わりに「[ESM モジュール形式を使用する Node.js アプリケーションをセットアップする](#Kubernetes-NodeJs-ESM)」を参照してください。 次のステップでは、Kubernetes [ワークロード](https://kubernetes.io/docs/concepts/workloads/)または[名前空間](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)に言語固有の[アノテーション](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)を追加して、CloudWatch Application Signals でアプリケーションを計測します。このアノテーションは、アプリケーションの計測を自動的に開始してメトリクス、トレース、ログを Application Signals に送信します。 **Application Signals のアノテーションを追加するには** 1. アノテーションには次の 2 つのオプションがあります。 + **ワークロードへのアノテーション**: クラスター内の 1 つのワークロードの計測を自動的に開始します。 + **名前空間へのアノテーション**: 選択した名前空間にデプロイしたすべてのワークロードに対し自動的に計測を開始します。 以上のいずれかのオプションを選択し、次の適切な手順に従います。 1. 1 つのワークロードに注釈を追加するには、次のいずれかのコマンドを入力します。*\$1WORKLOAD\$1TYPE* と *\$1WORKLOAD\$1NAME* をワークロードの値に置き換えます。 + Java ワークロードの場合: ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-java": "true"}}}}}' ``` + Python ワークロードの場合: ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-python": "true"}}}}}' ``` Python アプリケーションには、追加で必要な設定があります。詳細については、「[Application Signals を有効にしたが、その後、Python アプリケーションを起動できない](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)」を参照してください。 + .NET ワークロードの場合: ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"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 ワークロードの場合: ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-nodejs": "true"}}}}}' ``` 1. 名前空間内のすべてのワークロードにアノテーションを追加するには、次のいずれかのコマンドを入力します。*\$1NAMESPACE* を名前空間の名前に置き換えます。 名前空間に Java、Python、および .NET ワークロードが含まれている場合は、すべての注釈を名前空間に追加します。 + 名前空間に Java ワークロードがある場合: ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-java=true ``` + 名前空間に Python ワークロードがある場合: ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-python=true ``` Python アプリケーションには、追加で必要な設定があります。詳細については、「[Application Signals を有効にしたが、その後、Python アプリケーションを起動できない](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)」を参照してください。 + 名前空間に .NET ワークロードがある場合: ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-dotnet=true ``` + 名前空間に Node.js ワークロードがある場合: ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-nodejs=true ``` アノテーションを追加したら、次のコマンドを入力して、名前空間内のすべてのポッドを再起動します。 ``` kubectl rollout restart ``` 1. 前のステップが完了したら、CloudWatch コンソールで、**[Application Signals]**、**[サービス]** の順に選択します。ダッシュボードが開いて、Application Signals が収集したデータが表示されます。データが表示されるまでに数分かかる場合があります。 **[サービス]** ビューの詳細については、「[Application Signals を使用したアプリケーションの運用状態のモニタリング](Services.md)」を参照してください。 ### ESM モジュール形式を使用する Node.js アプリケーションをセットアップする ESM モジュール形式を使用する Node.js アプリケーションには限定的なサポートが提供されます。詳細については、「[EMS を使用する ENode.js における既知の制限事項](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)」を参照してください。 ESM モジュール形式において、マニフェストファイルに注釈を付けて 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 ``` 1. アプリケーションの 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"] ``` 1. 環境変数 `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 it 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)" ``` 1. Node.js アプリケーションを Kubernetes クラスターにデプロイします。 ## (オプション) ステップ 5: アプリケーションの状態をモニタリングする Kubernetes でアプリケーションを有効にすると、アプリケーションの状態をモニタリングできます。詳細については、「[Application Signals を使用したアプリケーションの運用状態のモニタリング](Services.md)」を参照してください。