Deploy OneAgent Operator on Kubernetes (deprecated)

Starting with Dynatrace Cluster version 1.215, you can deploy full-stack OneAgents and containerized ActiveGates using Dynatrace Operator. For migration instructions, see Migrate to Dynatrace Operator.

OneAgent Operator version 0.8.2

We recommend installing OneAgent Operator on Kubernetes with kubectl. If you prefer Helm, you can use the OneAgent Helm chart as a basic alternative.
For more information on all deployment options, see Kubernetes deployment strategies.


Find out below how to install and configure OneAgent.

  • Generate an API token and a PaaS token in your Dynatrace environment.
    Note: Make sure you have the Access problem and event feed, metrics, and topology setting enabled for the API token.
  • Pods must allow egress to your Dynatrace environment or to your Environment ActiveGate in order for metric routing to work properly.
  • See Support lifecycle for supported Kubernetes versions.
  1. Create the necessary objects for OneAgent Operator.

    OneAgent Operator acts on its separate namespace dynatrace. It holds the operator deployment and all dependent objects like permissions, custom resources and the corresponding DaemonSet. You can also observe the logs of OneAgent Operator.

    kubectl create namespace dynatrace
    kubectl apply -f
    kubectl -n dynatrace logs -f deployment/dynatrace-oneagent-operator
  2. Create the secret holding API and PaaS tokens for authentication to the Dynatrace Cluster.

    The name of the secret is important in a later step when you configure the custom resource (.spec.tokens). In the following code-snippet the name is oneagent. Be sure to replace API_TOKEN and PAAS_TOKEN with the values explained in the prerequisites.

    kubectl -n dynatrace create secret generic oneagent --from-literal="apiToken=API_TOKEN" --from-literal="paasToken=PAAS_TOKEN"
  3. Save custom resource.

    The rollout of Dynatrace OneAgent is governed by a custom resource of type OneAgent. Retrieve the cr.yaml file from the GitHub repository.

    curl -o cr.yaml
  4. Adapt the values of the custom resource as indicated below.

    If you want to revert an argument, you need to set it to empty instead of removing it from the custom resource.

      - "--set-proxy="
    Configuration for Anthos, SUSE CaaS, GKE, IKS, and TKGI

    For Anthos, SUSE CaaS, Google Kubernetes Engine, and VMware Tanzu Kubernetes Grid Integrated Edition (formerly PKE), you must add the following additional parameters to the env section in the cr.yaml file:

  5. Create the custom resource.

    kubectl apply -f cr.yaml
  6. optional Configure proxy.

    • You can configure optional parameters like proxy settings in the cr.yaml file in order to
      • download the OneAgent installer
      • ensure the communication between the OneAgent and your Dynatrace environment
      • ensure the communication between the Dynatrace OneAgent Operator and the Dynatrace API.

    There are two ways to provide the proxy, depending on whether or not your proxy uses credentials.

  7. optional Configure network zones.

    You can configure network zones by setting the following argument:

      - --set-network-zone=<>

    See network zones for more information.

Note: After deployment, you need to restart your pods so OneAgent can inject into them.

Cluster-wide permissions

The following table shows the permissions needed for OneAgent Operator.

Resources accessed APIs used Resource names
Nodes Get/List/Watch -
Namespaces Get/List/Watch -
Secrets Create -
Secrets Get/Update/Delete dynatrace-oneagent-config, dynatrace-oneagent-pull-secret


See Docker limitations for details.


Find out how to troubleshoot issues that you may encounter when deploying OneAgent on Kubernetes.

Deploy an ActiveGate and connect your Kubernetes API to Dynatrace

Now that you have OneAgent running on your Kubernetes nodes, you're able to monitor those nodes, and the applications running in Kubernetes. The next step is to deploy an ActiveGate and connect your Kubernetes API to Dynatrace in order to get native Kubernetes metrics, like request limits, and differences in pods requested vs. running pods.
For further instructions see Deploy ActiveGate in Kubernetes as a StatefulSet.

Update OneAgent Operator with kubectl

OneAgent Operator (for Kubernetes version 1.9+) automatically takes care of the lifecycle of the deployed OneAgents, so you don't need to update OneAgent pods yourself.

Review the release notes of the Operator for any breaking changes on the custom resource.

If the custom resource of the new version is compatible with the already deployed version, you can simply set the OneAgent Operator image to the new tagged version. Be sure to replace vX.Y.Z with the new version in the following command:

kubectl -n dynatrace set image deployment \
dynatrace-oneagent-operator *\

Note: The image version of the OneAgent Operator is independent from the OneAgent version. To check the available versions for the Operator, see the OneAgent Operator releases.

To update OneAgent Operator, run the following command:

kubectl apply -f

Update OneAgent Operator with Helm

Update your Helm repositories.

helm repo update

Another method of updating the Dynatrace OneAgent Helm repository is adding it again, which overwrites the older version.

Update OneAgent to the latest version.

Don't omit the --reuse-values flag in the command in order to keep your configuration.

helm upgrade dynatrace-oneagent-operator dynatrace/\
dynatrace-oneagent-operator -n dynatrace --reuse-values

Uninstall OneAgent Operator

To uninstall OneAgent Operator from Kubernetes version 1.9+

Remove OneAgent custom resources and clean up all remaining OneAgent Operator–specific objects.

kubectl delete -n dynatrace oneagent --all
kubectl delete -f

optional After deleting OneAgent Operator, the OneAgent binary remains on the node in an inactive state. To uninstall it completely, run the script and delete logs and configuration files.
See Linux related information.