使用 Amazon CloudWatch Observability EKS 附加组件或 Helm 图表安装 CloudWatch 代理 - Amazon CloudWatch

使用 Amazon CloudWatch Observability EKS 附加组件或 Helm 图表安装 CloudWatch 代理

您可以使用 Amazon CloudWatch 可观测性 EKS 加载项或 Amazon CloudWatch 可观测性 Helm 图表,在 Amazon EKS 集群上安装 CloudWatch 代理和 Fluent-bit 代理。您还可以使用 Helm 图表在未托管在 Amazon EKS 上的 Kubernetes 集群上安装 CloudWatch 代理和 Fluent-bit 代理。

默认情况下,在 Amazon EKS 集群上使用任一方法均可启用具有增强 Amazon EKS 可观测性的 Container InsightsCloudWatch Application Signals。这两项功能都可以帮助您从集群收集基础设施指标、应用程序性能遥测和容器日志。

借助针对 Amazon EKS 增强了可观测性的 Container Insights,Container Insights 指标按每次观测收费,而不是按存储的指标或摄取的日志收费。对于 Application Signals,计费基于应用程序的入站请求、来自应用程序的出站请求以及每个配置的服务级别目标(SLO)。收到的每个入站请求都会生成一个应用程序信号,而发出的每个出站请求都会生成一个应用程序信号。每个 SLO 在每个测量周期内创建两个应用程序信号。有关 CloudWatch 定价的信息,请参阅 Amazon CloudWatch 定价

这两种方法均可在 Amazon EKS 集群中的 Linux 和 Windows Worker 节点上启用 Container Insights。要在 Windows 上启用 Container Insights,您必须使用 Amazon EKS 加载项或 Helm 图表的 1.5.0 版或更高版本。目前,Amazon EKS 集群中的 Windows 不支持 Application Signals。

运行 Kubernetes 版本 1.23 或更高版本的 Amazon EKS 集群支持 Amazon CloudWatch Observability EKS 附加组件。

安装加载项或 Helm 图表时,还必须授予 IAM 权限,让 CloudWatch 代理能够向 CloudWatch 发送指标、日志和跟踪。有两种方式可执行此操作:

  • 将策略附加到 Worker 节点的 IAM 角色。此选项会向 Worker 节点授予向 CloudWatch 发送遥测数据的权限。

  • 对代理容器组(pod)的服务账户使用 IAM 角色,并将策略附加到此角色。这仅适用于 Amazon EKS 集群。此选项仅允许 CloudWatch 访问相应的代理容器组(pod)。

选项 1:使用 IAM 权限在 Worker 节点上进行安装

要使用此方法,请先输入以下命令,将 CloudWatchAgentServerPolicy IAM 策略附加到您的 Worker 节点上。在此命令中,将 my-worker-node-role 替换为您的 Kubernetes Worker 节点使用的 IAM 角色。

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

然后安装 Amazon CloudWatch Observability EKS 附加组件。要安装该附加组件,您可以使用 AWS CLI、控制台、AWS CloudFormation 或 Terraform。

AWS CLI
使用 AWS CLI 安装 Amazon CloudWatch Observability EKS 附加组件

输入以下 命令。将 my-cluster-name 替换为您的集群名称。

aws eks create-addon --addon-name amazon-cloudwatch-observability --cluster-name my-cluster-name
Amazon EKS console
使用 Amazon EKS 控制台添加 Amazon CloudWatch Observability EKS 附加组件
  1. 访问 https://console.aws.amazon.com/eks/home#/clusters 打开 Amazon EKS 控制台。

  2. 在左侧导航窗格中,选择集群

  3. 选择要为其配置 Amazon CloudWatch Observability EKS 附加组件的集群名称。

  4. 选择附加组件选项卡。

  5. 选择获取更多附加组件

  6. 选择附加组件页面上,执行以下操作:

    1. Amazon EKS 插件部分中,选中 Amazon CloudWatch Observability 复选框。

    2. 选择下一步

  7. 配置选定的附加组件设置页面上,执行以下操作:

    1. 选择您想使用的 Version(版本)

    2. 对于选择 IAM 角色,选择从节点继承

    3. (可选)展开可选配置设置。如果对冲突解决方法选择覆盖,则可能用 Amazon EKS 附加组件设置覆盖现有附加组件的一个或多个设置。如果不启用此选项,并且与现有设置存在冲突,则操作将失败。您可以使用生成的错误消息对冲突进行故障排除。在选择此选项之前,请确保 Amazon EKS 附加组件不会管理您需要自行管理的设置。

    4. 选择下一步

  8. 查看和添加页面上,选择创建。附加组件安装完成后,您将看到已安装的附加组件。

