/dt-setup-oneagent

name: dt-setup-oneagent
description: Reference knowledge for installing, uninstalling, or creating-and-installing Dynatrace OneAgent across VM/server, Kubernetes (Operator + DynaKube), AWS Lambda (layer + env vars, plus optional fresh function provisioning), Windows hosts, remote Linux hosts / EC2 instances over SSH, and Azure VMs / VM Scale Sets. Returns documented endpoints, env vars, token scopes, and copy-paste-ready commands. Returns the exact commands to run rather than executing them. Use when the user asks to install or uninstall OneAgent, or asks "how do I…", "what URL/scope/var do I need for…", or "explain the OneAgent deployment for X".
license: Apache-2.0

Deploy Dynatrace OneAgent — knowledge reference

This skill is **reference-only**. It contains the documented endpoints, environment variables, token scopes, and commands that an operator (or another agent) needs to install OneAgent manually across the supported targets. It executes nothing.

> This skill gives you the commands; it does not run them. Follow the procedure for the target you need, substituting the environment URL and token as documented below.

Hard rules for any agent consuming this skill

• **Operate only on resources the user explicitly named.** Never create a placeholder/test Lambda, IAM role, K8s namespace, secret, S3 bucket, EC2 instance, or any other fixture on your own initiative — not to "demonstrate", not "while we're at it", not preemptively. If the named resource doesn't exist and the user hasn't asked for it to be created, stop and ask. Side resources (additional Secrets Manager entries, monitoring, helper stacks) must not be provisioned silently — surface them as confirmation questions with the exact definition first.
• **Explicit user-driven create modes are fine.** When the user passes `--create` (or explicitly says "yes, create it" after being asked), provisioning exactly the resources documented for that mode is the right thing to do — see *Create a new function and install OneAgent* in [references/aws-lambda.md](references/aws-lambda.md) for the documented set. Don't second-guess the function name the user typed: do **not** pattern-match on names like "test", "demo", "scratch", "tmp" and refuse, warn, or insist on an alternative. The input is authoritative; the rule above is about *silent* or *unsolicited* creation, not user-requested creation.
• **Never persist the API token.** The token's only job is to (a) authenticate the OneAgent artifact download / layer-ARN lookup and (b) get handed to the target system (Lambda env var or Secrets Manager, Linux installer, DynaKube secret) as part of the install. Do not cache it to local files, write it to scratch scripts, leave it in shell history, copy it into PR descriptions, or store it anywhere outside the target system that strictly needs it. Treat each run as fresh: supply via env var or 0600 file, use, discard.
• **Never echo or log the API token.** When you have to reference it in a command, write `$DT_API_TOKEN` or an elided prefix (`dt0s16.…`, `dt0c01.…`). Don't paste the literal value into prose.
• **Never assume the env URL, and confirm the tenant before installing.** Targeting the wrong environment fails *silently*: the install succeeds and the host or function simply reports to a tenant nobody is watching. An environment URL the user stated explicitly always wins over anything derived from a tool default or a previous run — never let a cached or discovered value override it. State the tenant you are about to use and let the user correct you. Tenant IDs (`abc12345`) and labs vs. prod determine the correct host.
• **Writes that take a collection replace it — read, merge, then write.** Several APIs here accept a whole collection and overwrite whatever was there: `aws lambda update-function-configuration` does this for **both** `--environment` and `--layers`, so sending only the Dynatrace values silently deletes the function's own variables and any other layers. Always read current state, merge your additions into it, and write the union back. Take a rollback snapshot before the first write. This applies wherever you are about to replace a set rather than add to one.
• **Deriving the env URL from dtctl.** `dtctl config current-context` returns only the *context name* (e.g. `my-env`), not a URL. The URL comes from `dtctl config describe-context <ctx>`. Do **not** pipe that straight into `jq`: some dtctl versions ignore `-o json` and print a human table (`Environment: https://…`) while still exiting 0, so jq dies on a parse error and takes any `set -e -o pipefail` script down with it. Check the output really is JSON first, and fall back to scraping the `Environment:` line:

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 normalization

Dynatrace's "new platform" URLs and the classic OneAgent installer endpoints differ. Before constructing installer URLs, convert:

| Input (Dynatrace UI / docs) | Use for installer endpoints | |----------------------------------------|---------------------------------------| | `https://<id>.apps.dynatrace.com` | `https://<id>.live.dynatrace.com` | | `https://<id>.<region>.apps.dynatracelabs.com` | `https://<id>.<region>.dynatracelabs.com` | | Anything else | unchanged |

The tenant ID is the first dot-separated segment (`<id>`).

---

Token types and the Authorization header

Two token families are in play, and **the `Authorization` scheme is chosen by the token's prefix, not by which endpoint you call**:

| Token | Prefix | Header | |---|---|---| | Platform token | `dt0s1