enable-ssi

通过单步插桩在 Kubernetes 上启用 APM

开始前先完成以下事项： 完整解析 ## Context to resolve before acting 中的所有变量。在所有变量都有明确值之前，不要开始步骤 0。

---

静默失败——开始其他步骤前先检查：

如果应用的依赖清单（requirements.txt、package.json、Gemfile、go.mod、pom.xml）中包含 ddtrace、dd-trace 或任何 OpenTelemetry SDK，即使代码中没有导入语句，SSI 也会在运行时静默禁用。

这种失败不会显现出来：初始化容器会运行并完成，Pod 会正常启动，kubectl 或 pup 中不会出现错误，但不会收到任何跟踪数据。注入器检测到用户安装的跟踪器后会正常退出，不记录任何日志。

Claude 运行

grep -rE "ddtrace|dd-trace|opentelemetry" \
  requirements.txt package.json Gemfile go.mod pom.xml 2>/dev/null \
  || echo "No tracer dependency found"

如果有任何匹配项——请停止。彻底移除该软件包（而不只是移除导入语句），重新构建镜像，将镜像重新加载到集群中，并重启 Pod，然后再继续。只要依赖清单中存在该软件包，就会触发此问题，即使从未导入它也是如此。

---

触发条件

用户表达以下意图时，调用此技能：

• 在 Kubernetes 集群上启用 APM
• 使用 Datadog 跟踪功能为 Kubernetes 应用插桩
• 设置单步插桩（SSI）

以下情况不要调用此技能：

• 尚未安装 Datadog Agent——先运行 agent-install
• 用户想在设置后验证 SSI——使用 verify-ssi
• 用户想启用 Data Streams Monitoring：使用 enable-dsm
• 用户想启用 Profiler 或 AppSec：使用 dd-apm-k8s-sdk-features

---

先决条件

这不是阅读练习——继续操作前，务必主动验证每一项。

环境

• Datadog Agent 已安装且运行正常——已完成 agent-install
• Kubernetes v1.20+
• 仅限 Linux 节点池——Windows Pod 需要显式排除命名空间
• 集群不是 ECS Fargate——不受支持
• 不是经过安全加固的 SELinux 环境——不受支持
• 不是非常小的 VM 实例（例如 t2.micro）——SSI 可能会遇到初始化超时
• 未强制执行 PodSecurity baseline 或 restricted 策略

语言和运行时

• 应用语言属于以下范围：Java、Python、Ruby、Node.js、.NET、PHP
• 运行时版本在 SSI 支持范围内——请参阅 SSI 兼容性矩阵进行确认
• Node.js 应用未使用 ESM——SSI 不支持 ESM
• Java 应用未使用 -javaagent JVM 标志

现有插桩——已通过本技能顶部的检查确认无问题。如果跳过了该检查，请返回并立即运行。

执行前需要确定的上下文

从集群中自行查找，不要询问用户你能自行查到的信息。

变量	确定方法
AGENT_NAMESPACE	使用 agent-install 中的同一命名空间（例如 datadog）
APP_NAMESPACE	运行 kubectl get namespaces --no-headers | awk '{print $1}' | grep -vE '^(kube-system|kube-public|kube-node-lease|datadog|local-path-storage)$' — 为所有非系统命名空间添加监测，或使用用户提到的命名空间
TARGET_LANGUAGES	运行 kubectl get pods -A -o jsonpath='{.items[*].spec.containers[*].image}'，根据镜像名称推断语言，或检查工作区中的 Dockerfile/清单。如果不确定，则启用所有语言。
DEPLOYMENT_NAME	运行 kubectl get deployments -A --no-headers — 找出应用部署（排除系统组件）
APP_LABEL	通过 kubectl get deployment <DEPLOYMENT_NAME> -n <APP_NAMESPACE> -o yaml 检查 Deployment 清单中的 spec.selector.matchLabels
CLUSTER_NAME	检查 datadog-agent.yaml 中的 spec.global.clusterName，或运行 kubectl config current-context — Step 0 中的 kind 集群需要此项
ENV	如果在评估集群中运行，则使用 apm-evals（kind 集群名称中包含 "evalya"）。否则使用 production，除非用户另有指定。
SERVICE_NAME	使用部署名称（例如 python-app → 服务 python-app）。不要询问用户。
VERSION	默认使用 1.0.0。不要询问用户。

