agent-install

在 Kubernetes 上安装 Datadog Agent

开始前须知： 完整解决 ## Context to resolve before acting 中的所有变量。所有变量都有具体值后，再开始步骤 1。

阶段 0：加载凭据

[ -f environment ] && source environment
echo "DD_API_KEY set: $([ -n "${DD_API_KEY:-}" ] && echo yes || echo no)"
echo "DD_SITE: ${DD_SITE:-not set}"
echo "helm: $(helm version --short 2>/dev/null || echo NOT FOUND)"

如果找不到 helm — 请告知用户：

此技能需要 helm。请使用以下命令安装：

brew install helm        # macOS
# 或访问 https://helm.sh/docs/intro/install/ 查看其他平台的安装方法

安装完成后，请告知我，我会继续。

在 helm 可用之前，请勿继续。

如果已设置 DD_API_KEY — 继续执行先决条件。

如果未设置 DD_API_KEY — 请告知用户：

我需要两项信息才能继续：

1. Datadog API Key — 用于对 Agent 进行身份验证，使其能够连接到你的 Datadog 账户。你可以在此处查找或创建 API Key：https://app.datadoghq.com/organization-settings/api-keys

2. Datadog Site — 你的 Datadog 账户所在的区域。大多数账户使用 datadoghq.com。请检查你的 Datadog URL 进行确认（例如，app.datadoghq.eu → Site 为 datadoghq.eu）。其他选项：us3.datadoghq.com、us5.datadoghq.com、ap1.datadoghq.com。

请在此聊天中运行以下命令来设置凭据（! 前缀会在此会话中执行命令）：

! export DD_API_KEY=your-api-key-here
! export DD_SITE=datadoghq.com

等待用户运行这些命令，然后重新运行上述检查再继续。

---

先决条件