AWS CloudFormation
使用 AWS CloudFormation 安装 Amazon CloudWatch Observability EKS 附加组件

my-cluster-name 替换为您的集群名称。有关更多信息,请参阅 AWS::EKS::Addon

{ "Resources": { "EKSAddOn": { "Type": "AWS::EKS::Addon", "Properties": { "AddonName": "amazon-cloudwatch-observability", "ClusterName": "my-cluster-name" } } } }
Helm chart
使用 amazon-cloudwatch-observability Helm 图表
  1. 您必须安装 Helm 才能使用此图表。有关安装 Helm 的更多信息,请参阅 Helm 文档

  2. 安装 Helm 后,输入以下命令。将 my-cluster-name 替换为集群的名称,并将 my-cluster-region 替换为集群在其中运行的区域。

    helm repo add aws-observability https://aws-observability.github.io/helm-charts helm repo update aws-observability helm install --wait --create-namespace --namespace amazon-cloudwatch amazon-cloudwatch-observability aws-observability/amazon-cloudwatch-observability --set clusterName=my-cluster-name --set region=my-cluster-region
Terraform
使用 Terraform 安装 Amazon CloudWatch Observability EKS 附加组件

my-cluster-name 替换为您的集群名称。有关更多信息,请参阅 Resource: aws_eks_addon

resource "aws_eks_addon" "example" { addon_name = "amazon-cloudwatch-observability" cluster_name = "my-cluster-name" }

选项 2:使用 IAM 服务账户角色进行安装(仅适用于使用加载项的情况)

仅当您使用的是 Amazon CloudWatch 可观测性 EKS 加载项时,此方法才有效。在使用此方法之前,请验证以下先决条件:

  • 在某个支持 Container Insights 的 AWS 区域 中,您具有运行正常并附加了节点的 Amazon EKS 集群。有关支持的区域列表,请参阅Container Insights

  • 您已经为集群安装并配置 kubectl。有关更多信息,请参阅 Amazon EKS 用户指南 中的安装 kubectl

  • 您已安装 eksctl。有关更多信息,请参阅《Amazon EKS 用户指南》中的安装或更新 eksctl

使用 IAM 服务账户角色安装 Amazon CloudWatch Observability EKS 附加组件
  1. 如果集群还没有 OpenID Connect(OIDC)提供程序,请输入以下命令来创建一个。有关更多信息,请参阅《Amazon EKS 用户指南》中的配置 Kubernetes 服务账户以代入 IAM 角色

    eksctl utils associate-iam-oidc-provider --cluster my-cluster-name --approve
  2. 输入以下命令以创建附加了 CloudWatchAgentServerPolicy 策略的 IAM 角色,然后使用 OIDC 将代理服务账户配置为代入该角色。将 my-cluster-name 替换为您的集群名称,并将 my-service-account-role 替换为要将服务账户关联到的角色名称。如果角色尚不存在,eksctl 会为您创建它。

    eksctl create iamserviceaccount \ --name cloudwatch-agent \ --namespace amazon-cloudwatch --cluster my-cluster-name \ --role-name my-service-account-role \ --attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \ --role-only \ --approve
  3. 通过输入以下命令安装附加组件。将 my-cluster-name 替换为您的集群名称,将 111122223333 替换为账户 ID,并将 my-service-account-role 替换为在上一步中创建的 IAM 角色。

    aws eks create-addon --addon-name amazon-cloudwatch-observability --cluster-name my-cluster-name --service-account-role-arn arn:aws:iam::111122223333:role/my-service-account-role

(可选)其他配置

选择不收集容器日志

默认情况下,该附加组件使用 Fluent Bit 从所有容器组(pod)收集容器日志,然后将日志发送到 CloudWatch Logs。有关收集哪些日志的信息,请参阅 设置 Fluent Bit

