dt-setup-oneagent

部署 Dynatrace OneAgent — 知识参考

此技能仅供参考。其中包含操作员（或其他 Agent）在支持的目标上手动安装 OneAgent 所需的已记录端点、环境变量、令牌范围和命令。它不会执行任何操作。

此技能提供命令，但不会运行这些命令。请按照所需目标的步骤操作，并按下文说明替换环境 URL 和令牌。

使用此技能的任何 Agent 必须遵守的硬性规则

• 只能操作用户明确指定的资源。 绝不要自行创建占位或测试用的 Lambda、IAM 角色、K8s 命名空间、密钥、S3 存储桶、EC2 实例或任何其他测试资源——无论是为了“演示”、为了“顺便做一下”还是提前准备。如果指定的资源不存在，且用户未要求创建，请停止并询问。不得默默配置附属资源（额外的 Secrets Manager 条目、监控、辅助堆栈等）；应先提出确认问题，并明确说明具体定义。
• 用户明确要求的创建模式没有问题。 用户传入 --create（或在被询问后明确表示“是，创建”）时，按该模式的文档说明配置相应资源是正确做法——参见 references/aws-lambda.md 中的 Create a new function and install OneAgent。不要质疑用户输入的函数名称：不要根据名称是否包含“test”、“demo”、“scratch”、“tmp”等模式而拒绝、警告或坚持要求更换名称。用户输入具有权威性；上述规则针对的是默默或未经请求的创建，而非用户要求的创建。
• 绝不持久化 API 令牌。 令牌只用于 (a) 验证 OneAgent 构件下载或层 ARN 查找，以及 (b) 在安装过程中传递给目标系统（Lambda 环境变量或 Secrets Manager、Linux 安装程序、DynaKube 密钥）。不要将其缓存到本地文件、写入临时脚本、留在 shell 历史记录中、复制到 PR 描述中，也不要存储在目标系统之外的任何地方。每次运行都视为全新操作：通过环境变量或权限为 0600 的文件提供令牌，使用后立即丢弃。
• 绝不回显或记录 API 令牌。 在命令中需要引用令牌时，使用 $DT_API_TOKEN 或省略部分内容的前缀（dt0s16.…、dt0c01.…）。不要在文字中粘贴令牌的实际值。
• 绝不假定环境 URL，并在安装前确认租户。 如果目标环境错误，安装会静默失败：安装成功，但主机或函数只会向无人监控的租户报告。用户明确指定的环境 URL 始终优先于工具默认值或之前运行得出的任何值——绝不能让缓存或发现的值覆盖它。说明即将使用的租户，并允许用户纠正。租户 ID（abc12345）以及 labs 与 prod 的区别决定了正确的主机。
• 对整个集合进行写入时，应先读取、合并，再写入。 此处有多个 API 接收整个集合并覆盖原有内容：aws lambda update-function-configuration 的 --environment 和 --layers 都是如此，因此只发送 Dynatrace 值会静默删除函数自身的变量和其他层。始终先读取当前状态，将新增内容合并进去，再写回合并后的完整集合。在首次写入前先创建回滚快照。凡是要替换整个集合而非仅添加内容时，都适用此规则。
• 从 dtctl 推导环境 URL。 dtctl config current-context 只会返回上下文名称（例如 my-env），而非 URL。URL 来自 dtctl config describe-context <ctx>。不要直接将其通过管道传给 jq：某些版本的 dtctl 会忽略 -o json，并输出人类可读的表格（Environment: https://…），同时仍以 0 退出；这样 jq 会因解析错误而退出，并导致任何启用了 set -e -o pipefail 的脚本退出。先确认输出确实是 JSON；否则回退到提取 Environment: 行：

CTX="$(dtctl config current-context 2>/dev/null || true)"
OUT="$(dtctl config describe-context "$CTX" -o json 2>/dev/null || true)"
if printf '%s' "$OUT" | jq -e . >/dev/null 2>&1; then
  DT_ENV_URL="$(printf '%s' "$OUT" | jq -r '.environment // .url // empty')"
else
  DT_ENV_URL="$(printf '%s' "$OUT" | awk 'tolower($1) ~ /^(environment|url):$/ {print $2; exit}')"
