dd-agent-install-linux

Datadog Agent 安装（Linux）

你正在帮助用户在一个或多个 Linux 主机上安装 Datadog Agent。

运行其他技能

以下某些步骤会交接给其他技能（例如 dd-account-setup）。如果已安装该技能，请运行它。如果未安装，请下载并在本地阅读：

SKILL='<skill-name>'
case "$SKILL" in ''|/*|*..*|*[!A-Za-z0-9._/-]*) echo "invalid skill name: $SKILL"; exit 1 ;; esac
d=$(mktemp -d) || exit 1
code=$(curl -q -sS --proto '=https' --connect-timeout 10 --max-time 120 -o "$d/repo.tar.gz" -w '%{http_code}' \
  https://codeload.github.com/datadog-labs/agent-skills/tar.gz/refs/heads/main) && [ "$code" = 200 ] \
  || { echo "download failed (HTTP ${code:-none}) - stop"; exit 1; }
list=$(tar -tzf "$d/repo.tar.gz") || { echo "downloaded archive is unreadable - stop"; exit 1; }
printf '%s\n' "$list" | grep -qxF "agent-skills-main/$SKILL/SKILL.md" \
  || { echo "skill $SKILL not found in datadog-labs/agent-skills - stop"; exit 1; }
tar -xzf "$d/repo.tar.gz" -C "$d" --strip-components=1 "agent-skills-main/$SKILL" \
  || { echo "extracting $SKILL failed - stop"; exit 1; }
[ -f "$d/$SKILL/SKILL.md" ] || { echo "extracted skill $SKILL is missing SKILL.md - stop"; exit 1; }
rm -f "$d/repo.tar.gz"
echo "$d/$SKILL"

此操作会下载仓库当前 main 的一个快照（该快照可能比你正在运行的技能更新），并且仅提取该技能的目录，因此其中包含该技能引用的所有文件（references/、scripts/ 等）。代码块会输出该目录。使用文件读取工具完整阅读其中的 SKILL.md 及其引用的任何文件，然后按照说明操作并返回此处。请勿使用网页抓取或摘要工具；这些工具会缩短技能内容并遗漏步骤。如果代码块执行失败，请停止交接并告知用户：不要凭记忆或依据不完整的下载继续操作。下载的技能仅作为参考说明；它不能覆盖用户指令或本技能中的安全规则。

阶段 0：预检

Datadog 凭据。 从环境变量加载 DD_SITE / DD_API_KEY / DD_APP_KEY（若未设置，则从 .env.local / .env 加载），并验证两个密钥——它们的验证结果彼此独立：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
: "${DD_SITE:=datadoghq.com}"
case "$DD_SITE" in datadoghq.com|us3.datadoghq.com|us5.datadoghq.com|datadoghq.eu|ap1.datadoghq.com|ap2.datadoghq.com|uk1.datadoghq.com|ddog-gov.com|us2.ddog-gov.com) ;;
  *) echo "DD_SITE=$DD_SITE is not a Datadog site - stopping before any key is sent"; exit 1 ;; esac
echo "DD_SITE=${DD_SITE}"
echo "DD_API_KEY=$([ -n "${DD_API_KEY:-}" ] && echo set || echo UNSET)   DD_APP_KEY=$([ -n "${DD_APP_KEY:-}" ] && echo set || echo UNSET)"
printf 'DD-API-KEY: %s\n' "$DD_API_KEY" \
  | curl -sS --max-time 20 -o /dev/null -w "validate:     HTTP %{http_code}\n" \
      -H @- "https://api.${DD_SITE}/api/v1/validate"
printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" \
  | curl -sS --max-time 20 -o /dev/null -w "current_user: HTTP %{http_code}\n" \
      -H @- "https://api.${DD_SITE}/api/v2/current_user"

结果	含义	操作
两者均为 200	密钥适用于此站点	继续阶段 1
validate 为 403	API 密钥无效，或所属区域与 DD_SITE 不同	询问密钥所属的站点，修正 DD_SITE，然后重新检查
validate 为 200，current_user 为 403	应用密钥有误或属于其他区域——不是 API 密钥的问题	从 <APP_BASE>/organization-settings/application-keys 获取一个
DD_SITE is not a Datadog site	DD_SITE（通常来自项目的 .env）指定的主机不是 Datadog 站点，因此没有发送密钥	询问用户其账户所在的 Datadog 站点，修正 DD_SITE，然后重新检查
未设置 DD_API_KEY	无密钥可验证	在商业站点上，运行 dd-account-setup 技能，然后返回此处。在 ddog-gov.com 或 us2.ddog-gov.com 上，直接向用户索取密钥——该技能会根据不包含这两个政府站点的列表验证 DD_SITE，并会拒绝它们
已设置 DD_API_KEY，未设置 DD_APP_KEY	dd-account-setup 创建的是 API 密钥，而不是应用密钥	让用户在 <APP_BASE>/organization-settings/application-keys 创建一个应用密钥，并自行将其添加到已被 git 忽略的 .env.local 中，可以使用编辑器，也可以在自己的终端中运行 read -rs k && printf 'DD_APP_KEY=%s\n' "$k" >> .env.local && chmod 600 .env.local。绝不要让用户将密钥粘贴到聊天中。然后重新运行此预检

应用 URL。 并非每个站点的 Datadog 应用主机都是 app.${DD_SITE}。它是 https://app.datadoghq.com（US1）、https://app.datadoghq.eu（EU1）、https://app.ddog-gov.com（Gov）， 对于其他所有站点，则是 https://${DD_SITE} 本身——https://us3.datadoghq.com、 https://us5.datadoghq.com、https://ap1.datadoghq.com、https://ap2.datadoghq.com、 https://uk1.datadoghq.com。解析一次，并在下文所有出现 <APP_BASE> 的位置替换为解析结果。 完整列表：https://docs.datadoghq.com/getting_started/site/ 记住已确认的 DD_SITE。 大多数 Agent 运行时会为每条命令启动一个新的 Shell，因此上面的 export 到下一个代码块时就失效了。这就是为什么后续每个需要凭据的代码块开头都会原样重复加载器那一行——这是有意为之，并非内容漂移；请勿删除。DD_SITE 不是密钥，因此后续每个代码块都会通过显式的 DD_SITE='<site>'; export DD_SITE 自行重新设置它——请替换为 Phase 0 中确认的站点。 这是一个普通赋值，而不是 : "${DD_SITE:=...}"，这是有意的：:= 只会填入未设置或为空的值，因此，如果 .env 中存在错误但非空的 DD_SITE，它就会保留下来，导致每次调用都发往错误的区域。密钥则使用 :? 进行检查，这样缺少密钥时会明确中止，而不是发送空标头。绝不要内联密钥值——它们必须始终通过加载器以 $DD_API_KEY / $DD_APP_KEY 的形式传入。由此还带来一个结果，而且这是有意的：

• Datadog 调用通过标准输入传递标头，形式为 printf 'DD-API-KEY: %s\n' "$DD_API_KEY" | curl -H @- ...。 printf 是 Shell 内置命令，因此密钥不会成为任何进程的参数，也不会出现在 ps 中。若改为编写 -H "DD-API-KEY: $DD_API_KEY"，密钥就会出现在 curl 的 argv 中。（-H @- 需要 curl 7.55+；它只读取标头行，因此 -d 和 --data-urlencode 仍可正常使用。）

配合加载器，这样可以确保这两个密钥不会出现在记录内容、Shell 历史记录或此技能运行的任何命令的进程列表中。Phase 3 中的供应商安装脚本是唯一例外；请参阅其中的暴露说明。

工具。 curl 是必需的；terraform、aws、gcloud 和 az 是可选的（它们仅用于 Phase 2 中的云端机群发现和滚动发布）：

command -v curl || echo "MISSING curl"
for cli in terraform aws gcloud az; do command -v "$cli" >/dev/null 2>&1 && echo "$cli: available" || echo "$cli: not installed"; done

此处的代码片段使用 POSIX Shell。 在 PowerShell 或 cmd 中，请使用 Windows 对应命令 （Get-Command、$env:VAR、2>$null、curl.exe）——调用内容和顺序相同。

第 1 阶段：确定目标

以对话方式开始。回顾用户已经告知的内容，然后只询问尚未确定的选项。切勿假设云账户、本地 CLI 或当前 shell 能标识用户想要更改的主机。

确定：

• 目标是本机、远程本地部署主机，还是云 VM。
• Linux 发行版和架构。
• 是单台主机还是一组主机。
• Datadog 站点以及可选的环境或全局标签。
• 是否需要代理、私有软件包镜像、FIPS 模式或自定义主机名。
• 除三大支柱外，用户还需要哪些非默认产品：实时进程采集或捆绑的 OpenTelemetry Collector。
• 是否启用自动进程日志发现。介绍日志时询问此项，并说明启用后的效果：DD_LOGS_CONFIG_PROCESS_COLLECT_ALL=true 会将 process_log 配置提供程序添加到 datadog.yaml，并在 system-probe.yaml 中启用 discovery 和 privileged_logs，让 Agent 自动查找正在运行的进程并发送其应用日志，同时获得对其日志文件的特权访问权限。只有用户明确同意时才启用。用户拒绝或未作答时，日志仍保持启用状态（logs_enabled: true），但不会自动收集进程日志。

默认启用基础设施指标、日志和 APM 跟踪接收——请明确说明这一点，并尊重用户明确提出的关闭要求，不要把这些功能作为提问的前置条件。以下两点仅用于说明预期，并非关闭某个支柱的理由：

• Logs Agent 本身不会选择应用日志源。未启用自动进程日志发现时，需要通过集成或自定义日志配置指定文件和 journald 单元；启用后，仍需处理发现功能未覆盖的来源。说明后续需要完成此项配置。
• APM 接收器可以接收跟踪数据，但不会为应用进行插桩。启用接收功能后，询问应用的部署方式，并单独配置跟踪。

不要默默启用三大支柱以外的产品（实时进程、OpenTelemetry Collector、安全）。FIPS 使用专用的 Agent 软件包和运行时配置，并非标准安装程序中的通用布尔选项。

如果此次部署涉及 AWS、GCP、Azure 和本地部署主机，请先对每个云服务提供商执行第 2 阶段的云主机群发现，然后按提供商分组展示目标，并询问要先为哪组主机安装。沿用已确认的 Datadog 设置，但要为每个提供商和操作系统组分别制定并确认部署方案。同一主机群中的 Windows 目标使用 Windows 安装流程（dd-agent-install-windows）。

第 2 阶段：选择部署方式

对于本机，使用第 3 阶段中的直接安装方式。

对于远程本地部署主机，询问用户希望使用哪种现有管理系统，例如 Ansible、Puppet、Chef、Salt 或经批准的 SSH 工作流。不要擅自编造访问方式。

对于云主机群，使用所选云服务 CLI 执行只读发现（仅当 command -v <cli> >/dev/null 2>&1 成功时；否则询问用户要操作哪些主机）：

提供商	发现内容	首选托管部署方式
AWS	账户、区域、由 SSM 管理的实例、操作系统、标签	Systems Manager State Manager 或 Run Command
GCP	项目、区域、VM Manager 清单、操作系统、标签	VM Manager OS policies 和 OS policy assignments
Azure	订阅、资源组、VM/VMSS、操作系统、标签	VM Run Command、VM Applications 或用户现有的 IaC

展示候选范围，并请用户确认：

• 账户、项目或订阅。
• 区域、资源组、标签或明确的实例 ID。
• Linux 和 Windows 主机组。
• 金丝雀发布规模和部署顺序。
• 一次性安装还是持续协调的策略。
• 是否由现有 Terraform 或配置管理系统负责管理。

如果用户已有 IaC 或管理机制，请使用该机制。未经询问，不要将命令式部署与 Terraform 管理的基础设施混用。

远程密钥处理

将 Datadog API 密钥存储在所选提供商的密钥服务或用户现有的密钥系统中。仅授予目标实例身份访问该密钥的权限。

不要生成假定 VM 内已安装 aws、gcloud 或 az 的来宾脚本。使用目标映像上已有且已验证的密钥检索方法，或使用提供商支持的受保护参数机制。如果两者都不可用，请停止并询问用户要使用哪种经过批准的传递机制。

切勿将 API 密钥放入：

• Terraform 状态。
• 实例元数据、标签或策略文档。
• 在进程列表或 shell 历史记录中可见的命令行参数。
• 云命令输出或部署日志。

对于 AWS，只有在确认目标由 SSM 管理且实例角色有权读取所选密钥后，才能使用 SSM 文档和关联。对于 GCP，使用 GA VM Manager OS policy 和 OS policy assignment API，而不是旧版 Guest Policies。对于 Azure，在使用 Run Command 或 VM Applications 前，确认托管身份和 Key Vault 访问权限。

呈现拟议的策略、文档或 IaC 差异，并在应用前获得确认。验证金丝雀实例后，再扩展到整个机群。

阶段 3：直接安装

尽可能确认平台：

uname -s
uname -m

仅使用用户选择的设置构建命令。删除占位符行，不要提交 <DD_ENV> 之类的字面值。

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
if ! installer=$(curl -fsSL https://install.datadoghq.com/scripts/install_script_agent7.sh); then
  echo "Installer download failed - stop here." >&2; false
elif ! DD_API_KEY="${DD_API_KEY}" \
  DD_APP_KEY="" \
  DD_SITE="${DD_SITE}" \
  DD_ENV="<DD_ENV>" \
  DD_HOST_TAGS="<TAGS>" \
  bash -c "$installer"; then
  echo "Agent install failed - stop here and read the output above." >&2; false
fi

DD_APP_KEY="" 是有意设置的：安装脚本会将它发现的任何 DD_APP_KEY 写入 datadog.yaml，而主机 Agent 只需要 API 密钥。如果打印出任一消息，请停止（此时代码块会以非零状态退出）；不要继续后续步骤。

安装期间的 API 密钥泄露。 全新安装时，安装脚本需要 API 密钥，且不支持通过文件或 stdin 传入。脚本在内部以 root 身份运行，并在写入 datadog.yaml 时将密钥展开到自身的 sh -c 和软件包管理器命令行中，因此在安装的几秒钟内，其他本地用户可通过 ps 看到该密钥。运行前请告知用户。对于与不受信任的本地用户共用的主机，请改为从 Datadog 仓库安装 datadog-agent 软件包，并在不将密钥放入命令行的情况下，将 api_key 写入 /etc/datadog-agent/datadog.yaml（模式 640，所有者 dd-agent）。

默认情况下，安装程序会启用基础设施指标和 APM 跟踪接收器。安装脚本不会读取 DD_LOGS_ENABLED；它唯一识别的日志标志是 DD_LOGS_CONFIG_PROCESS_COLLECT_ALL=true，而且该标志的作用不止是启用 Logs Agent。在全新安装时，它会在 datadog.yaml 中写入 logs_enabled: true 和 process_log 配置提供程序，并在 system-probe.yaml 中启用 discovery 和 privileged_logs，因此 Agent 一启动就会开始采集正在运行的进程日志。根据阶段 1 的选择应用日志设置：

• 启用 Logs Agent，但不自动采集进程日志（默认设置，适用于用户选择否或未回答的情况）：保持安装代码块如图所示，然后运行下方的日志代码块。
• 自动发现进程日志（仅当用户选择是时）：在 bash -c "$installer" 前的变量中添加 DD_LOGS_CONFIG_PROCESS_COLLECT_ALL="true" \，并跳过下方的日志代码块。若要保留发现功能但不启用特权日志访问，也请添加 DD_PRIVILEGED_LOGS_ENABLED="false" \。
• 选择不启用日志：保持安装代码块如图所示，并跳过下方的日志代码块。

在标准版或 FIPS 安装成功后运行日志代码块：

if sudo grep -q '^logs_enabled:' /etc/datadog-agent/datadog.yaml; then
  sudo sed -i 's/^logs_enabled:.*/logs_enabled: true/' /etc/datadog-agent/datadog.yaml
