DataKit Operator 注入 DDTrace¶

使用说明¶

1. 在目标 Kubernetes 集群，下载和安装 DataKit-Operator

2. 在 Operator 中增加如下 ConfigMap 配置

   {
       "server_listen": "0.0.0.0:9543", // 服务监听地址
       "log_level": "info", // 日志级别
   
       "admission_inject_v2": { // 注入配置 v2(operator version >= v1.8.0)
           "ddtraces": [ // DDTrace 配置数组
               {
                 // 此处填写 DDTrace 注入配置。..
               },
               {
                 // 可再注入另一个 DDTrace 配置。..
               }
           ]                   
       },
   
       "admission_inject": { // 注入配置 v1
           "ddtrace": {
               // 此处填写 DDTrace 注入配置。..
               // 对 v1 版本的配置，operator 只支持注入一份 DDTrace 配置，建议使用 v2 更灵活一些
           }
       },
   }
   

   DDTrace 注入有如下可配置字段：

   字段	类型	描述	是否必填	示例值
   envs	object	环境变量映射	Y4	见下方示例
   image	string	DDTrace 镜像地址	Y2	见下方示例
   label_selectors	array	标签选择器数组	Y1	["app=nginx", "tier=frontend"]
   language	string	支持的语言类型（可选 java/python/php/nodejs）	Y3	"nodejs"
   namespace_selectors	array	命名空间选择器，支持正则	Y1	["prod-*", "test"]
   resources	object	资源限制配置	N	见下方示例
   enabled_namespaces	object	选择要注入的 Kubernetes namespace 并设定对应的开发语言	Y	1.7.0 中 admission_inject_v2 已弃用
   enabled_labelselectors	object	通过 Kubernetes label 选择要注入的目标	Y	1.7.0 中 admission_inject_v2 已弃用

DDTrace Lib 注入方式和镜像选择¶

DataKit Operator 注入 DDTrace 时，会添加名为 datakit-lib-init 的 initContainer，将 DDTrace Lib 拷贝到共享卷 /datadog-lib，再把该目录挂载到业务容器。镜像版本需要按业务容器内的语言运行时版本选择，而不是按 initContainer 的运行时选择。

镜像仓库按品牌区分。本文示例统一使用 pubrepo.guance.com/datakit-operator，发布到不同品牌站点时会替换为对应仓库地址。

Node.js 注入¶

Node.js 注入会在业务容器中设置或追加 NODE_OPTIONS：

--require=/datadog-lib/node_modules/dd-trace/init

如果业务容器中已经存在 NODE_OPTIONS，Operator 会在原值后追加上述参数。Node.js 镜像必须和业务容器中的 Node.js 主版本匹配。

Node.js DDTrace 配置示例：

{
    "namespace_selectors": ["default"],
    "label_selectors": [],
    "check_annotation": false,
    "image": "pubrepo.guance.com/datakit-operator/dd-lib-js-init:5.102.0",
    "language": "nodejs",
    "envs": {
        "DD_AGENT_HOST": "datakit-service.datakit.svc.cluster.local",
        "DD_TRACE_AGENT_PORT": "9529",
        "DD_SERVICE": "{fieldRef:metadata.labels['app']}",
        "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)"
    }
}

Python 注入¶

Python 注入会在业务容器中设置或追加 PYTHONPATH=/datadog-lib/，让 Python 进程从 /datadog-lib 加载 DDTrace 相关库。Python 的 DDTrace 包含 CPython ABI 相关 wheel，镜像版本需要和业务容器 Python 小版本匹配；版本不匹配时，可能出现 ModuleNotFoundError、native extension 加载失败或启动失败。

Python DDTrace 配置示例：

{
    "namespace_selectors": ["default"],
    "label_selectors": [],
    "check_annotation": false,
    "image": "pubrepo.guance.com/datakit-operator/dd-lib-python-init:v4.8.3",
    "language": "python",
    "envs": {
        "DD_AGENT_HOST": "datakit-service.datakit.svc.cluster.local",
        "DD_TRACE_AGENT_PORT": "9529",
        "DD_SERVICE": "{fieldRef:metadata.labels['app']}",
        "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)"
    }
}

版本选择依据来自 DDTrace 上游包的运行时要求：Node.js 以 npm dd-trace 的 engines.node 为准，Python 以 PyPI ddtrace 的 Requires-Python 和 wheel 支持为准。

