容器服务 ACK 和容器计算服务 ACS 通过 ack-onepilot 组件安装 Node.js 探针

ack-onepilot 负责在应用启动前准备探针及其接入配置，对于 Node.js 应用通过环境变量自动加载探针，具体工作机制请参见 ack-onepilot 组件基本原理说明。

前提条件

• 已创建 ACK 或 ACS 集群。具体操作，请参见创建 ACK 托管集群或创建 ACS 集群。

• 已创建应用所在的命名空间。本文使用 default 命名空间。有关命名空间的操作，请参见管理命名空间与配额。

• 已确认应用使用的 Node.js 版本及依赖受探针支持。具体支持范围，请参见 ARMS 应用监控支持的 Node.js 组件和框架。

• ack-onepilot 版本为 5.3.3 及以上。集群未安装该组件或已安装版本低于 5.3.3 时，请先完成步骤一：安装探针接入助手（ack-onepilot）。

• 当前账号具备完成本文操作所需的集群与 RAM 权限，包括安装或升级集群组件、修改 Worker RAM 角色的权限策略、编辑组件的 Helm 配置与 Deployment、创建 Secret。

• 应用未通过代码或启动参数手动加载 Node.js 探针。如已手动加载，请先移除原有加载配置，避免重复初始化。

生效时机与部署建议

• 接入配置在新建 Pod 时生效。更新应用标签会触发工作负载重新部署，请合理安排变更时间。

• 一个 Pod 包含多个容器时，组件会向 Pod 中的各普通容器注入 Node.js 加载参数。对于包含不同语言或不同模块类型的 Pod，建议将 Node.js 应用单独部署。

步骤一：安装探针接入助手（ack-onepilot）

1. 打开容器服务管理控制台，从集群列表进入需要接入应用的集群。

2. 在左侧导航栏选择组件管理，搜索 ack-onepilot。

3. 根据组件的安装情况执行对应操作。

   • 未安装 ack-onepilot：从搜索结果安装 ack-onepilot，按集群环境配置安装参数，确认后完成安装。安装完成后，确认组件版本为 5.3.3 及以上。

   • 已安装 ack-onepilot：检查组件版本。版本需为 5.3.3 及以上，低于该版本时先升级组件再继续后续步骤。

   说明

   ACS 集群需通过组件安装参数配置 accessKey 和 accessKeySecret，凭据的权限要求与配置方式请参见步骤二：授予 ARMS 资源的访问权限。

步骤二：授予 ARMS 资源的访问权限

ack-onepilot 需要访问 ARMS 资源，请按集群类型完成授权。已完成相应授权的集群，可直接为应用开启监控。应用监控数据统一在云监控 2.0 控制台查看。各集群类型的授权方式与所需权限策略如下。

步骤三：为 Node.js 应用开启应用监控

1. 在容器服务管理控制台打开目标集群。

2. 进入工作负载 > 无状态，找到目标 Node.js 应用。

3. 打开应用的 YAML 配置页面。

   • 已有应用：打开应用的 YAML 编辑页面。

   • 新建应用：选择使用 YAML 创建资源。

4. 在 spec.template.metadata.labels 下添加以下标签。

   labels:
     aliyun.com/app-language: nodejs
     armsPilotAutoEnable: "on"
     armsPilotCreateAppName: "nodejs-demo"
     armsPilotAppWorkspace: "workspace"

   标签	说明
   aliyun.com/app-language	应用语言，Node.js 应用填写 nodejs。
   armsPilotAutoEnable	应用监控开关，填写 "on"。
   armsPilotCreateAppName	应用在云监控 2.0 控制台显示的名称，请替换为实际应用名称。
   armsPilotAppWorkspace	应用监控数据所属的目标工作空间，取值为接入配置中的 Workspace 值，请替换为实际的工作空间名称。不配置该标签时使用默认工作空间。

   重要

   • 标签需添加到 Pod 模板的 spec.template.metadata.labels 下。仅向 Deployment 的 metadata.labels 添加标签不会使应用接入监控。

   • 如果应用已配置 armsAutoInstrumentationEnable: "off"，请删除该标签或将其改为 "on"，否则不会自动加载探针。

5. 如果应用使用 ECMAScript Modules（ESM），在同一位置的 labels 下补充以下标签，缩进层级与其他接入标签一致。CommonJS 应用无需配置。

   labels:
     aliyun.com/nodejs-module-type: "esm"

   说明

   aliyun.com/nodejs-module-type 支持 commonjs 和 esm，默认按 CommonJS 方式加载探针。ESM 应用需设置为 esm，由组件同时配置探针初始化和 ESM 模块加载。

6. 确认容器环境变量与启动参数的配置方式不影响探针注入。

   • 应用启动脚本需保留 NODE_OPTIONS 环境变量，避免覆盖组件注入的探针加载参数。

   • 如果通过 valueFrom 设置 NODE_OPTIONS，组件会跳过该容器的探针加载参数注入，此时需将需要保留的非敏感启动参数直接配置到容器的 env[].value。

   • 通过镜像 ENV 或 envFrom 设置的启动参数，也需显式填写到 env[].value，以便组件保留原有参数并追加探针配置。

7. 保存配置并等待新 Pod 启动。已有应用单击更新；新建应用在 YAML 配置完成后创建资源。

以下为 CommonJS 应用的完整 Deployment 配置示例。使用前请替换 image、应用名称（armsPilotCreateAppName）及工作空间（armsPilotAppWorkspace）等占位值。已有应用请保留原有的资源、存储和健康检查等配置，仅添加接入标签。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nodejs-demo
  namespace: default
  labels:
    app: nodejs-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nodejs-demo
  template:
    metadata:
      labels:
        app: nodejs-demo
        aliyun.com/app-language: nodejs
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "nodejs-demo"
        armsPilotAppWorkspace: "workspace"
    spec:
      containers:
        - name: nodejs-demo
          image: your-registry/your-nodejs-app:your-tag
          imagePullPolicy: IfNotPresent

ESM 应用需向上例的 spec.template.metadata.labels 追加 aliyun.com/nodejs-module-type: "esm"，其他接入标签保持不变。

查看监控详情

1. 待应用启动后，访问应用接口，使应用产生请求数据。

2. 打开云监控 2.0 控制台，进入配置的工作空间，即 armsPilotAppWorkspace 指定的工作空间；未配置该标签时进入默认工作空间。

3. 选择所有功能 > 应用可观测 > 应用监控。

4. 从应用列表找到 armsPilotCreateAppName 指定的应用，单击应用名称，查看实例、接口和调用链等监控数据。

相关文档

• 手动安装 Node.js 探针

• ARMS 应用监控支持的 Node.js 组件和框架