• Home
  • Deploy
  • Set up Dynatrace on container platforms
  • Kubernetes
  • Get started with Kubernetes/OpenShift monitoring

Get started with Kubernetes/OpenShift monitoring

New Kubernetes documentation available

We've just released updated documentation for Kubernetes. Moving forward, all updates and new information will only be added to the new documentation.

This page describes how to set up monitoring via Dynatrace Operator version 0.8.0+ on Kubernetes (with kubectl) and OpenShift (with oc) using the following deployment options:

  • Classic full-stack
  • Cloud-native full-stack
  • Host monitoring
  • Automatic application-only
Existing users

  • If you already set up monitoring using an earlier version of Dynatrace Operator, we recommend that you upgrade to the latest Dynatrace Operator version.

  • If you already set up monitoring using OneAgent Operator, please see the instructions for migrating to Dynatrace Operator, as the OneAgent Operator procedure is deprecated.

    • For information about the Dynatrace Operator version changes, see Understand and configure the DynaKube custom resource.
Deprecated pages

Kubernetes:

  • Set up Kubernetes monitoring using Dynatrace Operator v.0.2.0
  • Set up Kubernetes monitoring using OneAgent Operator
  • Set up automatic application-only monitoring on Kubernetes using OneAgent Operator

OpenShift:

  • Set up Openshift monitoring using Dynatrace Operator v.0.2.0
  • Set up OpenShift monitoring using OneAgent Operator
  • Set up automatic application-only monitoring on OpenShift using OneAgent Operator

There are two ways to set up Dynatrace Operator to monitor your Kubernetes cluster:

  • Automated: The automated mode provides a simple setup with basic configuration using the Dynatrace web UI.
Instructions for automated mode

  1. In the Dynatrace menu, go to Kubernetes.

  2. Select Connect automatically via Dynatrace Operator.

  3. Enter the following details.

    • Name: Defines the display name of your Kubernetes cluster. Additionally, this name is used as a prefix for naming Dynatrace-specific resources inside the Kubernetes cluster, such as DynaKube (custom resource), ActiveGate (pod), and OneAgents (pods), and as a name for the secret holding your tokens.

    • recommended Group: Defines a group that is used by various Dynatrace settings, including network zone, ActiveGate group, and host group. If not set, defaults or empty values are used.

    • Dynatrace Operator token: Select Create token to generate the token and the necessary permissions automatically.

    • optional Data ingest token: For cloudNativeFullStack and applicationMonitoring deployments, if you want to enable metadata metric enrichment, select Create token.

  4. optional Select whether you want Dynatrace to check your SSL certificate.

    The SSL certificate is only verified for Dynatrace Operator API requests.

  5. For GKE, Anthos, CaaS, TGKI, and IKS, turn on Enable volume storage (required only for classicFullStack deployments).

  6. Under Kubernetes/OpenShift, select Download dynakube.yaml, and then copy the code block created by Dynatrace based on your input from previous steps and run it in your terminal. Be sure to execute the commands in the same directory where you downloaded the YAML, or adapt the commands to link to the location of the YAML.

    The downloaded YAML file is a basic version of the DynaKube custom resource definition. To adapt values to your specific needs, see our preconfigured DynaKube custom resource samples from GitHub. For more information about deployment options, see Deployment options on Kubernetes/OpenShift.

  7. To see the deployment status, select Show deployment status.

  • Manual: The manual mode allows complex configuration options.

    Instructions for manual mode are below.

Prerequisites

  • See Support lifecycle for Kubernetes/OpenShift for supported versions and minimum version requirements.
  • Pods must allow egress to your Dynatrace environment or to your Environment ActiveGate in order for metric routing to work properly.
  • For OpenShift (cloudNativeFullStack and applicationMonitoring with CSI driver deployments), you need to configure security context constraints (OpenShift).
  • For OpenShift Dedicated, you need the cluster-admin role.

By default, the OneAgent and ActiveGate images are pulled from the configured Dynatrace Cluster endpoint, unless differently specified. For details, see Parameters.

Tokens and permissions required

