agent-install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Install the Datadog Agent on Kubernetes

在Kubernetes上安装Datadog Agent

Before doing anything else: Fully resolve all variables in
## Context to resolve before acting
. Do not begin Step 1 until every variable has a concrete value.

操作前须知： 请先完全解析
## 操作前需明确的上下文
中的所有变量。在每个变量都有具体值之前，不要开始执行步骤1。

Phase 0: Load Credentials

阶段0：加载凭证

bash

[ -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)"

If
helm
is not found — tell the user:

helm
is required for this skill. Install it with:
bash
brew install helm        # macOS
# or see https://helm.sh/docs/intro/install/ for other platforms
Once installed, let me know and I'll continue.

Do not proceed until

helm

is available.

If
DD_API_KEY
is already set — proceed to Prerequisites.

If
DD_API_KEY
is not set — tell the user:

I need two things to continue:

1. Datadog API Key — used to authenticate the Agent with your Datadog account. You can find or create one at: https://app.datadoghq.com/organization-settings/api-keys
2. Datadog Site — the region your Datadog account is on. Most accounts use
datadoghq.com
. Check your Datadog URL to confirm (e.g.
app.datadoghq.eu
→ site is
datadoghq.eu
). Other options:
us3.datadoghq.com
,
us5.datadoghq.com
,
ap1.datadoghq.com
.
Please run the following in this chat to set your credentials (the
!
prefix executes it in this session):
! export DD_API_KEY=your-api-key-here
! export DD_SITE=datadoghq.com

Wait for the user to run the commands, then re-run the check above before continuing.

bash

