Creating an environment for a new subsidiary, adding a user group, generating a token for the deployment pipeline, checking node status before maintenance: taken one at a time, these tasks take a few clicks in the Cluster Management Console. Repeated every week, across several clusters, by several administrators, they become a source of errors and configuration drift, unless you hand them over to the Dynatrace Managed Cluster API.
The Cluster API is built for exactly that. Separate from the environment API (https://{your-domain}/e/{environment-id}/api/…), it works at platform level: https://{your-domain}/api/cluster/v2/… for v2, and mostly https://{your-domain}/api/v1.0/onpremise/… for v1. It has no equivalent for a SaaS customer, because it is the cluster operator — you — who needs it.
This article covers what it can do, how to secure it, and offers concrete scripts to start serious automation.
Dynatrace Managed Cluster API or environment API?
| Criterion | Cluster API | Environment API |
|---|---|---|
| Base URL |
https://{your-domain}/api/cluster/v2 and …/api/v1.0/onpremise (v1) |
`https://{your-domain}/e/{id}/api/v1 |
| Token | Cluster token (CMC, Settings > API tokens) | Environment token |
| Scope | Nodes, environments, users, groups, licences, cluster settings | Entities, metrics, problems, monitoring settings, OneAgent deployment |
| Typical users | Platform team | Ops teams, CI/CD, third-party tools |
Full automation often uses both: the Cluster API creates the environment and a first environment token, then the environment API takes over for monitoring configuration.
What is commonly automated
- Environment lifecycle: creation, renaming, enabling/disabling, quotas (host units, sessions, storage).
- Tokens: generating environment tokens to bootstrap tools.
- Users and groups: creating groups, assigning permissions, audit exports (see the Managed access model).
- Cluster status: list of nodes, state, version; useful before and after maintenance.
- Settings: SMTP, proxy, backup, depending on what your version exposes.
The exact list of endpoints depends on the Managed version. The authoritative reference is the Cluster API explorer, available from the CMC, which documents every route and lets you try it.
Step-by-step tutorial
Step 1 — Create a dedicated Cluster API token
In the CMC, open Settings > API tokens, Cluster tokens section, and create one token per use: {% raw %}audit, environment-provisioning, and so on. Tick only the permissions you need among Service Provider API (ServiceProviderAPI, required for environments, users, groups and nodes), Cluster token management, Read settings and Write settings. Store the value in your secrets vault; it will not be shown again.
export DT_CLUSTER="https://{your-domain}"
export DT_CTOKEN="{token}" # load from a vault, never hard-coded in a repository
Step 2 — First call: list environments
curl -s -H "Authorization: Api-Token $DT_CTOKEN" \
-H "Accept: application/json" \
"$DT_CLUSTER/api/cluster/v2/environments" | python3 -m json.tool
You get the list of environments with their ID, name, state and quotas. A 401 means token authentication failed: check its validity and permissions.
Step 3 — Create an environment idempotently
A good automation script can be rerun without side effects. So we check whether the environment exists before creating it:
#!/usr/bin/env bash
set -euo pipefail
NOM="${1:?usage: $0 environment-name}"
existe=$(curl -s -H "Authorization: Api-Token $DT_CTOKEN" \
"$DT_CLUSTER/api/cluster/v2/environments" \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(any(e.get('name')=='$NOM' for e in d.get('environments',[])))")
if [ "$existe" = "True" ]; then
echo "Environment $NOM already exists, nothing to do."
exit 0
fi
curl -s -X POST -H "Authorization: Api-Token $DT_CTOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\": \"$NOM\", \"state\": \"ENABLED\", \"tags\": [\"provisionne-par-api\"]}" \
"$DT_CLUSTER/api/cluster/v2/environments"
The list comes back in the environments array and is paginated (nextPageKey): on a large cluster, follow the pagination or raise pageSize. The creation response contains the new environment’s ID, which you should keep for the next steps.
Step 4 — Bootstrap the environment with a token
By adding ?createToken=true to the creation POST, the response contains a tokenManagementToken (scopes apiTokens.read, apiTokens.write and TenantTokenManagement). It lets you create, through POST /e/{id}/api/v2/apiTokens, an environment token with limited scopes. That token drives a second phase of scripts that pushes the baseline configuration through the environment API: automatic tags, management zones, alerting profiles.
export DT_ENV="$DT_CLUSTER/e/{environment-id}"
curl -s -H "Authorization: Api-Token {environment-token}" \
"$DT_ENV/api/v2/settings/schemas" | python3 -m json.tool | head -40
Step 5 — Check node status before maintenance
Query the v1 route that returns the cluster’s known nodes (Service Provider API permission), including their operationState and version, and refuse to continue if a node is not in the expected state:
curl -s -H "Authorization: Api-Token $DT_CTOKEN" \
"$DT_CLUSTER/api/v1.0/onpremise/cluster" | python3 -m json.tool
Combined with a systemctl or a df -h /var/opt/dynatrace-managed run on each node through your configuration management tool, this check makes a reliable maintenance « pre-flight check ».
Step 6 — Integrate with existing tooling
The same calls fit easily into Ansible (the uri module), a CI pipeline, or Terraform through a provider compatible with your version. The principle stays the same: a Git repository describes the desired state (environments, groups, quotas), and a job compares it with the actual state and applies the difference.
Best practices
- One token per use, minimal scopes, an expiry date, scheduled rotation.
- Never a plain-text token in a script, a repository or shell history; use a vault and environment variables.
- Idempotence: check before creating, update rather than recreate.
- Dry-run mode: print the action plan before applying it.
- Error handling: check the HTTP code (
curl -w "%{http_code}") and respect rate limits (429 response). - Regression tests after every Managed update: APIs evolve, and v1 routes may be deprecated in favour of v2.
- Traceability: every automated action must be visible in the audit log and linked to a commit.
Frequently asked questions
What is the difference between the Cluster API and the environment API?
The Cluster API (/api/cluster/v2 and /api/v1.0/onpremise, cluster token created in the CMC) covers the platform: nodes, environments, users, groups, licences. The environment API (/e/{id}/api/…, environment token) covers monitoring: entities, metrics, problems, settings. Full automation often chains the two.
What do 401, 403 and 429 errors mean?
A 401 means token authentication failed (invalid, expired or missing the required permission), a 403 that access is denied, and a 429 that you have hit the rate limits: slow your calls down and retry later.
Where can you find the exact list of available routes?
In the Cluster API explorer, available from the CMC: it documents every route for your version and lets you try it. Recheck your scripts after each update, as some v1 routes may be deprecated in favour of v2.
Conclusion
The Cluster API is the tool that takes Dynatrace Managed administration from hand-crafted clicking to industrial-grade operations. By starting with simple, idempotent scripts — inventory, environment creation, audit export — and then plugging them into your configuration tooling, you gain speed, consistency across clusters and traceability. All without ever leaving the standards: HTTP, JSON, curl and a vault for secrets.
span.observer is an independent community blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of Dynatrace LLC. Always check values (ports, versions, sizes) against the official documentation for your Managed version.
Originally published on span.observer. French version: https://span.observer/fr/api-cluster-automatisation/.
Top comments (0)