Amazon CloudWatch Observability EKS アドオンまたは Helm チャートを使用して CloudWatch エージェントをインストールする
Amazon CloudWatch Observability EKS アドオンまたは Amazon CloudWatch Observability Helm チャートを使用して、Amazon EKS クラスターに CloudWatch エージェントと Fluent Bit エージェントをインストールできます。また、Helm チャートを使用して、Amazon EKS でホストされていない Kubernetes クラスターに CloudWatch エージェントと Fluent Bit エージェントをインストールすることもできます。
Amazon EKS クラスターでこのいずれかの方法を使用すると、デフォルトで Amazon EKS と CloudWatch Application Signals の両方の Container Insights がオブザーバビリティが強化されたうえで有効になります。どちらの機能を使用しても、クラスターからインフラストラクチャメトリクス、アプリケーションパフォーマンステレメトリ、コンテナログを容易に収集できます。
Amazon EKS 向けにオブザーバビリティが強化された Container Insights では、観察結果ごと Container Insights メトリクスに課金されます。保存されたメトリクスまたは取り込まれたログごとには課金されません。Application Signals の場合、アプリケーションへのインバウンドリクエスト、アプリケーションからのアウトバウンドリクエスト、設定された各サービスレベル目標 (SLO) に基づいて、請求が行われます。インバウンドリクエストを受信するたびにアプリケーションシグナルが 1 つ生成され、アウトバウンドリクエストが発生するたびにアプリケーションシグナルが 1 つ生成されます。各 SLO は、測定間隔ごとにアプリケーションシグナルを 2 つ作成します。CloudWatch の料金の詳細については、Amazon CloudWatch の料金
どちらの方法を使用しても、Amazon EKS クラスターの Linux と Windows の両方のワーカーノードで Container Insights を有効にできます。Windows で Container Insights を有効にするには、Amazon EKS アドオンのバージョン 1.5.0 以降を使用するか、Helm チャートを使用する必要があります。現在、Amazon EKS クラスターの Windows では、Application Signals はサポートされていません。
Amazon CloudWatch Observability EKS アドオンは、Kubernetes バージョン 1.23 以降で Amazon EKS クラスターを実行している場合にサポートされます。
また、このアドオンまたは Helm チャートをインストールするときは、IAM アクセス許可を付与して、CloudWatch エージェントが CloudWatch にメトリクス、ログ、トレースを送信できるようにする必要があります。次の 2 通りの方法があります。
ワーカーノードの IAM ロールにポリシーをアタッチします。このオプションは、テレメトリを CloudWatch に送信するアクセス許可をワーカーノードに付与します。
エージェントポッドでサービスアカウントの IAM ロールを使用し、このロールにポリシーをアタッチします。これは Amazon EKS クラスターでのみ機能します。このオプションでは、CloudWatch は適切なエージェントポッドにのみアクセスできます。
オプション 1: ワーカーノードで IAM のアクセス許可を使用してインストールする
この方法を使用するには、まず次のコマンドを入力して IAM ポリシー CloudWatchAgentServerPolicy をワーカーノードにアタッチします。このコマンドでは、my-worker-node-role を Kubernetes ワーカーノードが使用する IAM ロールに置き換えます。
aws iam attach-role-policy \ --role-namemy-worker-node-role\ --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
Amazon CloudWatch Observability EKS アドオンをインストールします。アドオンをインストールするには、AWS CLI、コンソール、AWS CloudFormation または Terraform を使用できます。
オプション 2: IAM サービスアカウントロールを使用してインストールする (アドオンを使用する場合のみ)
この方法は、Amazon CloudWatch Obeservability EKS アドオンを使用している場合にのみ有効です。この方法を使用する前に、次の前提条件を確認してください。
-
Container Insights がサポートされているいずれかの AWS リージョン に、ノードがアタッチされ機能している Amazon EKS クラスターがある。サポートされているリージョンのリストについては、「Container Insights」を参照してください。
-
クラスターに
kubectlがインストールされ、設定されている。詳細については、Amazon EKS ユーザーガイドの「kubectlのインストール」を参照してください。 -
eksctlがインストールされている。詳細については、「Amazon EKS ユーザーガイド」の「Installing or updatingeksctl」を参照してください。
IAM サービスアカウントロールを使用して Amazon CloudWatch Observability EKS アドオンをインストールするには
クラスターに OpenID Connect (OIDC) プロバイダーがない場合、次のコマンドを入力して作成します。詳細については、「Amazon EKS ユーザーガイド」の「Configuring a Kubernetes service account to assume an IAM role」を参照してください。
eksctl utils associate-iam-oidc-provider --clustermy-cluster-name--approve次のコマンドを入力してポリシー CloudWatchAgentServerPolicy がアタッチされた IAM ロールを作成し、OIDC を使用してそのロールを引き受けるようにエージェントのサービスアカウントを設定します。
my-cluster-nameをクラスターの名前、my-service-account-roleをサービスアカウントを関連付けるロールの名前に置き換えます。ロールがまだ存在しない場合は、eksctlによって作成されます。eksctl create iamserviceaccount \ --name cloudwatch-agent \ --namespace amazon-cloudwatch --clustermy-cluster-name\ --role-namemy-service-account-role\ --attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \ --role-only \ --approve次のコマンドを入力して、アドオンをインストールします。
my-cluster-nameをクラスターの名前、111122223333をアカウント ID、my-service-account-roleを前の手順で作成したIAM ロールに置き換えます。aws eks create-addon --addon-name amazon-cloudwatch-observability --cluster-namemy-cluster-name--service-account-role-arn arn:aws:iam::111122223333:role/my-service-account-role
(オプション) その他の設定
トピック
コンテナログの収集をオプトアウトする
デフォルトでは、アドオンは Fluent Bit を使用してすべてのポッドからコンテナログを収集し、そのログを CloudWatch Logs に送信します。収集されるログについての詳細は、「Fluent Bit の設定」を参照してください。
注記
アドオンも Helm チャートも、クラスター内の既存の Fluentd リソースや Fluent Bit リソースを管理しません。アドオンや Helm チャートをインストールする前に、既存の Fluentd や Fluent Bit リソースを削除できます。あるいは、既存のセットアップを維持し、アドオンや Helm チャートから Fluent Bit もインストールされないようにするには、このセクションの指示に従ってこうしたインストールを無効にできます。
Amazon CloudWatch Observability EKS アドオンを使用している場合に、コンテナログの収集をオプトアウトするには、アドオンの作成時または更新時に次のオプションを渡します。
--configuration-values '{ "containerLogs": { "enabled": false } }'
Helm チャートを使用している場合に、コンテナログの収集をオプトアウトするには、アドオンの作成時または更新時に次のオプションを渡します。
--set containerLogs.enabled=false
カスタム Fluent Bit 設定を使用する
Amazon CloudWatch Observability EKS アドオンのバージョン 1.7.0 以降では、アドオンや Helm チャートを作成または更新するときに Fluent Bit 設定を変更できます。こうしてカスタマイズした Fluent Bit 設定は、アドオンでは詳細設定の containerLogs ルートレベルセクションで指定し、Helm チャートでは値のオーバーライドで指定します。このセクションでは、カスタマイズした Fluent Bit 設定を config セクション (Linux の場合) または configWindows セクション (Windows の場合) で指定します。config は、さらに次のサブセクションに分かれています。
service–SERVICE設定を表すセクションであり、Fluent Bit エンジンのグローバルな動作を定義します。customParsers- グローバルなPARSERを表すセクションであり、これを含めると非構造化ログエントリを取得して、ログの処理とその後のフィルタリングが容易になるように構造化できます。extraFiles- Fluent Bitconfファイルを追加で含めることができるセクションです。デフォルトでは、次の 3 つのconfファイルが含まれています。application-log.conf– クラスターから CloudWatch Logs 内のロググループ/aws/containerinsights/にアプリケーションログを送信するためのmy-cluster-name/applicationconfファイル。dataplane-log.conf– CRI ログ、kubelet ログ、kube-proxy ログ、Amazon VPC CNI ログなど、クラスターのデータプレーンコンポーネントに対応するログを CloudWatch Logs のロググループ/aws/containerinsights/に送信するためのmy-cluster-name/dataplaneconfファイル。host-log.conf– Linux 上の/var/log/dmesg、/var/log/messages、/var/log/secureと、Windows 上の Systemwinlogsから CloudWatch のロググループ/aws/containerinsights/にログを送信するためのmy-cluster-name/hostconfファイル。
注記
サブセクション内のフィールドを 1 つだけ変更する場合でも、上記の個々のセクションをすべて設定してください。デフォルトで有効になっている機能を無効にすることがないように、下記に示したデフォルト設定をベースラインとして使用し、そのうえで適宜変更を加えることをお勧めします。Amazon EKS アドオンの詳細設定を変更するときや、Helm チャートの値のオーバーライドを指定するときには、以下の YAML 設定を使用できます。
クラスターの config セクションを確認するには、GitHub の aws-observability / helm-charts/charts/amazon-cloudwatch-observability/values.yaml に移動して、fluentBit セクション内の containerLogs で config セクション (Linux の場合) および configWindows セクション (Windows の場合) を探します。
例えば、バージョン 1.7.0 のデフォルトの Fluent Bit 設定は、ここで
config を、Amazon EKS アドオンの詳細設定を使用して指定する場合や、Helm インストールの値のオーバーライドとして指定する場合は、YAML として指定することをお勧めします。YAML が次の構造に準拠していることを確認してください。
containerLogs: fluentBit: config: service: | ... customParsers: | ... extraFiles: application-log.conf: | ... dataplane-log.conf: | ... host-log.conf: | ...
次の例では、config はフラッシュ間隔のグローバル設定を 45 秒に変更します。Flush フィールドへの変更はこれだけですが、サービスサブセクション全体に対する SERVICE 定義を指定する必要があります。この例では、他のサブセクションにオーバーライドを指定しなかったため、そのサブセクションではデフォルトが使用されます。
containerLogs: fluentBit: config: service: | [SERVICE] Flush 45 Grace 30 Log_Level error Daemon off Parsers_File parsers.conf storage.path /var/fluent-bit/state/flb-storage/ storage.sync normal storage.checksum off storage.backlog.mem_limit 5M
次の設定例には、追加で Fluent ビット conf ファイルが含まれています。この例では、extraFiles の下にカスタム my-service.conf を追加しており、3 つのデフォルトの extraFiles に加えて、このファイルが含まれます。
containerLogs: fluentBit: config: extraFiles: my-service.conf: | [INPUT] Name tail Tag myservice.* Path /var/log/containers/*myservice*.log DB /var/fluent-bit/state/flb_myservice.db Mem_Buf_Limit 5MB Skip_Long_Lines On Ignore_Older 1d Refresh_Interval 10 [OUTPUT] Name cloudwatch_logs Match myservice.* region ${AWS_REGION} log_group_name /aws/containerinsights/${CLUSTER_NAME}/myservice log_stream_prefix ${HOST_NAME}- auto_create_group true
次の例では、既存の conf ファイルを extraFiles から完全に削除しています。空の文字列で上書きすることで、application-log.conf 全体が除外されます。extraFiles から application-log.conf を省いてもデフォルトの使用を示唆するだけであり、この例で示そうとしているのはそういうことではありません。同じことが、以前にカスタマイズして extraFiles に追加した conf ファイルを削除するといった場合にも言えます。
containerLogs: fluentBit: config: extraFiles: application-log.conf: ""
インストールされたポッドワークロードの Kubernetes 許容範囲を管理する
Amazon CloudWatch Observability EKS アドオンのバージョン 1.7.0 以降、アドオンと Helm チャートはアドオンまたは Helm チャートがインストールするポッドワークロード上ですべてのテイントを許容するようにデフォルトで Kubernetes の許容範囲を設定します。これにより、CloudWatch エージェントや Fluent Bit などのデーモンセットは、デフォルトでクラスター内のすべてのノードでポッドをスケジュールできるようになります。許容範囲とテイントの詳細については、Kubernetes ドキュメントの「Taints and Tolerations
アドオンまたは Helm チャートによってデフォルトで設定される許容範囲は次のとおりです。
tolerations: - operator: Exists
アドオンの詳細設定を使用するときや、値のオーバーライドで Helm チャートをインストールまたはアップグレードするときに、tolerations フィールドをルートレベルで設定することで、デフォルトの許容範囲を上書きできます。例えば、次のようになります。
tolerations: - key: "key1" operator: "Exists" effect: "NoSchedule"
許容範囲を完全に省略するには、次のような設定を使用できます。
tolerations: []
許容範囲に加えた変更は、アドオンまたは Helm チャートがインストールするすべてのポッドワークロードに適用されます。
高速コンピューティングメトリクスの収集をオプトアウトする
オブザーバビリティが強化された Container Insights は、デフォルトでは高速化コンピューティングのモニタリングのためにメトリクスを収集します。NVIDIA GPU メトリクス、AWS Trainium と AWS Inferentia の AWS Neuron メトリクス、AWS Elastic Fabric Adapter (EFA) メトリクスなどです。
Amazon EKS ワークロードの NVIDIA GPU メトリクスは、デフォルトではバージョン v1.3.0-eksbuild.1 の EKS アドオンまたは Helm チャート、およびバージョン 1.300034.0 の CloudWatch エージェントから収集されます。収集されたメトリクスと前提条件のリストについては、「NVIDIA GPU メトリクス」を参照してください。
AWS Trainium および AWS Inferentia アクセラレーターの AWS Neuron メトリクスは、バージョン v1.5.0-eksbuild.1 の EKS アドオンまたは Helm チャート、およびバージョン 1.300036.0 の CloudWatch エージェントから収集されます。収集されたメトリクスと前提条件のリストについては、「AWS Trainium と AWS Inferentia の AWS Neuron メトリクス 」を参照してください。
Amazon EKS クラスター上の Linux ノードの AWS Elastic Fabric Adapter (EFA) メトリクスは、デフォルトではバージョン v1.5.2-eksbuild.1 の EKS アドオンまたは Helm チャート、およびバージョン 1.300037.0 の CloudWatch エージェントから収集されます。収集されたメトリクスと前提条件のリストについては、「AWS Elastic Fabric Adapter (EFA) メトリクス 」を参照してください。
CloudWatch エージェント設定ファイルの accelerated_compute_metrics フィールドを false に設定することで、これらのメトリクスの収集をオプトアウトできます。このフィールドは、CloudWatch 設定ファイルの metrics_collected セクションの kubernetes セクションで利用できます。以下は、オプトアウトの設定の例です。カスタム CloudWatch エージェント設定の使用方法の詳細については、次のセクション「カスタム CloudWatch エージェント設定を使用する」を参照してください。
{ "logs": { "metrics_collected": { "kubernetes": { "enhanced_container_insights": true, "accelerated_compute_metrics": false } } } }
カスタム CloudWatch エージェント設定を使用する
CloudWatch エージェントを使用して他のメトリクスやログやトレースを収集するには、Container Insights と CloudWatch Application Signals を有効にしたままカスタム設定を指定します。そのためには、EKS アドオンや Helm チャートを作成または更新するときに使用できる詳細設定を開き、エージェントキーの下にある設定キー内に CloudWatch エージェント設定ファイルを埋め込みます。次に、デフォルトのまま他に設定を行わない場合のエージェント設定を示します。
重要
他に構成設定を行って設定をカスタマイズした場合は、そのカスタム設定がエージェントで使用されるデフォルト設定よりも優先されます。オブザーバビリティが強化された Container Insights や CloudWatch Application Signals など、デフォルトで有効になっている機能を意図せず無効にしないように注意してください。エージェント設定をカスタマイズしなければならない場合は、以下のデフォルト設定をベースラインとして使用し、適宜必要な変更を加えることをお勧めします。
Amazon CloudWatch Observability EKS アドオンを使用する場合
--configuration-values '{ "agent": { "config": { "logs": { "metrics_collected": { "application_signals": {}, "kubernetes": { "enhanced_container_insights": true } } }, "traces": { "traces_collected": { "application_signals": {} } } } }'-
Helm チャートを使用する場合
--set agent.config='{ "logs": { "metrics_collected": { "application_signals": {}, "kubernetes": { "enhanced_container_insights": true } } }, "traces": { "traces_collected": { "application_signals": {} } } }'
次の例は、Windows 上の CloudWatch エージェントのデフォルトエージェント設定を示しています。Windows 上の CloudWatch エージェントは、カスタム設定をサポートしていません。
{ "logs": { "metrics_collected": { "kubernetes": { "enhanced_container_insights": true }, } } }
アドミッションウェブフック TLS 証明書の管理
Amazon CloudWatch Observability EKS アドオンと Helm チャートは、Kubernetes アドミッションウェブフックAmazonCloudWatchAgent および Instrumentation カスタムリソース (CR) リクエストのほか、オプションで CloudWatch Application Signals が有効になっている場合にはクラスター上の Kubernetes ポッドリクエストも、検証したうえで必要な変更を加えます。Kubernetes の場合、安全な通信を確保するためには、API サーバーからの信頼が設定された TLS 証明書がウェブフックに必要です。
デフォルトでは、Amazon CloudWatch Observability EKS アドオンと Helm チャートは、API サーバーとウェブフックサーバー間の通信を保護するために、自己署名 CA とこの CA の署名入りの TLS 証明書を自動生成します。この自動生成された証明書の有効期限はデフォルトで 10 年で、有効期限は自動更新されません。また、このアドオンや Helm チャートがアップグレードされるか再インストールされるたびに、CA バンドルと証明書が再生成されるため、有効期限がリセットされます。自動生成された証明書のデフォルトの有効期限を変更する場合は、アドオンを作成または更新するときに以下のように追加の設定を行います。expiry-in-days を目的の有効期限 (日) に置き換えてください。
これを Amazon CloudWatch Observability EKS アドオンに使用する
--configuration-values '{ "admissionWebhooks": { "autoGenerateCert": { "expiryDays":expiry-in-days} } }'これを Helm チャートに使用する
--set admissionWebhooks.autoGenerateCert.expiryDays=expiry-in-days
安全性の高い多機能な証明機関を利用できるように、cert-manager
クラスターで TLS 証明書を管理する場合のベストプラクティスを確認すること、および本番環境では cert-manager を選択することをお勧めします。アドミッションウェブフック TLS 証明書を管理できるように cert-manager を有効にすることにした場合は、Amazon CloudWatch Observability EKS アドオンや Helm チャートをインストールする前に、Amazon EKS クラスターに cert-manager をプリインストールしておく必要があることに注意してください。使用可能なインストールオプションの詳細については、cert-manager のドキュメント
Amazon CloudWatch Observability EKS アドオンを使用している場合
--configuration-values '{ "admissionWebhooks": { "certManager": { "enabled": true } } }'Helm チャートを使用している場合
--set admissionWebhooks.certManager.enabled=true
--configuration-values '{ "admissionWebhooks": { "certManager": { "enabled": true } } }'
詳細設定では、ここで説明するように、デフォルトで自己署名
Amazon EBS ボリューム ID を収集する
パフォーマンスログで Amazon EBS ボリューム ID を収集する場合は、ワーカーノードまたはサービスアカウントにアタッチされた IAM ロールに別のポリシーを追加する必要があります。以下をインラインポリシーとして追加します。詳細については、「Adding and Removing IAM Identity Permissions」を参照してください。
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "ec2:DescribeVolumes" ], "Resource": "*", "Effect": "Allow" } ] }
Amazon CloudWatch Observability EKS アドオンや Helm チャートのトラブルシューティング
以下の情報を参考にして、Amazon CloudWatch Observability EKS アドオンや Helm チャートに関する問題のトラブルシューティングを行います。
トピック
Amazon CloudWatch Observability EKS アドオンや Helm チャートの更新と削除
Amazon CloudWatch Observability EKS アドオンを更新または削除する手順については、「Amazon EKS アドオンの管理」を参照してください。アドオン名には amazon-cloudwatch-observability を使用してください。
クラスター内の Helm チャートを削除するには、次のコマンドを入力します。
helm delete amazon-cloudwatch -n amazon-cloudwatch --wait
Amazon CloudWatch Observability EKS アドオンや Helm チャートで使用される CloudWatch エージェントのバージョンを確認する
Amazon CloudWatch Observability EKS アドオンと Helm チャートは、使用中の CloudWatch エージェントのバージョンなど、クラスター上の CloudWatch エージェントデーモンセットの動作を制御する AmazonCloudWatchAgent のカスタムリソースをインストールします。以下のコマンドを入力して、クラスターにインストールされている AmazonCloudWatchAgent カスタムリソースがすべて記載されたリストを取得できます。
kubectl get amazoncloudwatchagent -A
このコマンドの出力を調べれば、CloudWatch エージェントのバージョンを確認できるはずです。このほか、amazoncloudwatchagent リソースを記述するか、クラスターで動作しているいずれかの cloudwatch-agent-* ポッドを記述して、使用中のイメージを調べることもできます。
アドオンや Helm チャートの管理時の ConfigurationConflict の処理
Amazon CloudWatch Observability EKS アドオンや Helm チャートのインストールまたは更新時に、既存のリソースによって生じたエラーが見られたとします。これはおそらく、CloudWatch エージェントとその関連コンポーネント (ServiceAccount、ClusterRole、ClusterRoleBinding など) がクラスターにインストールされていることが原因と考えられます。
アドオンによって表示されるエラーには、Conflicts found when trying to apply. Will not continue due to resolve conflicts mode などがあります。
Helm チャートによって表示されるエラーは、Error: INSTALLATION FAILED: Unable to continue with install and invalid ownership metadata. のようになります。
このアドオンや Helm チャートによって CloudWatch エージェントとその関連コンポーネントがインストールされるときに内容の変更が検出されると、デフォルトではインストールまたは更新が失敗します。これによって、クラスター上にあるリソースの状態が上書きされることを防いでいます。
Amazon CloudWatch Observability EKS アドオンへのオンボード時にこのエラーが発生した場合は、クラスターにインストール済みの CloudWatch エージェントセットアップを削除した後に EKS アドオンや Helm チャートをインストールすると良いでしょう。カスタムエージェント設定など、元の CloudWatch エージェントセットアップへのカスタマイズを必ずバックアップし、アドオンや Helm チャートを次回インストールまたは更新するときにそれらのカスタマイズを適用してください。Container Insights へのオンボーディングを目的に CloudWatch エージェントをインストール済みである場合は、「Container Insights の CloudWatch エージェントと Fluent Bit の削除」で詳細を確認してください。
その他に、アドオンでサポートされている設定オプションで OVERWRITE を指定して競合を解決することも可能です。このオプションを使用すると、クラスター上の競合を上書きしてアドオンのインストールまたは更新を継続できます。Amazon EKS コンソールを使用する場合、アドオンの作成または更新時に [オプションの構成設定] を選択すると、[競合の解決方法] が表示されます。AWS CLI を使用する場合は、コマンドに --resolve-conflicts OVERWRITE を指定することで、アドオンを作成または更新できます。