[ -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
。请通过以下方式安装：
bash
brew install helm        # macOS
# 其他平台请查看 https://helm.sh/docs/intro/install/
安装完成后，请告知我，我会继续后续操作。

在

helm

可用之前，请勿继续。

如果已设置
DD_API_KEY
——进入先决条件检查环节。

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

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

1. Datadog API密钥——用于Agent与您的Datadog账户进行身份验证。您可以在以下地址查找或创建：https://app.datadoghq.com/organization-settings/api-keys
2. Datadog站点——您的Datadog账户所在的区域。大多数账户使用
datadoghq.com
。请查看您的Datadog URL确认（例如
app.datadoghq.eu
对应的站点是
datadoghq.eu
）。其他可选值：
us3.datadoghq.com
、
us5.datadoghq.com
、
ap1.datadoghq.com
。
请在本聊天中运行以下命令设置您的凭证（
!
前缀表示在当前会话中执行）：
! export DD_API_KEY=your-api-key-here
! export DD_SITE=datadoghq.com

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

Prerequisites

先决条件

Kubernetes v1.20+ —
```
kubectl version
```
helm v3+ —
```
helm version
```
kubectl configured to target cluster —
```
kubectl config current-context
```

pup-cli installed — check with

pup --version

; if missing, install it now:

bash

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

Do not skip — proceed only once

pup --version

succeeds.

Kubernetes v1.20+ — 可通过
```
kubectl version
```
检查
helm v3+ — 可通过
```
helm version
```
检查
kubectl已配置为目标集群 — 可通过
```
kubectl config current-context
```
检查

pup-cli已安装 — 通过

pup --version

检查；如果未安装，请立即安装：

bash

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

执行成功后才能继续。

Context to resolve before acting

操作前需明确的上下文

Variable	How to resolve
`CLUSTER_NAME`	Check repo IaC, scripts, or `kubectl config current-context`
`DD_SITE`	Ask the user. Default: `datadoghq.com` . Common options: `datadoghq.eu` , `us3.datadoghq.com` , `us5.datadoghq.com` , `ap1.datadoghq.com` . Full list: https://docs.datadoghq.com/getting_started/site/
`AGENT_NAMESPACE`	Use `datadog` unless the repo already uses `datadog-agent` consistently
`CHART_VERSION`	Run `helm search repo datadog/datadog-operator --versions \| head -5` and use the latest stable

变量	解析方式
`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` 并使用最新稳定版本

Step 1: Check for an Existing Agent Installation

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

Claude runs

Claude执行

bash

helm list -A | grep -i datadog

If a release shows

deployed

— Agent already installed. Skip to Step 5 to confirm health, then exit.

If there is no output — no existing install. Continue to Step 2.

bash

helm list -A | grep -i datadog

如果输出中显示

deployed

——Agent已安装。跳至步骤5确认健康状态，然后退出。

如果无输出——无现有安装。继续步骤2。

Step 2: Install the Datadog Operator

步骤2：安装Datadog Operator

Claude runs

Claude执行

bash

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

If the Operator pod is Running — continue to Step 3.

ERROR: Pod not ready after 120s — check image pull:

kubectl describe pod -l app.kubernetes.io/name=datadog-operator -n <AGENT_NAMESPACE>

bash

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处于运行状态——继续步骤3。

错误：120秒后Pod仍未就绪——检查镜像拉取情况：

kubectl describe pod -l app.kubernetes.io/name=datadog-operator -n <AGENT_NAMESPACE>

。

Step 3: Create the API Key Secret

步骤3：创建API密钥Secret

What you need to do in a terminal

您需要在终端中执行的操作

bash

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

— continue to Step 4.

ERROR:

AlreadyExists

— confirm which key it holds via Step 5 before deciding whether to recreate.

bash

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确认该Secret包含的密钥。

Step 4: Deploy the DatadogAgent Resource

步骤4：部署DatadogAgent资源

[DECISION: cluster type]

Self-hosted (minikube, kind): include
```
kubelet.tlsVerify: false
```
inside
```
spec.global
```
Managed (GKE, EKS, AKS): omit
```
kubelet.tlsVerify
```
entirely

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

If yes: do not create a separate
```
DatadogAgent
```
for APM — extend this same manifest with
```
features.apm
```
per
```
enable-ssi
```
. One manifest, not two.
If no: use the manifest below as-is.

Save the following as

datadog-agent.yaml

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

[决策：集群类型]

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

[决策：本次会话是否同时启用APM/SSI]

如果是：不要为APM单独创建
```
DatadogAgent
```
——按照
```
enable-ssi
```
的要求，在同一个清单中扩展
```
features.apm
```
。仅使用一个清单，而非两个。
如果否：直接使用下方的清单。

将以下内容保存为

datadog-agent.yaml

：

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
    # 仅自托管集群使用（minikube、kind）：
    # kubelet:
    #   tlsVerify: false
  features:
    orchestratorExplorer:
      enabled: true
    clusterChecks:
      enabled: true
    logCollection:
      enabled: true
      containerCollectAll: false

Claude runs

Claude执行

bash

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

bash

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

Step 5: Verify the API Key

步骤5：验证API密钥

Claude runs

Claude执行

bash

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

— key is accepted.

ERROR: Authentication errors found — validate credentials directly:

bash

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

——密钥已被接受。

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

Claude runs

Claude执行

bash

undefined

bash

undefined

Prefer pup (OAuth) — fall back to curl with API key

优先使用pup（OAuth）——如果失败则回退到使用API密钥的curl

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


If key is invalid:


如果密钥无效：

What you need to do in a terminal

您需要在终端中执行的操作

bash

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>

bash

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>

Done

完成

Exit when ALL of the following are true:

Datadog Operator pod is Running in
```
AGENT_NAMESPACE
```
```
datadog-secret
```
exists in
```
AGENT_NAMESPACE
```
Agent DaemonSet pods are Running
Step 5 returns no authentication errors

Automatically proceed to

enable-ssi

now — do not ask the user for permission.

当以下所有条件均满足时，操作完成：

Datadog Operator Pod在
```
AGENT_NAMESPACE
```
中处于运行状态
```
datadog-secret
```
在
```
AGENT_NAMESPACE
```
中存在
Agent DaemonSet Pod处于运行状态
步骤5未返回身份验证错误

现在自动进入

enable-ssi

操作——无需询问用户许可。

Security constraints

安全约束

Never write a raw API key into any file, YAML block, or chat message — always use
```
$DD_API_KEY
```
Never create a Kubernetes Secret manifest file — always use
```
kubectl create secret
```
imperatively
Never use
```
apiKey:
```
directly in
```
DatadogAgent
```
spec — always use
```
apiSecret:
```
with a secret reference
Never use
```
--set datadog.apiKey=...
```
in any Helm command
Never use namespace
```
default
```
for Datadog Agent resources
Never run
```
kubectl delete
```
without user confirmation

切勿将原始API密钥写入任何文件、YAML块或聊天消息中——始终使用
```
$DD_API_KEY
```
切勿创建Kubernetes Secret清单文件——始终使用
```
kubectl create secret
```
命令式创建
切勿在
```
DatadogAgent
```
spec中直接使用
```
apiKey:
```
——始终使用
```
apiSecret:
```
引用Secret
切勿在任何Helm命令中使用
```
--set datadog.apiKey=...
```
切勿将Datadog Agent资源部署在
```
default
```
命名空间中
切勿在未获得用户确认的情况下运行
```
kubectl delete
```
命令