You have two options for configuring tokens and permissions:

  • recommended In Dynatrace, go to Kubernetes > Connect automatically via Dynatrace Operator and quickly generate tokens with the necessary permissions.

  • For greater control over the configuration options, follow the instructions below.

    1. Create a Dynatrace Operator token (former API token) and enable the following permissions.

      • Access problem and event feed, metrics, and topology (DataExport)
      • PaaS integration - Installer download (InstallerDownload)
      • Create ActiveGate tokens1 (activeGateTokenManagement.create)
      • Read entities2 (entities.read)
      • Read settings2 (settings.read)
      • Write settings2 (settings.write)

    2. optional For cloudNativeFullStack and applicationMonitoring deployments, if you want to enable metadata metric enrichment, create a data ingest token and enable the following permissions:

      • Ingest metrics (metrics.ingest)
      • Ingest logs (logs.ingest)
      • Ingest events (events.ingest)
    1

    Creates an authentication token for your ActiveGate to connect to the Dynatrace Cluster. The token is rotated by Dynatrace Operator every 29 days. When an authentication token is rotated, the affected ActiveGate is automatically deleted and redeployed.

    2

    All three scopes are needed if you want Dynatrace Operator to automatically handle the connection to ActiveGate via public API for Kubernetes monitoring.

Token scope usage
ScopeUsageMinimum Dynatrace Operator version
PaaS integration - Installer downloadManages OneAgent and ActiveGate lifecycle.All versions
Access problem and event feed, metrics, and topology (API v1)Notifies the Dynatrace Cluster of graceful shutdown.All versions
Read settings (API v2), Write settings (API v2)Manage the ActiveGate object for Kubernetes API monitoring.v0.4.0+
Read entities (API v2)Checks if the ActiveGate object exists for Kubernetes API monitoring.v0.4.0+
Ingest metrics (API v2)Enables metadata enrichment for metrics.v0.4.0+
Create ActiveGate token (API v2)Manages the ActiveGate authentication token lifecycle.v0.9.0+

Set up monitoring via Dynatrace Operator - manual mode

Create a dynatrace namespace (Kubernetes)/Add a dynatrace project (OpenShift)

Install Dynatrace Operator

Wait for Dynatrace Operator components to finish initialization

Create a secret holding your tokens

Download a preconfigured DynaKube custom resource sample

Review the parameters

Review the available configuration options

Apply the DynaKube custom resource

Verify the Dynatrace Operator image signature

Create a dynatrace namespace (Kubernetes)/Add a dynatrace project (OpenShift)

Depending on your platform, select one of the options below.

bash
kubectl create namespace dynatrace
bash
oc adm new-project --node-selector="" dynatrace

Install Dynatrace Operator

To install Dynatrace Operator, select one of the following, depending on your deployment type.

  • For classicFullStack, applicationMonitoring without CSI driver, and hostMonitoring when readonly is disabled, run the command below.

    bash
    kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
    bash
    oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml

  • For cloudNativeFullStack, applicationMonitoring with CSI driver, and hostMonitoring when readonly isn't disabled, run the commands below.

    bash
    kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes-csi.yaml
    bash
    oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml
oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift-csi.yaml
  • For TKGI where CSI driver is used

    For VMware Tanzu Kubernetes Grid Integrated Edition (formerly PKE), follow the steps below.

    1. Get kubernetes-csi.yaml from GitHub.
    2. Adjust the YAML file by replacing the /var/lib/kubelet/ path with /var/vcap/data/kubelet/ in all instances.
    3. Run the commands below.
    bash
    kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
kubectl apply -f kubernetes-csi.yaml
    1. Get openshift-csi.yaml from GitHub.
    2. Adjust the YAML file by replacing the /var/lib/kubelet/ path with /var/vcap/data/kubelet/ in all instances.
    3. Run the commands below.
    bash
    oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml
oc apply -f openshift-csi.yaml
  • For IKS where CSI driver is used

    For IBM Cloud Kubernetes Service (IKS), follow the steps below.

    1. Get kubernetes-csi.yaml from GitHub.
    2. Adjust the YAML file by replacing the /var/lib/kubelet/ path with /var/data/kubelet in all instances.
    3. Run the commands below.
    bash
    kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
