# 在 Amazon EKS 集群上启用应用程序
<a name="CloudWatch-Application-Signals-Enable-EKS"></a>

CloudWatch Application Signals 支持 Java、Python、Node.js 和 .NET 应用程序。您可以使用 AWS 管理控制台、AWS CDK 或 CloudWatch 可观测性附加组件的“自动监控”高级配置，为现有 Amazon EKS 集群上的应用程序启用 Application Signals。

**Topics**
+ [使用控制台在 Amazon EKS 集群上启用 Application Signals](#CloudWatch-Application-Signals-Enable-EKS-Console)
+ [使用 CloudWatch 可观测性附加组件的高级配置在 Amazon EKS 集群上启用 Application Signals](#CloudWatch-Application-Signals-Enable-EKS-Addon)
+ [使用 AWS CDK 在 Amazon EKS 上启用 Application Signals](#CloudWatch-Application-Signals-EKS-CDK)
+ [使用模型上下文协议（MCP）服务器在 Amazon EKS 上启用 Application Signals](#CloudWatch-Application-Signals-EKS-MCP)

## 使用控制台在 Amazon EKS 集群上启用 Application Signals
<a name="CloudWatch-Application-Signals-Enable-EKS-Console"></a>

要在现有 Amazon EKS 集群的应用程序上启用 CloudWatch Application Signals，请按照本节中的说明进行操作。

**重要**  
如果您已经在打算为 Application Signals 启用的应用程序中使用 OpenTelemetry，请在启用 Application Signals 之前参阅 [支持的系统](CloudWatch-Application-Signals-supportmatrix.md)。

**为现有 Amazon EKS 集群上的应用程序启用 Application Signals**
**注意**  
如果还没有启用 Application Signals，请按照[在账户中启用 Application Signals](CloudWatch-Application-Signals-Enable.md)中的说明操作，然后完成以下程序。

1. 通过 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 打开 CloudWatch 控制台。

1. 选择 **Application Signals**。

1. 在**指定平台**中，选择 **EKS**。

1. 在**选择 EKS 集群**中，选择要在其中启用 Application Signals 的集群。

1. 如果此集群尚未启用 Amazon CloudWatch Observability EKS 附加组件，则系统会提示您将其启用。在这种情况下，请执行以下操作：

   1. 选择**添加 CloudWatch Observability EKS 附加组件**。Amazon EKS 控制台出现。

   1. 选中 **Amazon CloudWatch Observability** 对应的复选框，然后选择**下一步**。

      CloudWatch Observability EKS 附加组件启用 Application Signals 和 CloudWatch Container Insights，从而增强 Amazon EKS 的可观测性。有关安装 Container Insights 的更多信息，请参阅 [Container Insights](ContainerInsights.md)。

   1. 选择要安装的最新版本的附加组件。

   1. 选择要用于附加组件的 IAM 角色。如果您选择**从节点继承**，请将正确的权限附加到您的 Worker 节点使用的 IAM 角色。将 *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 \
      --policy-arn arn:aws:iam::aws:policy/AWSXRayWriteOnlyAccess
      ```

   1. 如果您想要创建服务角色以使用附加组件，请参阅 [使用 Amazon CloudWatch Observability EKS 附加组件或 Helm 图表安装 CloudWatch 代理](install-CloudWatch-Observability-EKS-addon.md)。

   1. 选择**下一步**，确认屏幕上的信息，然后选择**创建**。

   1. 在下一个屏幕中，选择**启用 CloudWatch Application Signals** 以返回 CloudWatch 控制台并完成该过程。

1. 有两个选项可以为您的应用程序启用 Application Signals。为保持一致性，建议您为每个集群选择一个选项。
   + **控制台**选项更简单。使用此方法会导致您的容器组（pod）立即重启。
   + **注释清单文件**方法可以让您更好地控制容器组（pod）何时重启；如果您不想集中监控，还可以帮助您以更分散的方式管理监控。
**注意**  
要为使用 ESM 的 Node.js 应用程序启用 Application Signals，改为跳转到[设置采用 ESM 模块格式的 Node.js 应用程序](#EKS-NodeJs-ESM)。

------
#### [ Console ]

   **控制台**选项使用 Amazon CloudWatch Observability EKS 附加组件的高级配置，为您的服务设置 Application Signals。有关附加组件的更多信息，请参阅 [（可选）其他配置](install-CloudWatch-Observability-EKS-addon.md#install-CloudWatch-Observability-EKS-addon-configuration)。

   如果没有看到工作负载和命名空间列表，则请确保您拥有查看该集群工作负载和命名空间的适当权限。有关更多信息，请参阅[所需权限](https://docs.aws.amazon.com/eks/latest/userguide/view-kubernetes-resources.html#view-kubernetes-resources-permissions)。

   您可以通过选中**自动监控**复选框来监控所有服务工作负载，也可以有选择地选取要监控的特定工作负载和命名空间。

   要使用“自动监控”功能来监控所有服务工作负载，请执行以下操作：

   1. 选中**自动监控**复选框，自动选择集群中的所有服务工作负载。

   1. 选择**自动重启**功能重启所有工作负载容器组（pod），将 AWS Distro for OpenTelemetry 自动检测（ADOT）SDK 注入容器组（pod）中，即可立即启用 Application Signals。

   1. 选择**完成**。选择**自动重启**后，CloudWatch 可观测性 EKS 附加组件将立即启用 Application Signals。否则，将在每个工作负载的下次部署期间启用 Application Signals。

   您可以监控单个工作负载或整个命名空间。

   要监控单个工作负载，请执行以下操作：

   1. 选中要监控的工作负载旁的复选框。

   1. 使用**选择语言**下拉列表选择工作负载的语言。选择要为其启用 Application Signals 的语言，然后选择复选标记图标（✓）以保存此选择。

      对于 Python 应用程序，请确保您的应用程序符合所需的先决条件，然后再继续。有关更多信息，请参阅 [启用 Application Signals 后，Python 应用程序无法启动](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。

   1. 选择**完成**。Amazon CloudWatch Observability EKS 附加组件会立即将 AWS Distro for OpenTelemetry 自动检测（ADOT）SDK 注入到您的容器组（pod）中，并触发容器组（pod）重启以允许收集应用程序指标和跟踪。

   要监控整个命名空间，请执行以下操作：

   1. 选中要监控的命名空间旁的复选框。

   1. 使用**选择语言**下拉列表选择命名空间的语言。选择要为其启用 Application Signals 的语言，然后选择复选标记图标（✓）以保存此选择。此操作将该语言应用到此命名空间中的所有工作负载，无论其当前已部署还是将在未来部署。

      对于 Python 应用程序，请确保您的应用程序符合所需的先决条件，然后再继续。有关更多信息，请参阅 [启用 Application Signals 后，Python 应用程序无法启动](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。

   1. 选择**完成**。Amazon CloudWatch Observability EKS 附加组件会立即将 AWS Distro for OpenTelemetry 自动检测（ADOT）SDK 注入到您的容器组（pod）中，并触发容器组（pod）重启以允许收集应用程序指标和跟踪。

   要在另一个 Amazon EKS 集群中启用 Application Signals，请从**服务**屏幕中选择**启用 Application Signals**。

------
#### [ Annotate manifest file ]

   在 CloudWatch 控制台中，**监控服务**部分说明了您必须向集群中的清单 YAML 添加注释。添加此注释会自动检测应用程序以向 Application Signals 发送指标、跟踪和日志。

   您有两种注释选项：
   + **注释工作负载**会自动检测集群中的单个工作负载。
   + **注释命名空间**会自动检测所选命名空间中部署的所有工作负载。

   选择其中一个选项，然后按照相应的步骤操作：
   + 要为单个工作负载添加注释，请执行以下操作：

     1. 选择**注释工作负载**。

     1. 将以下行之一粘贴到工作负载清单文件的 `PodTemplate` 部分。
        + **对于 Java 工作负载：**`annotations: instrumentation.opentelemetry.io/inject-java: "true"`
        + **对于 Python 工作负载：**`annotations: instrumentation.opentelemetry.io/inject-python: "true"`

          对于 Python 应用程序，还需要额外的配置。有关更多信息，请参阅 [启用 Application Signals 后，Python 应用程序无法启动](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-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"`

     1. 在您的终端中，输入 `kubectl apply -f your_deployment_yaml` 以应用更改。
   + 要为命名空间中的所有工作负载添加注释，请执行以下操作：

     1. 选择**注释命名空间**。

     1. 将以下行之一粘贴到命名空间清单文件的元数据部分。如果命名空间包含 Java、Python 和 NET 工作负载，请将以下所有行都粘贴到命名空间清单文件中。
        + **如果命名空间中有 Java 工作负载：**`annotations: instrumentation.opentelemetry.io/inject-java: "true"`
        + **如果命名空间中有 Python 工作负载：**`annotations: instrumentation.opentelemetry.io/inject-python: "true"`

          对于 Python 应用程序，还需要额外的配置。有关更多信息，请参阅 [启用 Application Signals 后，Python 应用程序无法启动](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。
        + **如果命名空间中有 .NET 工作负载：**`annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"`
        + **如果命名空间中有 Node.JS 工作负载：**`annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"`

     1. 在您的终端中，输入 `kubectl apply -f your_namespace_yaml` 以应用更改。

     1. 在您的终端中，输入命令以重启命名空间中的所有容器组（pod）。重启部署工作负载的命令示例是 `kubectl rollout restart deployment -n namespace_name`

------

1. 选择**完成后查看服务**。这将带您进入 Application Signals 服务视图，您可以在其中查看 Application Signals 正在收集的数据。可能需要几分钟才会显示数据。

   要在另一个 Amazon EKS 集群中启用 Application Signals，请从**服务**屏幕中选择**启用 Application Signals**。

   有关**服务**视图的更多信息，请参阅 [使用 Application Signals 监控应用程序的运行状况](Services.md)。

**注意**  
如果您在 Python 应用程序中使用 WSGI 服务器，请参阅[使用 WSGI 服务器的 Python 应用程序没有 Application Signals 数据](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI)以获取有关使 Application Signals 起作用的信息。  
我们也已经明确在为 Application Signals 启用 Python 应用程序时应注意的其他注意事项。有关更多信息，请参阅 [启用 Application Signals 后，Python 应用程序无法启动](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。

### 设置采用 ESM 模块格式的 Node.js 应用程序
<a name="EKS-NodeJs-ESM"></a>

我们对采用 ESM 模块格式的 Node.js 应用程序提供有限的支持。有关更多信息，请参阅 [使用 ESM 的 Node.js 的已知限制](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)。

对于 ESM 模块格式，通过控制台或通过注释清单文件来启用 Application Signals 不起作用。跳过之前程序的步骤 8，改为执行以下操作。

**为使用 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 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 应用程序部署到集群。

在 Amazon EKS 集群上启用应用程序后，就可以监控应用程序的运行状况。有关更多信息，请参阅 [使用 Application Signals 监控应用程序的运行状况](Services.md)。

## 使用 CloudWatch 可观测性附加组件的高级配置在 Amazon EKS 集群上启用 Application Signals
<a name="CloudWatch-Application-Signals-Enable-EKS-Addon"></a>

默认情况下，在安装 CloudWatch 可观测性 EKS 附加组件（V5.0.0 或更高版本）或 Helm 图表时，会通过 Application Signals 启用基于 OpenTelemetry（OTEL）的应用程序性能监控（APM）。您可以使用 Amazon EKS 附加组件的高级配置或通过 Helm 图表覆盖值，进一步自定义特定设置。

**注意**  
如果您使用任何基于 OpenTelemetry（OTEL）的 APM 解决方案，启用 Application Signals 将会影响现有的可观测性设置。在继续操作之前，先检查当前的实施情况。若需在升级到 5.0.0 及更高版本后保留原有 APM 配置，请参阅[选择退出 Application Signals](install-CloudWatch-Observability-EKS-addon.md#Opting-out-App-Signals)。

CloudWatch 可观测性附加组件还提供了额外的精细控制功能，可根据需要在新的高级配置中包含或排除特定服务。有关更多信息，请参阅 [通过 Application Signals 为 Amazon EKS 集群启用 APM](install-CloudWatch-Observability-EKS-addon.md#Container-Insights-setup-EKS-appsignalsconfiguration)。

## 使用 AWS CDK 在 Amazon EKS 上启用 Application Signals
<a name="CloudWatch-Application-Signals-EKS-CDK"></a>

 如果您尚未在此账户中启用 Application Signals，则必须向 Application Signals 授予发现您的服务所需的权限。请参阅[在账户中启用 Application Signals](CloudWatch-Application-Signals-Enable.md)。

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 的服务相关角色权限](using-service-linked-roles.md#service-linked-role-signals)。

1. 安装 `amazon-cloudwatch-observability` 插件。

   1. 使用 `CloudWatchAgentServerPolicy` 以及与集群关联的 OIDC 创建 IAM 角色。

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

1. 使用上面创建的 IAM 角色安装附加组件。

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

1. 将其中一行添加到工作负载清单文件的 `PodTemplate` 部分。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.html)

   ```
   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)
   ```

## 使用模型上下文协议（MCP）服务器在 Amazon EKS 上启用 Application Signals
<a name="CloudWatch-Application-Signals-EKS-MCP"></a>

您可以使用 CloudWatch Application Signals 模型上下文协议（MCP）服务器，通过对话式人工智能交互在 Amazon EKS 集群上启用 Application Signals。这为设置 Application Signals 监控提供了自然语言界面。

MCP 服务器通过理解您的需求并生成相应的配置来自动执行启用过程。您只需简单描述要启用的功能，无需手动执行控制台步骤或编写 CDK 代码。

### 先决条件
<a name="CloudWatch-Application-Signals-EKS-MCP-Prerequisites"></a>

在使用 MCP 服务器启用 Application Signals 之前，请确保满足以下条件：
+ 支持 MCP 的开发环境（例如 Kiro、Claude Desktop、带有 MCP 扩展的 VSCode 或其他与 MCP 兼容的工具）
+ 已在 IDE 中配置 CloudWatch Application Signals MCP 服务器。有关详细的设置说明，请参阅 [CloudWatch Application Signals MCP 服务器文档](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

### 使用 MCP 服务器
<a name="CloudWatch-Application-Signals-EKS-MCP-Usage"></a>

在 IDE 中配置好 CloudWatch Application Signals MCP 服务器后，即可使用自然语言提示来请求启用指导。尽管编码助手可以从项目结构中推断出上下文，但在提示中提供具体细节有助于确保获得更准确、更相关的指导。包含一些信息，例如应用程序语言、Amazon EKS 集群名称以及基础设施和应用程序代码的绝对路径等等。

**最佳实践提示（具体且完整）：**

```
"Enable Application Signals for my Python service running on EKS.
My app code is in /home/user/flask-api and IaC is in /home/user/flask-api/terraform"

"I want to add observability to my Node.js application on EKS cluster 'production-cluster'.
The application code is at /Users/dev/checkout-service and
the Kubernetes manifests are at /Users/dev/checkout-service/k8s"

"Help me instrument my Java Spring Boot application on EKS with Application Signals.
Application directory: /opt/apps/payment-api
CDK infrastructure: /opt/apps/payment-api/cdk"
```

**效果较差的提示：**

```
"Enable monitoring for my app"
→ Missing: platform, language, paths

"Enable Application Signals. My code is in ./src and IaC is in ./infrastructure"
→ Problem: Relative paths instead of absolute paths

"Enable Application Signals for my EKS service at /home/user/myapp"
→ Missing: programming language
```

**快速模板：**

```
"Enable Application Signals for my [LANGUAGE] service on EKS.
App code: [ABSOLUTE_PATH_TO_APP]
IaC code: [ABSOLUTE_PATH_TO_IAC]"
```

### 使用 MCP 服务器的优势
<a name="CloudWatch-Application-Signals-EKS-MCP-Benefits"></a>

使用 CloudWatch Application Signals MCP 服务器具有以下优势：
+ **自然语言界面：**无需记住命令或配置语法，即可描述要启用的功能
+ **上下文感知指导**：MCP 服务器了解特定环境并提供量身定制的建议
+ **减少错误：**自动生成配置可最大限度地减少手动输入错误
+ **更快设置：**更快地将想法过渡到实施
+ **学习工具：**查看生成的配置，了解 Application Signals 的工作原理

### 其他资源
<a name="CloudWatch-Application-Signals-EKS-MCP-MoreInfo"></a>

有关配置和使用 CloudWatch Application Signals MCP 服务器的更多信息，请参阅 [MCP 服务器文档](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。