Planning a Dynatrace Managed cluster upgrade and OneAgent updates

In a Dynatrace Managed environment, an update is never « something that just happens ». The cluster runs on your servers, in your datacentres, on the schedule of your maintenance windows. Each new version brings security fixes, interface improvements and support for newly monitored technologies — but it also involves a rolling restart of services, a disk space check and coordination with application teams. A Dynatrace Managed cluster upgrade should therefore be planned like any other operational change.

The real trap is falling behind. A cluster that skips several versions ends up having to catch up in several steps, while the OneAgents deployed on hundreds of hosts age in turn and drop out of the compatibility window. You then face a project lasting several weeks where a monthly routine would have done.

This article sets out a method for planning updates of the Managed cluster and its OneAgents: understand what gets updated and in what order, prepare the prerequisites, drive the operation from the Cluster Management Console (CMC) and the API, then industrialise the whole process.

What gets updated (and in what order)

A Managed deployment has several layers, each with its own lifecycle:

• Cluster nodes: Dynatrace server, Cassandra, Elasticsearch, transaction storage, web components. They are updated together, node by node.
• Cluster ActiveGates and Environment ActiveGates: they talk to the cluster and must stay within a compatible version range.
• OneAgents: installed on monitored hosts, managed per environment, per host group or individually.
• Dynatrace Operator on Kubernetes, which itself manages the OneAgents and ActiveGates declared in the DynaKube resource.

The golden rule: cluster first, ActiveGates next, OneAgents last. This order follows from how Managed works: OneAgent, ActiveGate and RUM packages are distributed by the cluster itself, with its updates. Compatibility windows between versions must be checked in the official documentation; the CMC, for example, flags Cluster ActiveGates that are more than five versions behind.

Automatic or manual updates?

When the cluster is connected to Mission Control, the CMC can download new versions and offer automatic installation during a maintenance window you define. In offline mode, the packages received by email are uploaded to the CMC, which distributes them to all nodes. An automatic update only runs in the first maintenance window that occurs 24 hours after the package was downloaded. Either way, you decide when.

Preparing a Dynatrace Managed cluster upgrade

Most update incidents come from an overlooked prerequisite. Before each operation, go through this list:

• Cluster health: every node is « Healthy » in the CMC, with no storage alert in progress.
• Disk space: the update unpacks the new binaries under /opt/dynatrace-managed and can trigger data migrations under /var/opt/dynatrace-managed. The documentation requires at least 5 GB free on the installation partition, and 24 hours between two cluster updates.
• Recent backup: make sure the last cluster backup to NFS storage completed successfully.
• Release notes: read about behaviour changes, deprecated technologies and the minimum required OneAgent and ActiveGate versions.
• Communication: warn users; with fewer than three nodes, the cluster is unreachable during the update; above that, the interface stays available, but occasional disconnections are possible.

Step-by-step tutorial

Step 1 — Check the state of the cluster and nodes

In the CMC, open the cluster overview page and confirm that every node is up and running. At system level, on each node:

systemctl list-units --type=service | grep -i dynatrace
df -h /opt/dynatrace-managed /var/opt/dynatrace-managed
sudo /opt/dynatrace-managed/utils/cassandra-nodetool.sh status

You can also query the Cluster API to list the nodes and their state, with a Cluster API token that has the Service Provider API permission (Cluster API v1):

curl -s -H "Authorization: Api-Token {cluster-token}" \
  "https://{your-domain}/api/v1.0/onpremise/cluster" | python3 -m json.tool

Step 2 — Check the last backup

In the CMC, in the backup settings, check the date and status of the last backup. On the shared storage side:

ls -lh {nfs-mount-point}/
df -h {nfs-mount-point}

If the last backup failed, fix the cause before any update.

Step 3 — Define the maintenance window

Under Settings > Automatic update in the CMC, choose between automatic and manual installation, and define a window (for example Tuesday between 10 pm and 2 am). Align it with your change freeze calendar and document it in your ITSM tool.