kubectl apply -f kubernetes-csi.yaml
    1. Get openshift-csi.yaml from GitHub.
    2. Adjust the YAML file by replacing the /var/lib/kubelet/ path with /var/data/kubelet in all instances.
    3. Run the commands below.
    bash
    oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml
oc apply -f openshift-csi.yaml

Wait for Dynatrace Operator components to finish initialization

Run the following command to see when Dynatrace Operator components finish initialization.

bash
kubectl -n dynatrace wait pod --for=condition=ready --selector=app.kubernetes.io/name=dynatrace-operator,app.kubernetes.io/component=webhook --timeout=300s
bash
oc -n dynatrace wait pod --for=condition=ready --selector=app.kubernetes.io/name=dynatrace-operator,app.kubernetes.io/component=webhook --timeout=300s

Create a secret holding your tokens

To create a secret holding your tokens, select one of the following, depending on your deployment type.

  • For classicFullStack, create a secret named dynakube holding the API token obtained in Tokens and permissions required. Be sure to replace the placeholder (<...>) with your own value.

    bash
    kubectl -n dynatrace create secret generic dynakube --from-literal="apiToken=<API_TOKEN>"
    bash
    oc -n dynatrace create secret generic dynakube --from-literal="apiToken=<API_TOKEN>"

  • For cloudNativeFullStack and applicationMonitoring, create a secret named dynakube holding both the API token and the dataIngestToken, see Tokens and permissions required. Be sure to replace the placeholders (<...>) with your own values.

    bash
    kubectl -n dynatrace create secret generic dynakube --from-literal="apiToken=<API_TOKEN>" --from-literal="dataIngestToken=<DATA_INGEST_TOKEN>"
    bash
    oc -n dynatrace create secret generic dynakube --from-literal="apiToken=<API_TOKEN>" --from-literal="dataIngestToken=<DATA_INGEST_TOKEN>"

Download a preconfigured DynaKube custom resource sample

Download one of the preconfigured DynaKube custom resource samples from GitHub, according to your monitoring approach.

Review the parameters

Review the available parameters, and adapt the DynaKube custom resource according to your requirements.

Review the available configuration options optional

Review the available configuration options for this integration:

  • Configure build label propagation
  • Add a custom properties file
  • Add a custom certificate for ActiveGate
  • Configure proxy
  • Read-only file systems support
  • Configure monitoring for namespaces and pods
  • Import Kubernetes API certificates
  • Configure security context constraints (OpenShift)
  • Metadata metric enrichment
  • Enable AppArmor for enhanced security
  • High availability
  • Using priorityClass for critical Dynatrace components
  • Set namespace-based isolation levels for pods
  • Configure customPullSecret in DynaKube

Apply the DynaKube custom resource

Run the command below to apply the DynaKube custom resource, making sure to replace <your-DynaKube-CR> with your actual DynaKube custom resource file name. A validation webhook will provide helpful error messages if there's a problem.

bash
kubectl apply -f <your-DynaKube-CR>.yaml
bash
oc apply -f <your-DynaKube-CR>.yaml

Verify the Dynatrace Operator image signature and check the Software Bill of Materials (SBOM) optional

Dynatrace Operator version 0.9.0+

To verify the signature of a Dynatrace Operator image

  1. Install Cosign.

  2. Select one of the following options:

    bash
    cosign verify --key https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/cosign.pub dynatrace/dynatrace-operator:v0.13.0
    bash
    cosign verify --certificate-identity=https://github.com/Dynatrace/dynatrace-operator/.github/workflows/publish-images.yaml@refs/tags/v0.13.0 --certificate-oidc-issuer=https://token.actions.githubusercontent.com dynatrace/dynatrace-operator:v0.13.0

Dynatrace Operator version 0.12.0+

To check the Software Bill of Materials (SBOM) of a Dynatrace Operator image, you can use Cosign to verify the attestation and retrieve the signed SBOM.

  1. Install Cosign.

  2. Run the following command to get the signed SBOM:

    bash
    cosign verify-attestation \
