Enrich Kubernetes telemetry with primary Grail fields and tags

All enrichment options require metadataEnrichment to be enabled in your DynaKube:

spec:
  metadataEnrichment:
    enabled: true

By default, enrichment applies to all namespaces (except kube-*, openshift-*, and the Dynatrace Operator namespace—for details, see Configure monitoring for namespaces and pods). If you configure a namespaceSelector, only matching namespaces receive enrichment. Excluded namespaces won't have complete primary Grail fields or tags populated on their telemetry. For complete coverage, prefer omitting the selector or configuring it to match all monitored namespaces.

Dynatrace automatically populates k8s.cluster.name and k8s.namespace.name on all telemetry from Kubernetes workloads, with no configuration required. If filtering, routing, and access control at the cluster or namespace level cover your use case, no additional setup is needed.

If your namespaces, workloads, or pods already carry labels or annotations that represent the context you want, such as team ownership, environment, cost center, security boundary, use central configuration to promote them to primary Grail tags or fields. No changes to workload manifests are required.

Each central configuration rule selects a source, for example, a namespace label, a workload annotation, a pod label, or a static literal value, and a target, such as a primary field or a primary tag.

How the source value reaches telemetry depends on the rule type:

Configuration changes to central rules can take up to 15 minutes to take effect. You might need to restart affected pods. Rules created before you deploy your DynaKube are picked up immediately.

To set up central configuration

For a full reference of form fields and available targets, see Configure central enrichment rules.

Promote forwarded Kubernetes tags to primary tags in OpenPipeline

You need this step only if a central configuration rule forwards a label or annotation with the Kubernetes tag target. This applies if your environment runs a version earlier than the versions required for the Primary tag target, or if you want to combine Kubernetes tags with tags from other sources in a single rule.

If a rule maps a label or annotation directly to the Primary tag target, skip this step.

Forwarded Kubernetes tags arrive in OpenPipeline as, for example, k8s.namespace.label.<key>, k8s.workload.annotation.<key>, or k8s.pod.label.<key>, which are not primary tags. To make them primary_tags.* tags that you can use uniformly across Dynatrace, review your OpenPipeline primary Grail tag rules.

Define the target primary_tags.<key> once and list the source fields to read from, in order. The first source with a non-null value is used to set the target. You can also add the equivalent fields from other cloud providers to the same rule, so a single primary_tags.team definition works across Kubernetes, AWS, Azure, and Google Cloud.

For the full setup, see Set primary Grail tag rules in OpenPipeline.

If your Kubernetes resources don't carry suitable information in existing labels or annotations, add dedicated metadata.dynatrace.com/primary_tags.<key>:<value> annotations directly to your Kubernetes manifests to set primary Grail tags. The same convention also accepts the supported primary fields dt.security_context, dt.cost.costcenter, and dt.cost.product. Any other metadata.dynatrace.com/<key> annotation is ignored for enrichment on signals.

metadata:
  annotations:
    # Primary tags:
    metadata.dynatrace.com/primary_tags.team: payments
    metadata.dynatrace.com/primary_tags.environment: production

    # Supported primary fields:
    metadata.dynatrace.com/dt.security_context: confidential
    metadata.dynatrace.com/dt.cost.costcenter: it_services
    metadata.dynatrace.com/dt.cost.product: fin_app

You can place these annotations at three levels:

When the same key is set at multiple levels, the pod-level value wins over the workload-level value, and the workload-level value wins over the namespace-level value.

You can define additional resource attributes directly in your DynaKube. Dynatrace Operator propagates these attributes to all telemetry signals without requiring you to modify namespaces, workloads, or pods. This is useful when you want to attach a fixed tag to all signals from a cluster, such as a team identifier, at the DynaKube level.

Three DynaKube sections control which signals receive which attributes:

apiVersion: dynatrace.com/v1beta6
kind: DynaKube
metadata:
  name: dynakube
  namespace: dynatrace
spec:
  apiUrl: https://<environment-id>.live.dynatrace.com/api
  resourceAttributes:
    primary_tags.team: "alpha"
  oneAgent:
    cloudNativeFullStack:
      additionalResourceAttributes:
        aws.account.id: "000000000000"
        primary_tags.team: "charly"
      namespaceSelector:
        matchLabels:
          my.app.com/oneagent: "true"

  otlpExporterConfiguration:
    additionalResourceAttributes:
      aws.account.id: "000000000000"
      primary_tags.team: "charly"
    namespaceSelector:
      matchLabels:
        my.app.com/otel: "true"
    signals:
      metrics: {}
      traces: {}
      logs: {}

If none of these options apply, derive or assign primary tags at ingest with OpenPipeline and the processing stage. Use this as a fallback for environments where source-side or central enrichment isn't possible.