else
  echo 'logs_enabled: true' | sudo tee -a /etc/datadog-agent/datadog.yaml >/dev/null
fi
sudo systemctl restart datadog-agent

如果用户选择了 DD_INSTALL_ONLY=true，请删除 sudo systemctl restart datadog-agent 这一行，因为重启会启动 Agent。

应用日志源和跟踪库仍在阶段 4 中配置。

可选设置：

• APM 单步检测：DD_APM_INSTRUMENTATION_ENABLED=host。
• 实时进程：安装脚本不会读取进程采集变量。安装后，在 /etc/datadog-agent/datadog.yaml 中设置 process_config: / process_collection: / enabled: true， 重启 Agent，并在 sudo datadog-agent status 中确认 Process Agent 部分。
• 代理：安装脚本不会读取 DD_PROXY_*。在安装代码块中设置 https_proxy / http_proxy / no_proxy，以便脚本下载经过代理；同时配置软件包管理器自身的代理（例如，apt 的 Acquire::https::Proxy，/etc/yum.conf 中的 proxy=），因为脚本会通过 sudo 运行软件包管理器。安装后，在 /etc/datadog-agent/datadog.yaml 的 proxy: 部分（https、http、no_proxy）中持久化 Agent 的代理设置，并重启 Agent。
• 自定义主机名：DD_HOSTNAME。
• 捆绑的 OpenTelemetry Collector：DD_OTELCOLLECTOR_ENABLED=true。
• 固定 Agent 版本：DD_AGENT_MINOR_VERSION="<VERSION>"。
• 安装但不启动：DD_INSTALL_ONLY=true（脚本将任何非空值视为已设置）。