--certificate-identity=https://github.com/Dynatrace/dynatrace-operator/.github/workflows/release.yaml@refs/tags/v0.13.0 \
--certificate-oidc-issuer=https://token.actions.githubusercontent.com \
--type cyclonedx docker.io/dynatrace/dynatrace-operator:v0.13.0 \
| jq -r .payload | base64 -d | jq -r .predicate > sbom.json

    This will create a sbom.json file in your local file system with the SBOM of the operator image.

Limitations

Dynatrace Operator doesn't support OpenShift version 3.11 or earlier.

Monitor large Kubernetes environments

Contact a Dynatrace product expert via live chat if you want to monitor environments that are larger than:

  • 1,000 Kubernetes clusters per Dynatrace environment.
  • 500 nodes per Kubernetes cluster.
  • 50,000 pods per Kubernetes cluster.

Update Dynatrace Operator

To update Dynatrace Operator, select one of the following, depending on your deployment type.

  • For classicFullStack, applicationMonitoring without CSI driver, and hostMonitoring when readonly is disabled, run the command below.

    bash
    kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
    bash
    oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml

  • For cloudNativeFullStack, applicationMonitoring with CSI driver, and hostMonitoring when readonly isn't disabled, run the commands below.

    bash
    kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
kubectl apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes-csi.yaml
    bash
    oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml
oc apply -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift-csi.yaml
Change in the default behavior of CSI-driver modes

Dynatrace Operator version 0.9.0+