fi

---

URL 规范化

Dynatrace 的“新平台”URL 与经典 OneAgent 安装程序端点有所不同。在构造安装程序 URL 之前，请进行以下转换：

输入（Dynatrace UI / 文档）	安装程序端点使用的 URL
https://<id>.apps.dynatrace.com	https://<id>.live.dynatrace.com
https://<id>.<region>.apps.dynatracelabs.com	https://<id>.<region>.dynatracelabs.com
其他任何值	保持不变

租户 ID 是按点分隔后的第一段（<id>）。

---

令牌类型与 Authorization 标头

这里涉及两类令牌，Authorization 方案由令牌前缀决定，而非由你调用的端点决定：

令牌	前缀	标头
平台令牌	dt0s16.	Authorization: Bearer <token>
访问令牌（经典 API 令牌）	dt0c01.	Authorization: Api-Token <token>
PaaS 令牌	dt0s01.	Authorization: Bearer <token>
OAuth 客户端密钥	dt0s02. / dt0s03.	❌ 不可直接使用——必须先交换为 bearer 令牌

平台令牌是面向未来的默认选择。 Dynatrace 正在弃用访问令牌：新租户已无法创建访问令牌，且经典 API 端点正在更新，以接受平台令牌。请勿假设令牌以 dt0c01. 开头。此规则的参考实现是 dtwiz 的 AuthHeader()（pkg/installer/installer.go）：dt0c01.* → Api-Token，其他情况 → Bearer。

有一条路径会将令牌传递给一个历来要求 PaaS / 访问令牌的组件——如果该组件拒绝平台令牌，请在该处使用 dt0c01. 访问令牌：

• Kubernetes——Dynatrace Operator 使用 dynakube 密钥进行身份验证。

VM、远程 VM / EC2、Windows 和 Lambda 会直接调用 Deployment API，使用任一类型的令牌均可。

按目标划分的令牌范围

对于平台令牌（dt0s16.），与 OneAgent 相关的范围位于Fleet management下：fleet-management:oneagents:download、fleet-management:oneagent.connection-info:read、fleet-management:oneagent.tokens:read、fleet-management:cluster-id:read；Kubernetes 还需要 fleet-management:activegates:download 和 fleet-management:activegate.tokens:create。通过 Dynatrace QuickStart 应用生成令牌会自动配置一组可用的范围。

对于经典访问令牌（dt0c01.）：

目标	所需令牌范围
VM / Windows	InstallerDownload（PaaS）
Kubernetes	InstallerDownload、settings.read、settings.write、activeGateTokenManagement.create——Dynatrace UI 的“Kubernetes: Dynatrace Operator”模板会设置这四项。
Azure VM / VMSS	InstallerDownload（PaaS）。Azure 侧：调用方的 az 身份需要在该资源上具有 Contributor 角色，或任何授予 Microsoft.Compute/.../extensions/write 权限的角色。
AWS Lambda（运行时令牌）	OneAgent 层在运行时使用的连接身份验证令牌。它与安装程序令牌不同。在 Dynatrace UI 的 Access tokens 下创建，范围设为 entities.read，或使用 Hub → AWS Lambda 模板。

令牌从不绑定到用户名——它们属于租户。

---

目标

每个目标都有自己的参考文档。它们遵循上述相同的规则、URL 规范化方式和令牌指南——请先阅读这些内容，再阅读所需的参考文档。

托管式 Kubernetes 发行版包含在 Kubernetes 参考文档中，而非单独列出：安装方式相同，只有节点类型不同，因此差异会列在其所修改的操作步骤旁边。

目标	参考文档
VM / 服务器（Linux、macOS）	下文 — 其他所有目标都以此为基础
通过 SSH 连接的远程 VM / EC2	→ references/remote-vm-ec2.md
Windows 主机（WSL 或原生）	→ references/windows.md
Kubernetes（Operator + DynaKube）— 包括 EKS、Fargate 和 Bottlerocket 限制	→ references/kubernetes.md
AWS Lambda（层 + 环境变量）	→ references/aws-lambda.md
Azure VM / VM Scale Set（VM 扩展）	→ references/azure-vm.md