注意

加载项或 Helm 图表都不会管理集群中现有的 Fluentd 或 Fluent Bit 资源。在安装加载项或 Helm 图表之前,您可以删除现有的 Fluentd 或 Fluent Bit 资源。或者,要保留现有设置并避免加载项或 Helm 图表同时安装 Fluent Bit,您可以按照本节中的说明将其禁用。

要在使用 Amazon CloudWatch 可观测性 EKS 加载项时选择不收集容器日志,请在创建或更新加载项时传递以下选项:

--configuration-values '{ "containerLogs": { "enabled": false } }'

要在使用 Helm 图表时选择不收集容器日志,请在创建或更新加载项时传递以下选项:

--set containerLogs.enabled=false

使用自定义 Fluent Bit 配置

从 Amazon CloudWatch 可观测性 EKS 加载项的 1.7.0 版本开始,您可以在创建或更新加载项或 Helm 图表时修改 Fluent Bit 配置。您可以在加载项高级配置的 containerLogs 根级别部分提供自定义 Fluent Bit 配置,或者在 Helm 图表中提供覆盖值。在本节中,您可以在 config 部分(Linux)或 configWindows 部分(Windows)中提供自定义 Fluent Bit 配置。config 进一步细分为以下子部分:

  • service:本部分表示用于定义 Fluent Bit 引擎全局行为的 SERVICE 配置。

  • customParsers:本部分表示您想要包含的任何全局 PARSER,其能够获取非结构化日志条目,并为这些条目提供结构,使其更易于处理和进一步筛选。

  • extraFiles:本部分可用于提供要包含的其他 Fluent Bit conf 文件。默认情况下,包含以下 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 上的 System winlogs 发送到 CloudWatch Logs 中的日志组 /aws/containerinsights/my-cluster-name/hostconf 文件。

注意

即使您只修改某个子部分的一个字段,也要为这些单独的部分提供完整配置。建议您使用下面提供的默认配置作为基准,然后对其进行相应的修改,这样您就不会禁用默认已启用的功能。在修改 Amazon EKS 加载项的高级配置或为 Helm 图表提供覆盖值时,您可以使用以下 YAML 配置。

要查找集群的 config 部分,请参阅 GitHub 上的 aws-observability / helm-charts,并找到与您安装的加载项或 Helm 图表版本相对应的版本。然后导航到 /charts/amazon-cloudwatch-observability/values.yaml,在 containerLogs 下的 fluentBit 部分中找到 config 部分(Linux)和 configWindows 部分(Windows)。

例如,可以在此处找到版本 1.7.0 的默认 Fluent Bit 配置。

建议您在使用 Amazon EKS 加载项的高级配置提供 YAML 或者在安装 Helm 时将其作为覆盖值提供时,将 config 作为 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 bit conf 文件。在此示例中,我们在 extraFiles 下添加一个自定义 my-service.conf,它将与三个默认 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

下一个示例将从 extraFiles 中完全删除现有的 conf 文件。该示例用空字符串覆盖 application-log.conf,从而将其完全排除在外。仅仅忽略 extraFilesapplication-log.conf 意味着使用默认值,这不是我们在本示例中尝试实现的目标。这同样适用于删除您之前可能已添加到 extraFiles 的任何自定义 conf 文件。

containerLogs: fluentBit: config: extraFiles: application-log.conf: ""

管理已安装容器组(pod)工作负载的 Kubernetes 容忍度

从 Amazon CloudWatch 可观测性 EKS 加载项的 1.7.0 版本开始,加载项和 Helm 图表默认将 Kubernetes 容忍度设置为容忍加载项或 Helm 图表安装的容器组(pod)工作负载上的所有污点。这可确保 CloudWatch 代理和 Fluent Bit 等守护程序集默认可以在集群中的所有节点上安排容器组(pod)。有关污点和容忍度的更多信息,请参阅 Kubernetes 文档中的污点和容忍度

加载项或 Helm 图表设置的默认容忍度如下:

tolerations: - operator: Exists

您可以在使用加载项高级配置或安装或升级具有覆盖值的 Helm 图表时,通过在根级别设置 tolerations 字段来覆盖默认容忍度。示例将如下所示:

tolerations: - key: "key1" operator: "Exists" effect: "NoSchedule"

要完全忽略容忍度,您可以使用如下配置:

tolerations: []

对容忍度的任何更改都将应用于加载项或 Helm 图表安装的所有容器组(pod)工作负载。

选择退出加速计算指标收集

默认情况下,具有增强可观测性的 Container Insights 会收集加速计算监控的指标,包括 NVIDIA GPU 指标、AWS Trainium 和 AWS Inferentia 的 AWS Neuron 指标以及 AWS Elastic Fabric Adapter(EFA)指标。

从 EKS 加载项或 Helm 图表的版本 v1.3.0-eksbuild.1 以及 CloudWatch 代理的版本 1.300034.0 开始,默认收集来自 Amazon EKS 工作负载的 NVIDIA GPU 指标。有关收集的指标和先决条件的列表,请参阅 NVIDIA GPU 指标

从 EKS 加载项或 Helm 图表的版本 v1.5.0-eksbuild.1 以及 CloudWatch 代理的版本 1.300036.0 开始,默认收集 AWS Trainium 和 AWS Inferentia 加速器的 AWS Neuron 指标。有关收集的指标和先决条件的列表,请参阅 AWS Trainium 和 AWS Inferentia 的 AWS Neuron 指标

从 EKS 加载项或 Helm 图表的版本 v1.5.2-eksbuild.1 以及 CloudWatch 代理的版本 1.300037.0 开始,默认收集来自 Amazon EKS 集群 Linux 节点的 AWS Elastic Fabric Adapter(EFA)指标。有关收集的指标和先决条件的列表,请参阅 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 处于启用状态。为此,请将 CloudWatch 代理配置文件嵌入到高级配置(您可以在创建或更新 EKS 加载项或 Helm 图表时使用该配置)代理键下的配置键中。以下是您未提供任何其他配置时的默认代理配置。

重要

您使用其他配置设置提供的任何自定义配置都会覆盖代理使用的默认配置。请注意不要无意中禁用默认启用的功能,例如可观测性经增强的 Container Insights 和 CloudWatch Application Signals。在需要提供自定义代理配置的情况下,我们建议使用以下默认配置作为基准,然后对其进行相应的修改。

  • 使用 Amazon CloudWatch 可观测性 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 }, } } }

管理准入 webhook TLS 证书

Amazon CloudWatch 可观测性 EKS 加载项和 Helm 图表利用 Kubernetes 准入 webhook 来验证和更改 AmazonCloudWatchAgentInstrumentation 自定义资源(CR)请求,如果启用了 CloudWatch Application Signals,还可以选择在集群上验证和更改 Kubernetes 容器组(pod)请求。在 Kubernetes 中,webhook 需要一个 TLS 证书,API 服务器配置为信任该证书,以确保安全通信。

默认情况下,Amazon CloudWatch 可观测性 EKS 加载项和 Helm 图表会自动生成自签名 CA 和由此 CA 签名的 TLS 证书,以确保 API 服务器和 webhook 服务器之间的安全通信。此自动生成的证书的默认有效期为 10 年,到期后不会自动续订。此外,每次升级或重新安装加载项或 Helm 图表时,都会重新生成 CA 捆绑包和证书,从而重置有效期。如果要更改自动生成的证书的默认有效期,则可以在创建或更新附加组件时使用以下其他配置。将 expiry-in-days 替换为所需的有效期持续时间(以天为单位)。

  • 将此内容用于 Amazon CloudWatch 可观测性 EKS 加载项

    --configuration-values '{ "admissionWebhooks": { "autoGenerateCert": { "expiryDays": expiry-in-days } } }'
  • 将此内容用于 Helm 图表

    --set admissionWebhooks.autoGenerateCert.expiryDays=expiry-in-days

为了获得更安全、功能更丰富的证书颁发机构解决方案,该附加组件支持选择加入 cert-manager,这是一种在 Kubernetes 中广泛采用的 TLS 证书管理解决方案,可简化获取、续订、管理和使用这些证书的过程。此解决方案可确保证书有效且最新,并尝试在证书到期前的配置时间续订证书。cert-manager 还便于从各种支持的来源(包括 AWS Certificate Manager 私有证书颁发机构)颁发证书。

