Injecting DDTrace via DataKit Operator¶

Usage Instructions¶

1. Download and install DataKit-Operator in the target Kubernetes cluster.

2. Add the following ConfigMap configuration to the Operator:

   {
       "server_listen": "0.0.0.0:9543", // Service listening address
       "log_level": "info", // Log level
   
       "admission_inject_v2": { // Injection config v2 (operator version >= v1.8.0)
           "ddtraces": [ // DDTrace configuration array
               {
                 // Fill in DDTrace injection config here...
               },
               {
                 // Can inject another DDTrace config...
               }
           ]                   
       },
   
       "admission_inject": { // Injection config v1
           "ddtrace": {
               // Fill in DDTrace injection config here...
               // For v1 config, operator only supports injecting one DDTrace config. v2 is recommended for flexibility.
           }
       },
   }
   

   DDTrace injection has the following configurable fields:

   Field	Type	Description	Required	Example Value
   envs	object	Environment variable map	Y4	See example below
   image	string	DDTrace image address	Y2	See example below
   label_selectors	array	Label selector array	Y1	["app=nginx", "tier=frontend"]
   language	string	Supported language type (optional java)	Y3	"java"
   namespace_selectors	array	Namespace selector, supports regex	Y1	["prod-*", "test"]
   resources	object	Resource limit configuration	N	See example below
   enabled_namespaces	object	Select target Kubernetes namespace and set development language	Y	Deprecated in 1.7.0 admission_inject_v2
   enabled_labelselectors	object	Select target using Kubernetes label	Y	Deprecated in 1.7.0 admission_inject_v2

check_annotation Configuration Item Explanation¶

check_annotation is an important configuration field used to control how DataKit Operator handles version annotations on Pods (e.g., admission.datakit/java-lib.version). The values and behaviors of this field are as follows:

Important Logic Explanation¶

1. Function-specific annotations always effective:
2. admission.datakit/ddtrace.enabled is not affected by check_annotation configuration
3. Regardless of whether check_annotation is true or false, admission.datakit/ddtrace.enabled will be checked

4. If admission.datakit/ddtrace.enabled: "false", injection will be directly rejected

5. Version annotations controlled by check_annotation:

6. admission.datakit/java-lib.version is affected by check_annotation configuration
7. When check_annotation: true, version annotations must exist to inject

8. When check_annotation: false, version annotation checks are ignored

9. Global annotations always effective:

10. admission.datakit/enabled is not affected by check_annotation configuration
11. If admission.datakit/enabled: "false", all injections will be completely rejected (highest priority)

Supported DDTrace-related Annotations:

When check_annotation: true¶

The following conditions must be simultaneously met to perform injection:

1. Configuration matches: Pod must match namespace_selectors and label_selectors rules
2. Function annotation allows: admission.datakit/ddtrace.enabled is not "false" (if exists)
3. Version annotation exists: Version annotations must exist on Pod (e.g., admission.datakit/java-lib.version)

When check_annotation: false¶

The following conditions must be met to perform injection:

1. Configuration matches: Pod must match namespace_selectors and label_selectors rules
2. Function annotation allows: admission.datakit/ddtrace.enabled is not "false" (if exists)
3. Ignore version annotations: Injection occurs even without version annotations

Use Case Examples¶

1. Strict version control scenario (check_annotation: true):

{
    "namespace_selectors": ["prod"],
    "label_selectors": ["app=backend"],
    "check_annotation": true,
    "image": "internal-registry/dd-lib-java:v1.55.10-ext",
    "language": "java"
}

Injection conditions: - Pod is in prod namespace with app=backend label - Pod does not have admission.datakit/ddtrace.enabled: "false" (if exists) - Pod must have admission.datakit/java-lib.version annotation

1. Batch injection scenario (check_annotation: false):

{
    "namespace_selectors": ["staging"],
    "label_selectors": ["env=test"],
    "check_annotation": false,
    "image": "internal-registry/dd-lib-java:latest",
    "language": "java"
}

Injection conditions: - Pod is in staging namespace with env=test label - Pod does not have admission.datakit/ddtrace.enabled: "false" (if exists) - Ignore admission.datakit/java-lib.version annotation check

1. Selective rejection scenario:

{
    "namespace_selectors": ["prod"],
    "label_selectors": ["app=java-app"],
    "check_annotation": false,
    "image": "internal-registry/dd-lib-java:latest",
    "language": "java"
}

Injection logic: - All matching Pods will be injected - If a Pod has admission.datakit/ddtrace.enabled: "false", that Pod will be excluded - Version annotation admission.datakit/java-lib.version: "1.15.0" can be used to override image version, but won't affect injection decision

Here is an example:

```json
{
    "namespace_selectors": [],
    "label_selectors": [],
    "image": "pubrepo.guance.com/datakit-operator/dd-lib-java-init:v1.55.10-ext",
    "language": "java",
    "envs": {
         "DD_AGENT_HOST":           "datakit-service.datakit.svc.cluster.local",
         "DD_TRACE_AGENT_PORT":     "9529",
         "DD_JMXFETCH_STATSD_HOST": "datakit-service.datakit.svc.cluster.local",
         "DD_JMXFETCH_STATSD_PORT": "8125",
         "DD_SERVICE":              "{fieldRef:metadata.labels['service']}",
         "POD_NAME":                "{fieldRef:metadata.name}",
         "POD_NAMESPACE":           "{fieldRef:metadata.namespace}",
         "NODE_NAME":               "{fieldRef:spec.nodeName}",
         "DD_TAGS":                 "pod_name:$(POD_NAME),pod_namespace:$(POD_NAMESPACE),host:$(NODE_NAME)"
     },
    "resources": {
        "requests": {
            "cpu":    "100m",
            "memory": "64Mi"
        },
        "limits": {
            "cpu":    "500m",
            "memory": "512Mi"
        }
    }
}
```

Handling Special Deployments¶

The Operator configuration above is for DDTrace injection across the entire cluster. Sometimes this one-size-fits-all approach is not suitable for certain specific Deployments. Therefore, we can make some Annotation markings for these Deployments individually:

The Operator can recognize the following two Annotations:

• admission.datakit/ddtrace.enabled: Marks whether to enable injection in a single Deployment standard. Fill in "true" to enable injection, "false" to block injection. If blocked, the Operator will ignore injecting this Deployment.
• admission.datakit/java-lib.version: Specifies a specific DDTrace version.

Annotation Usage Instructions: For how check_annotation configuration affects version annotation behavior, please refer to Annotation Configuration Injection and check_annotation Configuration Item Explanation.

Annotation Example¶

Mark whether to inject in Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
  labels:
    app: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        admission.datakit/ddtrace.enabled: "true"
    spec:
      containers:
      - name: my-app
        image: my-app:1.2.3
        ports:
        - containerPort: 80

Inject specific version of dd-java-lib into Deployment ⁵:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
  labels:
    app: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        admission.datakit/java-lib.version: "v1.55.10-ext"
    spec:
      containers:
      - name: my-app
        image: my-app:1.2.3
        ports:
        - containerPort: 80

Create resources using the yaml file:

$ kubectl apply -f my-app.yaml
...

Verify as follows:

$ kubectl get pod

NAME                                   READY   STATUS    RESTARTS      AGE
my-app-deployment-7bd8dd85f-fzmt2       1/1     Running   0             4s

$ kubectl get pod my-app-deployment-7bd8dd85f-fzmt2 -o=jsonpath={.spec.initContainers\[\*\].name}

datakit-lib-init