check_annotation 配置项说明¶

check_annotation 是一个重要的配置字段，用于控制 DataKit Operator 如何处理 Pod 上的版本注解（如 admission.datakit/java-lib.version、admission.datakit/python-lib.version、admission.datakit/nodejs-lib.version）。该字段的取值和行为如下：

重要逻辑说明¶

1. 功能特定注解始终有效：
2. admission.datakit/ddtrace.enabled 不受 check_annotation 配置影响
3. 无论 check_annotation 是 true 还是 false，都会检测 admission.datakit/ddtrace.enabled

4. 如果 admission.datakit/ddtrace.enabled: "false"，将直接拒绝注入

5. 版本注解受 check_annotation 控制：

6. admission.datakit/<language>-lib.version 受 check_annotation 配置影响
7. 当 check_annotation: true 时，需要版本注解存在才会注入

8. 当 check_annotation: false 时，忽略版本注解检查

9. 全局注解始终有效：

10. admission.datakit/enabled 不受 check_annotation 配置影响
11. 如果 admission.datakit/enabled: "false"，将完全拒绝任何注入（最高优先级）

支持的 DDTrace 相关 Annotation：

当 check_annotation: true 时¶

需要同时满足以下条件才会执行注入：

1. 配置匹配：Pod 必须匹配 namespace_selectors 和 label_selectors 规则
2. 功能注解允许：admission.datakit/ddtrace.enabled 不为 "false"（如果存在）
3. 版本注解存在：Pod 上必须存在版本注解（如 admission.datakit/java-lib.version、admission.datakit/python-lib.version 或 admission.datakit/nodejs-lib.version）

当 check_annotation: false 时¶

需要满足以下条件才会执行注入：

1. 配置匹配：Pod 必须匹配 namespace_selectors 和 label_selectors 规则
2. 功能注解允许：admission.datakit/ddtrace.enabled 不为 "false"（如果存在）
3. 忽略版本注解：即使没有版本注解也会注入

使用场景示例¶

1. 严格版本控制的场景（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"
}

注入条件： - Pod 在 prod 命名空间且带有 app=backend 标签 - Pod 没有 admission.datakit/ddtrace.enabled: "false"（如果存在） - Pod 必须有 admission.datakit/java-lib.version 注解

1. 批量注入的场景（check_annotation: false）：

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

注入条件： - Pod 在 staging 命名空间且带有 env=test 标签 - Pod 没有 admission.datakit/ddtrace.enabled: "false"（如果存在） - 忽略 admission.datakit/java-lib.version 注解检查

1. 选择性拒绝的场景：

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

注入逻辑： - 所有匹配的 Pod 都会被注入 - 如果某个 Pod 有 admission.datakit/ddtrace.enabled: "false"，该 Pod 将被排除 - 版本注解 admission.datakit/java-lib.version: "1.15.0" 可用于覆盖镜像版本，但不会影响是否注入的决策

如下是一个示例：

```json
{
    "namespace_selectors": [],
    "check_annotation": false,
    "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"
        }
    }
}
```

特殊 Deployment 的处理¶

上面 Operator 的配置是针对整个集群中的 DDTrace 注入配置，某些时候这种一刀切的方式不适合特定的某些 Deployment，为此我们可以单独为这些 Deployment 做一些 Annotation 标记。

Operator 能识别如下 Annotation：

• admission.datakit/ddtrace.enabled：在单个 Deployment 标准自己是否开启注入，填写 "true" 即开启注入，"false" 则屏蔽注入，屏蔽后，Operator 会忽略注入这个 Deployment
• admission.datakit/java-lib.version：指定特定的 DDTrace Java Agent 版本
• admission.datakit/python-lib.version：指定特定的 DDTrace Python Lib 版本
• admission.datakit/nodejs-lib.version：指定特定的 DDTrace Node.js Lib 版本

注解使用说明：关于 check_annotation 配置如何影响版本注解的行为，请参考 Annotation 配置注入 和 check_annotation 配置项说明。

Annotation 示例¶

给 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

给 Deployment 注入 dd-java-lib 特定版本号 ⁵：

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

使用 yaml 文件创建资源：

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

验证如下：

$ 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