我们建议您查看集群上管理 TLS 证书的最佳实践,并建议您选择使用针对生产环境的 cert-manager。请注意,如果您通过选择加入来启用 cert-manager,以便管理准入 webhook TLS 证书,则您需要在安装 Amazon CloudWatch 可观测性 EKS 加载项或 Helm 图表之前,在 Amazon EKS 集群上预安装 cert-manager。有关可用安装选项的更多信息,请参阅 cert-manager 文档。安装完成后,您可以使用以下附加配置选择使用 cert-manager 来管理准入 webhook TLS 证书。

  • 如果使用 Amazon CloudWatch 可观测性 EKS 加载项

    --configuration-values '{ "admissionWebhooks": { "certManager": { "enabled": true } } }'
  • 如果您使用的是 Helm 图表

    --set admissionWebhooks.certManager.enabled=true
--configuration-values '{ "admissionWebhooks": { "certManager": { "enabled": true } } }'

默认情况下,本节中讨论的高级配置将使用 SelfSigned 颁发者。

收集 Amazon EBS 卷 ID

如果您希望在性能日志中收集 Amazon EBS 卷 ID,则必须向附加到 Worker 节点或服务账户的 IAM 角色添加另一个策略。添加以下内容作为内联策略。有关更多信息,请参阅添加和删除 IAM 身份权限

{ "Version": "2012-10-17", "Statement": [ { "Action": [ "ec2:DescribeVolumes" ], "Resource": "*", "Effect": "Allow" } ] }

Amazon CloudWatch 可观测性 EKS 加载项或 Helm 图表问题排查

可以使用以下信息帮助对 Amazon CloudWatch 可观测性 EKS 加载项或 Helm 图表的问题进行排查

更新和删除 Amazon CloudWatch 可观测性 EKS 加载项或 Helm 图表

有关更新或删除 Amazon CloudWatch Observability EKS 附加组件的说明,请参阅管理 Amazon EKS 附加组件。使用 amazon-cloudwatch-observability 作为附加组件的名称。

要删除集群中的 Helm 图表,请输入以下命令。

helm delete amazon-cloudwatch-observability -n amazon-cloudwatch --wait

验证 Amazon CloudWatch 可观测性 EKS 加载项或 Helm 图表使用的 CloudWatch 代理版本

Amazon CloudWatch 可观测性 EKS 加载项和 Helm 图表安装 AmazonCloudWatchAgent 类型的自定义资源,用于控制集群上 CloudWatch 代理守护程序集的行为,包括正在使用的 CloudWatch 代理的版本。您可以通过输入以下命令获取集群 u 上安装的所有 AmazonCloudWatchAgent 自定义资源的列表:

kubectl get amazoncloudwatchagent -A

在此命令的输出中,您应该能够检查 CloudWatch 代理的版本。或者,您也可以描述集群上运行的 amazoncloudwatchagent 资源或其中一个 cloudwatch-agent-* 容器组(pod)来检查正在使用的映像。

管理加载项或 Helm 图表时处理 ConfigurationConflict

在安装或更新 Amazon CloudWatch 可观测性 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 可观测性 EKS 加载项,但出现此故障,则建议您删除之前在集群上安装的现有 CloudWatch 代理设置,然后安装 EKS 加载项或 Helm 图表。请务必备份您可能对原始 CloudWatch 代理设置所做的任何自定义,例如自定义代理配置,并在下次安装或更新时将其提供给加载项或 Helm 图表。如果您之前安装了 CloudWatch 代理以载入 Container Insights,请参阅 删除 Container Insights 的 CloudWatch 代理和 Fluent Bit 获取更多信息。

或者,该附加组件支持具有指定 OVERWRITE 功能的冲突解决配置选项。您可以使用此选项,通过覆盖集群上的冲突来继续安装或更新附加组件。如果您使用的是 Amazon EKS 控制台,则在创建或更新附加组件时选择可选配置设置时,会找到冲突解决方法。如果您使用的是 AWS CLI,则可以在命令中提供 --resolve-conflicts OVERWRITE,以创建或更新附加组件。