---

Step 0（仅在检测到现有插桩时）：移除手动插桩

扫描所有源文件，查找：import ddtrace、from ddtrace、require 'ddtrace'、require("dd-trace")、opentelemetry、tracer.trace(

同时检查依赖清单中是否包含 ddtrace / dd-trace / OTel SDK 包。

如果找到 — 移除导入/包，然后重新构建并重新加载：

Claude 执行

docker build -f <DOCKERFILE_PATH> -t <IMAGE_NAME> <BUILD_CONTEXT>

[DECISION: how does this cluster get local images?]

检查仓库的设置脚本（例如 create.sh、Makefile、justfile），确认镜像的加载方式 — 不要根据集群名称或上下文进行猜测。常见模式如下：

在设置脚本中发现的内容	加载命令
minikube image load 或 minikube cache add	minikube -p <PROFILE> image load <IMAGE_NAME> — 配置文件是脚本中 -p 标志的值，不一定是 kubectl 上下文名称
kind load docker-image	kind load docker-image <IMAGE_NAME> --name <CLUSTER_NAME>
向注册表执行 docker push	推送新镜像；集群将在重启时拉取 — 跳过本地加载
k3d image import	k3d image import <IMAGE_NAME> -c <CLUSTER_NAME>
没有镜像加载步骤（云集群，始终从注册表拉取）	跳过 — 镜像将在下次部署时拉取

如果设置脚本含义不明确，则原样运行其中使用的加载命令。

• 基于注册表：跳过 — 镜像将在下次部署时拉取

重启前先向用户确认。 告知用户："我需要重启 <DEPLOYMENT_NAME>（位于 <APP_NAMESPACE>）以使用重新构建的镜像。现在可以继续吗？" 等待确认。

Claude 执行

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>
kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

---

步骤 1：为 DatadogAgent 清单添加 APM

SSI 配置在现有的 DatadogAgent 资源上——不要创建单独的清单。

根据用户的需求选择目标范围：

• 用户要求为所有应用接入监控，或未指定范围 → 使用选项 A（整个集群）
• 用户只要求指定命名空间 → 使用选项 B
• 用户要求在整个集群范围内排除某些命名空间 → 使用选项 C
• 用户要求指定 Pod／工作负载 → 使用选项 D

默认范围是整个集群（选项 A）。 如果用户说“我的所有应用”“整个集群”，或未限制范围，则使用选项 A，不要设置 enabledNamespaces 或 targets。

推荐的 ddTraceVersions：java: "1"、python: "2"、js: "5"、dotnet: "3"、ruby: "2"、php: "1"

选项 A — 整个集群（默认）：

features:
  apm:
    instrumentation:
      enabled: true

选项 B — 仅限指定命名空间：

features:
  apm:
    instrumentation:
      enabled: true
      enabledNamespaces:
        - <APP_NAMESPACE>

选项 C — 整个集群，但排除指定命名空间：

features:
  apm:
    instrumentation:
      enabled: true
      disabledNamespaces:
        - jenkins
        - kube-system

选项 D — 指定目标工作负载：

features:
  apm:
    instrumentation:
      enabled: true
      targets:
        - name: <TARGET_NAME>
          namespaceSelector:
            matchNames:
              - <APP_NAMESPACE>
          ddTraceVersions:
            <LANGUAGE>: "<MAJOR_VERSION>"

注意： ddTraceVersions 仅适用于 targets[] 条目内（选项 D）。它不能与 enabledNamespaces 同时使用，也不能直接设置在 instrumentation 层级。

Claude 执行

kubectl apply -f datadog-agent.yaml

如果 datadogagent.datadoghq.com/datadog configured，则继续执行步骤 2。

错误：验证错误——请检查 YAML。不能同时设置 enabledNamespaces 和 disabledNamespaces。

---

步骤 2：告知用户统一服务标签

未经用户明确确认，不要修改应用 Deployment。 为现有应用工作负载添加标签会更改由客户管理的资源。

告知用户，为 Deployment 添加统一服务标签（UST）后，Datadog 才能正确标记服务／环境／版本。SSI 无需此设置也能正常工作，但为了实现完整的可观测性，建议添加：

# Add to both metadata.labels and spec.template.metadata.labels
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE_NAME>"
tags.datadoghq.com/version: "<VERSION>"

如果用户希望你应用这些标签，请先征得确认。应用标签更改会立即滚动重启 Pod；如果将在步骤 2b 中启用 DSM，请在启用后再应用标签。APM 链路正常上报不要求设置 UST 标签；即使没有这些标签，SSI 也能正常工作。

---

步骤 2b：检查是否存在事件驱动服务

在评估集群（kind 集群名称包含“evalya”）或以非交互方式运行时，完全跳过此步骤：不运行任何命令、不询问任何问题，然后继续下一步。

其他情况下，阅读 .claude/skills/dd-apm/enable-dsm/SKILL.md 中的 ## Is DSM a fit? 部分，并运行其中的检测命令。

• 找到适用场景（消息传递客户端、代理、队列触发的 Lambda，或用户描述的服务之间异步传递工作）→ 按照 enable-dsm 操作。它会询问用户一次、说明计划规则，并在不重启的情况下修改配置。
• 不适用 → 跳过。不要提及 DSM。

如果用户同意，enable-dsm 会应用其 DatadogAgent 更改，并等待 Cluster Agent 使用新配置，以便步骤 3 的重启同时启用 SSI 和 DSM。在步骤 3 中，先重启一个 DSM Deployment，并在其上运行 enable-dsm 步骤 2a 中的 DD_DATA_STREAMS_ENABLED 检查，再重启其余 Deployment。如果该 Deployment 启动时没有 init 容器，请等待 30 秒，然后再重启一次。

---

步骤 3：重启应用 Pod

重启前请先征得用户确认。 告知用户：“我需要重启 <DEPLOYMENT_NAME>（位于 <APP_NAMESPACE>），以便 SSI 注入 Pod。这会造成短暂中断。现在可以继续吗？” 等待用户确认。

Claude 执行

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>

kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

如果 Pod 顺利重启，Pod 规格中将显示名为 datadog-lib-<language>-init 的 init 容器。

错误：Pod 持续崩溃并重启——请检查是否已有自定义插桩。请参阅 troubleshoot-ssi。

---

完成

仅当以下所有条件都满足时才退出：

• 已应用的 DatadogAgent 清单中包含 features.apm.instrumentation
• 已告知用户需要重启其应用 Pod
• 已向用户介绍统一服务标签（UST），并说明如何在需要时应用这些标签
• 已确认范围：哪些工作负载已启用埋点、哪些被跳过以及原因

立即自动继续执行 verify-ssi —— 不要征求用户许可。

---

安全约束

• 绝不将原始 API 密钥写入任何文件或聊天消息
• 绝不将命名空间 default 用于 Datadog 资源
• 绝不直接修改 admissionController 设置 —— SSI 通过 Operator 管理这些设置
• 不要向应用清单添加 APM 配置 —— 仅通过 DatadogAgent 配置
• 例外：应用 Deployment 上的 UST 标签（tags.datadoghq.com/*）是必需且有意添加的
• 未经用户确认，绝不运行 kubectl delete
• 向注册表执行 docker push 始终需要用户确认
• 绝不使用 kubectl patch 应用 UST 标签或进行任何 Deployment 更改。 始终编辑 Deployment YAML 文件并运行 kubectl apply -f。通过 kubectl patch 所做的更改是临时的，并会在下一次发布时被覆盖。