Starting with Dynatrace Operator version 0.9.0+, there are some changes in the CSI driver mount failure recovery:

  • The single driver container is split in two:

    • A provisioner container, which handles download and unpacking of OneAgent binaries.
    • A server container, which handles mount and unmount requests of CSI volumes, even if the provisioner container runs out of memory.

  • In case of issues with the CSI driver (such as network issues), the injected application pods are no longer blocked; empty files are mounted instead, so that the pods can start (there's no monitoring, but pods are available).

  • The CSI driver defaults to 10 mount attempts (about 5 minutes). Each attempt occurs when the pod restarts. For information on the exponential back-off delay, see Container restart policy.

    You can configure the number of attempts in DynaKube:

    yaml
    apiVersion: dynatrace.com/v1beta1
kind: DynaKube
metadata:
  name: dynakube
  annotations:
    feature.dynatrace.com/max-csi-mount-attempts: "10"

Update OneAgent if automatic updates are disabled

By default, Dynatrace Operator handles OneAgent updates automatically. If you choose to disable automatic updates, and haven't set any standard OneAgent version in Dynatrace, you can manually update OneAgent by running the command below.

bash
kubectl -n dynatrace rollout restart daemonset/<DYNAKUBE>-oneagent
bash
oc -n dynatrace rollout restart daemonset/<DYNAKUBE>-oneagent

Updating tokens

If you need to update your tokens, follow the steps below.

Find current tokens

Delete your secret

Create new tokens

Create a new secret with updated tokens

Delete the old tokens

Find current tokens

Find and save your currently used tokens.

After generating new tokens, you'll need to delete the old ones.

bash
kubectl -n dynatrace get secrets <dynakube-name> -o yaml | yq '.data.apiToken' | base64 -d
bash
oc -n dynatrace get secrets <dynakube-name> -o yaml | yq '.data.apiToken' | base64 -d

Delete your secret

To delete the secret, run one of the commands below.

In Kubernetes, used tokens are stored in a secret named dynakube by default. If the DynaKube custom resource has a different name, or the tokens field in Dynakube is set, make sure that the new secret has the same name as defined there.

bash
kubectl -n dynatrace delete secret dynakube
bash
oc -n dynatrace delete secret dynakube

Create new tokens

For instructions on how to create the tokens, see Tokens and permissions required.

Create a new secret with updated tokens

To create a new secret with the updated tokens, run one of the commands below, making sure to replace the placeholders with the new tokens.

  • For apiToken: 
    bash
    kubectl -n dynatrace create secret generic dynakube --from-literal="apiToken=<API-TOKEN>"
  • For apiToken and dataIngestToken: 
    bash
    kubectl -n dynatrace create secret generic dynakube --from-literal="apiToken=<API-TOKEN>" --from-literal="dataIngestToken=<INGEST-TOKEN>"
  • For apiToken: 
    bash
    oc -n dynatrace create secret generic dynakube --from-literal="apiToken=<API-TOKEN>"
  • For apiToken and dataIngestToken: 
    bash
    oc -n dynatrace create secret generic dynakube --from-literal="apiToken=<API-TOKEN>" --from-literal="dataIngestToken=<INGEST-TOKEN>"

Dynatrace Operator picks up the updated secrets in approximately five minutes. Removing DynaKube and reapplying it forces an instant reconciliation.

Delete the old token

After the new tokens are in place, delete the old ones.

  1. In Dynatrace, go to Access tokens and look for the old token.
  2. Select Delete.

Uninstall Dynatrace Operator

Depending on your deployment type, select one of the following.

  • classicFullStack and applicationMonitoring without CSI driver
  • cloudNativeFullStack and applicationMonitoring with CSI driver

classicFullStack and applicationMonitoring without CSI driver

  1. Delete Dynatrace Operator.
bash
kubectl delete -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
bash
oc delete -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml
  1. Run uninstall.sh on every node of your Kubernetes cluster where OneAgent was installed. The default location is /opt/dynatrace/oneagent/agent/uninstall.sh.

cloudNativeFullStack and applicationMonitoring with CSI driver

  1. Remove DynaKube custom resources and clean up all remaining Dynatrace Operator–specific objects.
bash
kubectl delete dynakube --all -n dynatrace
bash
oc delete dynakube --all -n dynatrace
  1. Wait until Dynatrace Operator components have been deleted.
bash
kubectl -n dynatrace wait pod --for=condition=delete --selector=app.kubernetes.io/name=oneagent,app.kubernetes.io/managed-by=dynatrace-operator --timeout=300s
bash
oc -n dynatrace wait pod --for=condition=delete --selector=app.kubernetes.io/name=oneagent,app.kubernetes.io/managed-by=dynatrace-operator --timeout=300s

  1. Restart your monitored applications.

  2. Uninstall Dynatrace Operator and delete the Dynatrace namespace/project.

bash
kubectl delete -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes-csi.yaml
kubectl delete -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/kubernetes.yaml
kubectl delete namespace dynatrace
bash
oc delete -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift-csi.yaml
oc delete -f https://github.com/Dynatrace/dynatrace-operator/releases/download/v0.13.0/openshift.yaml
oc delete project dynatrace
  1. Delete the /var/lib/kubelet/plugins/csi.oneagent.dynatrace.com directory from all Kubernetes nodes.

Alternative deployments

Besides the main deployment of Dynatrace Operator on Kubernetes via kubectl and OpenShift via oc, you have the following alternatives, depending on your needs.

  • Set up Kubernetes/OpenShift monitoring with Helm
  • Set up application-only monitoring (automatic/pod runtime/container build-time)
  • Set up Kubernetes/OpenShift monitoring with DaemonSet
  • Set up OpenShift monitoring via OperatorHub

Other configuration options

  • Enable Kubernetes/OpenShift API monitoring
  • Deployment options on Kubernetes/OpenShift
  • DynaKube parameters for Dynatrace Operator
  • Configuration options for Dynatrace Operator on Kubernetes/OpenShift
  • Migrate from OneAgent Operator to Dynatrace Operator on Kubernetes/OpenShift using kubectl/oc
Related topics
  • Connect your Kubernetes/OpenShift clusters to Dynatrace

    Set up and configure a containerized ActiveGate on Kubernetes/OpenShift with Dynatrace Operator.

  • Kubernetes/OpenShift monitoring

    Monitor Kubernetes/OpenShift with Dynatrace.

  • Technology support

    Find technical details related to Dynatrace support for specific platforms and development frameworks.

  • Kubernetes cluster and workload monitoring