Step 4 — Start the cluster update

When the new version is available, trigger the installation from Settings > Automatic update in the CMC, or through Cluster API v1:

curl -s -X POST -H "Authorization: Api-Token {cluster-token}" \
  "https://{your-domain}/api/v1.0/upgradeManagement/triggerUpgrade"

Then follow the progress under Deployment Status.

In offline mode, upload the package via Upload installation package. For a fully manual update, copy dynatrace-managed-{version}.sh to /opt/dynatrace-managed/installer/upgrade on each node, then run it as root with --upgrade, one node at a time, waiting for each to finish.

Step 5 — Validate after the update

• The version shown in the CMC matches the target version on every node.
• Environments are still receiving data (check a key host and service).
• ActiveGates are connected and no connection error events appear.

Step 6 — Update the ActiveGates

Once the cluster has settled, update the ActiveGates, either through automatic update from the environment interface or by reinstalling the package downloaded from your cluster. Start with a non-critical ActiveGate.

Step 7 — Roll out OneAgents in waves

In each environment, the OneAgent update settings let you choose a target version and a maintenance window, globally, per host group or per host. Recommended strategy:

1. Wave 1: the staging host group (--set-host-group=staging at installation).
2. Wave 2: non-critical production, a few days later.
3. Wave 3: critical production, after validation.

For a single host, check the installed version with oneagentctl:

sudo /opt/dynatrace/oneagent/agent/tools/oneagentctl --version
sudo /opt/dynatrace/oneagent/agent/tools/oneagentctl --get-host-group

To fetch the latest installer from your cluster (for hosts reinstalled through automation):

curl -o oneagent.sh -H "Authorization: Api-Token {token}" \
  "https://{your-domain}/e/{environment-id}/api/v1/deployment/installer/agent/unix/default/latest?arch=x86"
sudo /bin/sh oneagent.sh --set-host-group={group} --set-monitoring-mode=fullstack

Note that most OneAgent updates require a restart of application processes to activate the new instrumentation version: plan it with the application teams.

Step 8 — Kubernetes: Dynatrace Operator

On Kubernetes, first update the Operator using your usual method (Helm or manifests), then let it bring the OneAgents declared in the DynaKube into line (its apiUrl points to https://{your-domain}/e/{environment-id}/api). Then check:

kubectl -n dynatrace get dynakube
kubectl -n dynatrace get pods -o wide

Best practices

• A fixed cadence: one cluster update per release cycle, without skipping versions, beats a massive catch-up.
• A staging cluster: if your licence allows, a small pre-production Managed cluster that receives each version one to two weeks before production.
• Host groups designed for updates: name them by criticality and environment so you can target the waves.
• A versioned runbook: pre-checks, commands, validation criteria and rollback procedure documented and reviewed after each operation.
• Watch compatibility: a dashboard listing OneAgent versions by host group helps spot forgotten hosts.

Frequently asked questions

In what order should the components be updated?

The cluster first, ActiveGates next, OneAgents last: the cluster is what distributes the agent packages. Check the compatibility windows in the official documentation.

Can I skip cluster versions?

Sometimes: only an installed version divisible by 4 (1.300, 1.304…) lets you skip the next one, once the target is released; otherwise you must go through each version. Since 1.324, a CMC option enforces sequential updates. One update per cycle remains the simplest routine.

Is a new OneAgent version active straight away?

Not always: most OneAgent updates require a restart of application processes to activate the new instrumentation. Plan these restarts with the application teams.

Conclusion

Updating Dynatrace Managed carries no particular risk if you respect the cluster → ActiveGate → OneAgent order, check health, disk and backup before acting, and roll out agents in waves. The real gain comes from regularity: a short, repeated routine turns a dreaded operation into a non-event, and keeps your observability platform as reliable as the applications it monitors.

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/mises-a-jour-cluster-managed/.