按平台分类

上表按安装机制整理，因为安装机制决定了操作步骤。如果你是从特定云平台进入此文档，请参阅以下内容：

平台	部署目标	前往
AWS	EC2 实例	remote-vm-ec2.md
	EKS — EC2 节点	kubernetes.md
	EKS — Fargate 或 Bottlerocket 节点	kubernetes.md § AWS EKS specifics — 不支持全栈模式，仅支持 applicationMonitoring
	Lambda 函数	aws-lambda.md
Azure	VM 或 VM Scale Set	azure-vm.md
	AKS	kubernetes.md — 不是 VM 扩展，即使节点池是 VMSS 也是如此
Google Cloud	GKE（标准版）	kubernetes.md
	GKE Autopilot	kubernetes.md 中的 Operator 路径 — 不支持全栈模式，与 Bottlerocket 相同。不涵盖 Autopilot 专属调优
	Compute Engine VM	remote-vm-ec2.md — SSH 操作步骤并非 AWS 专用
本地部署 / 其他环境	你已登录的 Linux 或 macOS	下文
	通过 SSH 连接的 Linux	remote-vm-ec2.md
	Windows	windows.md
	Kubernetes，或通过标准 Operator 部署的 OpenShift	kubernetes.md — 不涵盖传统的 OpenShift node-config-operator 路径

VM / 服务器（Linux、macOS）

端点（将 ${DT_ENV_URL_NORMALIZED} 和 ${ARCH} 替换为相应值，其中 ARCH ∈ x86 | arm | ppc64le | s390）：

GET ${DT_ENV_URL_NORMALIZED}/api/v1/deployment/installer/agent/unix/default/latest?arch=${ARCH}&flavor=default
Header: Authorization: Api-Token ${DT_API_TOKEN}   # dt0c01.… access token
        Authorization: Bearer ${DT_API_TOKEN}      # dt0s16.… platform token

安装命令：

根据令牌设置方案——dt0c01.… 使用 Api-Token，dt0s16.… 使用 Bearer：

DT_AUTH="Api-Token ${DT_API_TOKEN}"   # platform token: DT_AUTH="Bearer ${DT_API_TOKEN}"

wget -O Dynatrace-OneAgent-Linux.sh \
  --header="Authorization: ${DT_AUTH}" \
  "${DT_ENV_URL_NORMALIZED}/api/v1/deployment/installer/agent/unix/default/latest?arch=${ARCH}&flavor=default"

sudo /bin/sh Dynatrace-OneAgent-Linux.sh \
  --set-monitoring-mode=fullstack \
  --set-app-log-content-access=true \
  [--set-host-group=<name>] \
  [--set-network-zone=<zone>]

重启注意事项： OneAgent 无法注入已在运行的进程。安装后，请重启你希望监控的工作负载。

卸载：

sudo /opt/dynatrace/oneagent/agent/uninstall.sh

此操作会移除 systemd 单元、/opt/dynatrace，以及注入 Agent 的 /etc/ld.so.preload 条目。

---

不应使用此技能的情况

• 用户希望由你代为安装，而不是了解安装方法。→ 仍可使用此技能：遵循相应目标的操作步骤并运行命令，先确认租户。
• 用户询问安装失败的原因并希望获得解释。→ 适合使用此技能。
• 用户需要的目标不在此技能的涵盖范围内（Azure Functions / App Service / Container Apps、传统的 OpenShift node-config-operator、GKE Autopilot 专属配置、ECS Fargate）。→ 请参阅 https://docs.dynatrace.com；此技能涵盖 VM/服务器、通过 SSH 连接的远程 VM/EC2、Windows、Kubernetes 和 AWS Lambda。

References

• OneAgent Linux install: https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/linux
• OneAgent Windows install: https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/windows
• Kubernetes (Operator + DynaKube): https://docs.dynatrace.com/docs/ingest-from/setup-on-k8s/deployment/full-stack-observability
• Dynatrace Operator releases: https://github.com/Dynatrace/dynatrace-operator/releases
• AWS Lambda (Hub): https://www.dynatrace.com/hub/detail/amazon-web-services-aws-lambda/