DataKit Operator¶

DataKit Operator 是 DataKit 在 Kubernetes 编排的联动项目，旨在协助 DataKit 更方便的部署，以及其他诸如验证、注入的功能。

概述¶

DataKit Operator 通过 Kubernetes Admission Controller 机制，为 Kubernetes 集群提供自动化注入功能，帮助用户更轻松地集成观测能力。主要功能包括：

• DDTrace 注入：自动为 Java 应用注入 APM 追踪代理
• 日志采集：通过 logfwd Sidecar 自动采集容器日志
• 性能分析：注入 Flameshot 或 Profiler 组件进行应用性能监控
• 配置管理：支持全局配置和声明式配置两种注入方式

核心优势：

• 自动化部署：无需手动修改应用 YAML，减少配置错误
• 批量管理：通过命名空间和标签选择器实现批量注入
• 灵活配置：支持 JSON 配置和 Annotation 精细控制
• 版本兼容：保持向后兼容，支持平滑升级

先决条件¶

• 推荐 Kubernetes v1.24.1 及以上版本，且能够访问互联网（下载 yaml 文件并拉取对应镜像）
• 确保启用 MutatingAdmissionWebhook 和 ValidatingAdmissionWebhook 控制器
• 确保启用了 admissionregistration.k8s.io/v1 API

安装¶

$ kubectl create namespace datakit
$ wget https://static.guance.com/datakit-operator/datakit-operator.yaml
$ kubectl apply -f datakit-operator.yaml
$ kubectl get pod -n datakit

NAME                               READY   STATUS    RESTARTS   AGE
datakit-operator-f948897fb-5w5nm   1/1     Running   0          15s

$ helm install datakit-operator datakit-operator \
    --repo https://pubrepo.guance.com/chartrepo/datakit-operator \
    -n datakit --create-namespace

$ helm -n datakit list

$ helm -n datakit get values datakit-operator -a -o yaml > values.yaml
$ helm upgrade datakit-operator datakit-operator \
    --repo https://pubrepo.guance.com/chartrepo/datakit-operator \
    -n datakit \
    -f values.yaml

$ helm uninstall datakit-operator -n datakit

配置说明¶

DataKit Operator 配置是 JSON 格式，在 Kubernetes 中单独以 ConfigMap 存放，以环境变量方式加载到容器中。

{
    "server_listen": "0.0.0.0:9543", // operator 自身服务监听地址
    "log_level": "info",             // operator 自身日志级别
    "admission_inject_v2": {         // 注入配置 v2
        "ddtraces": [...],           // DDTrace 配置数组
        "logfwds": [...],            // 日志转发配置数组
        "flameshots": [...]          // 性能分析配置数组
    },
    "admission_mutate": {            // 配置变更
        "loggings": [...]            // 日志配置变更
    }
}

{
    "server_listen": "0.0.0.0:9543",
    "log_level":     "info",
    "admission_inject": {
        "ddtrace": {...},
        "profiler": {...},
        "logfwd": {...}
    },
    "admission_mutate": {
        "loggings": [...]
    }
}

注入方式¶

DataKit Operator 支持两种资源输入方式，分别是

1. selector 配置注入（指令式）

   通过修改 DataKit-Operator config，指定目标 Pod 的 Namespace 和 Selector，如果发现 Pod 符合条件，就执行注入。

   优点：不需要在目标 Pod 添加 Annotation（但是需要重启目标 Pod）

   缺点：范围不够精确，可能存在无效注入

2. Annotation 配置注入（声明式）

   在目标 Pod 添加 Annotation 开启自身的注入。

   优点：可以通过 Annotation 精确控制是否拒绝注入

   缺点：不能单独通过 Annotation 触发注入，仍需配置匹配规则，即在目标 Pod annotation 上开启注入外，还需要在 Operator 配置其它字段。

Selector 配置注入¶

通过配置 namespace_selectors 和 label_selectors 可以实现批量注入。

在 admission_inject_v2 配置中，namespace_selectors 和 label_selectors 直接在数组项中配置，以 DDTrace 注入为例：

{
    "admission_inject_v2": {
        "ddtraces": [
            {
                "namespace_selectors": ["testns"],
                "label_selectors":     ["app=log-output"],
                ...
            }
        ]
    }
}

• namespace_selectors：命名空间选择器数组，支持正则表达式匹配。如需精确匹配，请使用 ^ 和 $ 将模式包围，例如 ^testns$
• label_selectors：标签选择器数组，使用 Kubernetes Label Selector 语法

如果同时配置了这两个 selector，则目标 Pod 必须同时满足这两个条件。关于 label selector 的编写规范，可参考此官方文档。

Annotation 配置注入¶

在 Deployment 添加指定 Annotation 可以控制是否允许注入。注意 Annotation 要添加在 template 中。

支持的 Annotation 如下：

示例：

    annotations:
    admission.datakit/ddtrace.enabled: "true"
    admission.datakit/logfwd.enabled: "true"

注入方式总结

• 全局配置：适合批量场景，通过 Operator 配置控制注入范围
• Annotation 配置：适合精细控制，通过 Pod 注解决定是否注入
• 优先级：Annotation 配置优先于全局配置，可用于拒绝注入
• 兼容性：不同版本支持的功能略有差异，请参考具体版本说明

支持的注入功能列表¶

Downward API¶

在 DataKit Operator v1.4.2 及以后版本，envs 支持 Kubernetes Downward API 的 环境变量取值字段。现支持以下几种：

举个例子，现有一个 Pod 名称是 nginx-123，namespace 是 middleware，要给它注入环境变量 POD_NAME 和 POD_NAMESPACE，参考以下：

{
    "admission_inject": {
        "ddtrace": {
            "envs": {
                "POD_NAME":      "{fieldRef:metadata.name}",
                "POD_NAMESPACE": "{fieldRef:metadata.namespace}"
            }
        }
    }
}

最终在该 Pod 可以看到：

$ env | grep POD
POD_NAME=nginx-123
POD_NAMESPACE=middleware

FAQ¶

如何禁用特定 Pod 的注入？¶

给该 Pod 添加 Annotation "admission.datakit/enabled": "false"，将不再为它执行任何操作，此优先级最高。

工作原理是什么？¶

DataKit-Operator 使用 Kubernetes Admission Controller 功能进行资源注入，详细机制请查看官方文档

在 AWS EKS 环境需要注意什么？¶

在 AWS EKS 环境部署，可能导致 DataKit-Operator 不生效，需要在安全组开启 9543 端口。

故障排查指南¶