• Kubernetes v1.20+ — kubectl version
• helm v3+ — helm version
• 已配置 kubectl 指向目标集群 — kubectl config current-context
• 已安装 pup-cli — 使用 pup --version 检查；如果未安装，请立即安装：

  if [[ "$(uname)" == "Darwin" ]]; then
    brew tap datadog-labs/pack && brew install pup
  else
    PUP_VERSION=$(curl -s https://api.github.com/repos/datadog-labs/pup/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
    curl -L "https://github.com/datadog-labs/pup/releases/download/${PUP_VERSION}/pup_linux_amd64.tar.gz" | tar xz -C /usr/local/bin pup
    chmod +x /usr/local/bin/pup
  fi
  pup --version
  

  请勿跳过 — 只有在 pup --version 成功后才能继续。

---

开始前要解决的上下文

变量	解决方法
CLUSTER_NAME	检查仓库中的 IaC、脚本，或运行 kubectl config current-context
DD_SITE	询问用户。默认值：datadoghq.com。常见选项：datadoghq.eu、us3.datadoghq.com、us5.datadoghq.com、ap1.datadoghq.com。完整列表：https://docs.datadoghq.com/getting_started/site/
AGENT_NAMESPACE	除非仓库已统一使用 datadog-agent，否则使用 datadog
CHART_VERSION	运行 helm search repo datadog/datadog-operator --versions | head -5 并使用最新的稳定版本

---

步骤 1：检查是否已安装 Agent

Claude 运行

helm list -A | grep -i datadog

如果某个发行版显示为 deployed — 表示 Agent 已安装。跳到步骤 5 确认运行状况，然后退出。

如果没有输出 — 表示尚未安装。继续执行步骤 2。

---

步骤 2：安装 Datadog Operator

Claude 运行

helm repo add datadog https://helm.datadoghq.com
helm repo update

helm upgrade --install datadog-operator datadog/datadog-operator \
  --namespace <AGENT_NAMESPACE> \
  --create-namespace \
  --version <CHART_VERSION>

kubectl wait --for=condition=Ready pod \
  -l app.kubernetes.io/name=datadog-operator \
  -n <AGENT_NAMESPACE> \
  --timeout=120s

如果 Operator Pod 处于 Running 状态 — 继续执行步骤 3。

错误：Pod 在 120 秒后仍未就绪 — 检查镜像拉取情况：kubectl describe pod -l app.kubernetes.io/name=datadog-operator -n <AGENT_NAMESPACE>。

---

步骤 3：创建 API Key Secret

你需要在终端中执行

export DD_API_KEY=<your-api-key>

kubectl create secret generic datadog-secret \
  --from-literal api-key=$DD_API_KEY \
  --namespace <AGENT_NAMESPACE>

如果显示 secret/datadog-secret created — 继续执行步骤 4。

错误：AlreadyExists — 在决定是否重新创建之前，请按照步骤 5 确认其中保存的 API Key。

---

步骤 4：部署 DatadogAgent 资源

[DECISION: cluster type]

• 自托管（minikube、kind）：在 spec.global 中加入 kubelet.tlsVerify: false
• 托管（GKE、EKS、AKS）：完全省略 kubelet.tlsVerify

[DECISION: APM/SSI also being enabled in this session]

• 如果是：不要为 APM 单独创建 DatadogAgent — 根据 enable-ssi 为同一份清单添加 features.apm。只使用一份清单，不要使用两份。
• 如果不是：直接使用下方的清单。

将以下内容保存为 datadog-agent.yaml：

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
  namespace: <AGENT_NAMESPACE>
spec:
  global:
    clusterName: <CLUSTER_NAME>
    site: <DD_SITE>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key
    # Self-hosted clusters only (minikube, kind):
    # kubelet:
    #   tlsVerify: false
  features:
    orchestratorExplorer:
      enabled: true
    clusterChecks:
      enabled: true
    logCollection:
      enabled: true
      containerCollectAll: false

Claude 运行

kubectl apply -f datadog-agent.yaml

kubectl wait --for=condition=Ready pod \
  -l app.kubernetes.io/component=agent \
  -n <AGENT_NAMESPACE> \
  --timeout=120s 2>/dev/null || true

---

步骤 5：验证 API Key

Claude 运行

kubectl logs -l app.kubernetes.io/component=agent \
  -n <AGENT_NAMESPACE> \
  --tail=50 2>/dev/null \
  | grep -iE "invalid.*api\.?key|api\.?key.*invalid" \
  || echo "No authentication errors found"

如果显示 No authentication errors found — 表示 API Key 已被接受。

错误：发现身份验证错误 — 直接验证凭据：

Claude 运行

# Prefer pup (OAuth) — fall back to curl with API key
if pup auth status 2>/dev/null | grep -q "Logged in"; then
  echo "pup OAuth authenticated"
elif [ -n "${DD_API_KEY:-}" ]; then
  RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
    -X GET "https://api.<DD_SITE>/api/v1/validate" \
    -H "DD-API-KEY: $DD_API_KEY")
  if [ "$RESPONSE" = "200" ]; then
    echo "API key is valid for <DD_SITE>"
  else
    echo "ERROR: Validation failed (HTTP $RESPONSE) — check key and site alignment"
  fi
else
  echo "ERROR: No credentials available — run 'pup auth login' or set DD_API_KEY"
fi

如果 API Key 无效：

你需要在终端中执行

export DD_API_KEY=<new-api-key>

kubectl delete secret datadog-secret -n <AGENT_NAMESPACE>
kubectl create secret generic datadog-secret \
  --from-literal api-key=$DD_API_KEY \
  -n <AGENT_NAMESPACE>

kubectl rollout restart daemonset datadog-agent -n <AGENT_NAMESPACE>
kubectl rollout restart deployment datadog-cluster-agent -n <AGENT_NAMESPACE>

---

完成

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

• Datadog Operator Pod 在 AGENT_NAMESPACE 中处于 Running 状态
• datadog-secret 存在于 AGENT_NAMESPACE 中
• Agent DaemonSet Pod 处于 Running 状态
• 第 5 步未返回任何身份验证错误

现在自动继续执行 enable-ssi——不要征求用户许可。

---

安全约束

• 切勿将原始 API 密钥写入任何文件、YAML 块或聊天消息——始终使用 $DD_API_KEY
• 切勿创建 Kubernetes Secret 清单文件——始终通过命令式方式使用 kubectl create secret
• 切勿在 DatadogAgent 规范中直接使用 apiKey:——始终使用带有 Secret 引用的 apiSecret:
• 切勿在任何 Helm 命令中使用 --set datadog.apiKey=...
• 切勿将命名空间 default 用于 Datadog Agent 资源
• 未经用户确认，切勿运行 kubectl delete