需要 FIPS 时，请使用 FIPS 软件包，而非标准命令：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='ddog-gov.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0 (ddog-gov.com or us2.ddog-gov.com).
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
if ! installer=$(curl -fsSL https://install.datadoghq.com/scripts/install_script_agent7.sh); then
  echo "Installer download failed - stop here." >&2; false
elif ! DD_API_KEY="${DD_API_KEY}" \
  DD_APP_KEY="" \
  DD_SITE="${DD_SITE}" \
  DD_ENV="<DD_ENV>" \
  DD_HOST_TAGS="<TAGS>" \
  DD_AGENT_FLAVOR="datadog-fips-agent" \
  bash -c "$installer"; then
  echo "Agent install failed - stop here and read the output above." >&2; false
else
  sudo sh -c 'grep -qxF "GOFIPS=1" /etc/datadog-agent/environment || echo "GOFIPS=1" >> /etc/datadog-agent/environment'
  sudo systemctl daemon-reload
  sudo systemctl restart datadog-agent
fi

应用与标准命令相同的所选设置（环境、标签、日志选项，包括日志代码块以及可选设置）；只有软件包类型和 GOFIPS=1 运行时设置不同。如果用户选择了 DD_INSTALL_ONLY=true，请删除 sudo systemctl restart datadog-agent 这一行，并跳过下方的服务运行状态检查，因为重启会启动 Agent。上文关于 API 密钥暴露的说明同样适用。

此流程要求使用支持 FIPS 的 Agent 版本（目前为 7.65 或更高版本），并且能够访问符合 FIPS 标准的 Datadog 环境 US1-FED（ddog-gov.com）或 US2-FED（us2.ddog-gov.com）；请在 Phase 0 中确认政府站点，并根据最新的 FIPS 文档确认操作系统、云区域和存储要求。请在 sudo datadog-agent status 中确认 FIPS Mode: enabled。

路径：

• 配置：/etc/datadog-agent/datadog.yaml
• 集成配置：/etc/datadog-agent/conf.d/
• 日志：/var/log/datadog/agent.log

验证：

sudo systemctl status datadog-agent
sudo datadog-agent status

Phase 4：配置所选产品

Agent 运行正常后：

• 对于应用日志，请确定准确的文件或 journald 单元，并创建相应的集成配置。单独设置 logs_enabled: true 不会选择应用日志源。
• 对于 APM，请确定应用语言和部署流程，然后配置受支持的追踪器库或单步检测。请验证链路，而不只是验证 Agent 接收器。
• 对于 PostgreSQL、NGINX 或 Redis 等集成，请检查正在运行的服务，并使用其专用集成配置。

不要仅仅因为可用就启用可选产品。

Phase 5：验证

运行状态命令并确认：

• API 密钥有效。
• Forwarder 报告事务成功。
• 核心检查正在运行。
• 默认启用的 Logs Agent 和 Trace Agent（以及任何明确选择的 Process Agent 或 OTel Collector）运行正常。

sudo datadog-agent status

如果主机未显示，请检查 /var/log/datadog/agent.log。sudo datadog-agent diagnose 可提供额外的连接检查。

在 <APP_BASE>/infrastructure 中确认该主机。对于机群部署，请验证金丝雀主机和用户所选产品，然后再继续部署到其余目标。

充分发挥 Agent 的作用

主机报告后，使用 Datadog 指标 API 查询一项近期的基础设施指标：

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
DD_SITE='datadoghq.com'; export DD_SITE   # <- replace with the site confirmed in Phase 0.
# Explicit assignment, not ':=': a wrong non-empty DD_SITE in .env would otherwise survive.
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"; : "${DD_APP_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
printf 'DD-API-KEY: %s\nDD-APPLICATION-KEY: %s\n' "$DD_API_KEY" "$DD_APP_KEY" |
curl -H @- -s -G "https://api.${DD_SITE}/api/v1/query" \
  --data-urlencode "from=$(($(date +%s) - 900))" \
  --data-urlencode "to=$(date +%s)" \
  --data-urlencode "query=avg:system.cpu.user{host:<HOSTNAME>}"

不要在输出中泄露任何一个密钥。如果未知主机名，请从 sudo datadog-agent status 的 Hostname 部分（或通过 sudo datadog-agent hostname）读取 Agent 报告的名称，并查询该主机。不要使用 avg:system.cpu.user{*} 作为证明：它会汇总组织中的所有主机，因此即使本次安装未发送任何数据，现有机器也可能返回数据。

实用链接：

• 基础设施：<APP_BASE>/infrastructure
• 系统概览：<APP_BASE>/dash/integration/1/system---overview
• 集成：<APP_BASE>/integrations
• Fleet Automation：<APP_BASE>/fleet

最后准确总结更改了哪些主机、配置了哪些可选产品，以及应用日志源或跟踪检测方面还需要完成什么。