DataKit Operator 注入 logfwd¶

Operator 注入 logfwd 采集主要采集 Pod 内部日志（日志没有保留在容器的 stdout），其实现原理是在 Pod 中注入一个 Sidecar 容器，该 Sidecar 容器通过直接采集容器内指定命令的日志，将其发送给 DataKit。

配合特定的 CRD 配置，logfwd 方式能动态调整目标 Pod 的采集设置，而不需要重启目标 Pod。

sequenceDiagram
autonumber

box User pod
participant container as 业务容器
participant logfwd as logfwd Sidecar
end

participant opr as DataKit Operator
participant crd as ClusterLoggingConfig

box DataKit
participant logfwds as logfwd Server
end

opr ->> logfwd: 注入 logfwd
opr ->> crd: Watch CRD 变更
opr ->> opr: 有则缓存下来
logfwd ->> opr: 定期轮询 CRD 是否变更（1min）

alt CRD 有变更
logfwd ->> logfwd: 更新采集配置
end

logfwd ->> container: 采集日志
logfwd ->> logfwds: 采集日志并上报

前置条件¶

1. DataKit 开启 logfwdserver 采集器，监听端口默认是 9533
2. DataKit service 需要开放 9533 端口，使得其它 Pod 能访问 datakit-service.datakit.svc:9533

使用说明¶

Operator <= v1.6.0 以前的 Operator，其 logfwd 注入使用参见这里。

采用 ClusterLoggingConfig CRD 集中管理日志采集配置： Version-1.7.0

• 集中管理采集配置：支持监听 Kubernetes ClusterLoggingConfig CRD，并暴露匹配结果供 logfwd sidecar 轮询获取（sidecar 默认每 60 秒向 Operator 发起 HTTP 请求，logfwd 需 Version-1.86.0）
• 热更新 & 精细匹配：CRD selector（Namespace/Pod/Label/Container）随改随生效，无需重建 Workload
• 简化配置：日志采集配置完全通过 CRD 管理，不再支持通过 Annotation 覆盖配置

若尚未了解 ClusterLoggingConfig 的定义及编写方式，请先阅读容器日志采集 CRD 配置文档。

操作流程：

1. 注册 ClusterLoggingConfig CRD（如 DataKit 文档中所述）
2. 升级/安装 DataKit Operator v1.7.0，并添加 CRD 的 RBAC 读权限
3. 在 DataKit Operator 配置中设置 logfwds 数组，配置 namespace_selectors/label_selectors 匹配规则和 log_configs 字段
4. （可选）在目标 Pod 添加 Annotation admission.datakit/logfwd.enabled: "true" 允许注入（如果设置为 "false" 则会拒绝注入）
5. 创建 ClusterLoggingConfig 资源，logfwd sidecar 将定期（默认 60 秒）拉取采集配置

安装最新的 datakit-operator.yaml 即可带上必要权限，或参考下列最小示例：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: datakit-operator
rules:
- apiGroups: ["logging.datakits.io"]
  resources: ["clusterloggingconfigs"]
  verbs: ["get", "list", "watch"]

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: datakit-operator
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: datakit-operator
subjects:
- kind: ServiceAccount
  name: datakit-operator
  namespace: datakit

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: datakit-operator
  namespace: datakit

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: datakit-operator
  namespace: datakit
  labels:
    app: datakit-operator
spec:
  replicas: 1  # Do not change the ReplicaSet number!
  selector:
     matchLabels:
       app: datakit-operator
  template:
    metadata:
      labels:
        app: datakit-operator
    spec:
      serviceAccountName: datakit-operator
      containers:
      - name: operator
        # other..

CRD 配置¶

ClusterLoggingConfig 示例：

apiVersion: logging.datakits.io/v1alpha1
kind: ClusterLoggingConfig
metadata:
  name: nginx-logs
spec:
  selector:
    namespaceRegex: "^(middleware)$"
    podLabelSelector: "app=logging"
  podTargetLabels:
    - app
    - env
  configs: # 以下配置和 ConfigMap 中的 log_configs 一一对应
    - type: file
      source: nginx-access
      service: nginx
      path: /var/log/nginx/access.log
      pipeline: nginx-access.p
      storage_index: app-logs
      multiline_match: "^\\d{4}-\\d{2}-\\d{2}"
      tags:
        team: web

应用上述资源后，DataKit Operator 会：

1. 监听 Deployment 创建事件并注入 datakit-logfwd Sidecar 容器
2. 根据 ClusterLoggingConfig 选择器匹配 Pod，持续维护匹配结果，供 Sidecar 在轮询时读取
3. Sidecar 启动后通过 LOGFWD_DATAKIT_OPERATOR_ENDPOINT 与 Operator 交互，每 60 秒拉取一次 CRD 配置，并将任务转发至 DataKit logfwdserver

日志采集配置¶

Operator 注入 logfwd，需在 Operator 的 ConfigMap 中增加如下结构的配置：

{
    "admission_inject_v2": {         // 注入配置 v2
        "logfwds": [
            // 此处支持多组 logfwd 配置
            { ... }, // 单个 logfwd 配置
            { ... }, // 另一个 logfwd 配置
        ],        
    }
}

其中，单个 logfwd 支持的配置字段如下：

环境变量配置¶

logfwd 注入新增若干环境变量与镜像版本要求，可在 datakit-operator-config ConfigMap 中配置：

"logfwds": [
    {
        "image": "pubrepo.guance.com/datakit/logfwd:1.89.0",
        "envs": {
            "LOGFWD_DATAKIT_HOST":              "{fieldRef:status.hostIP}",
            "LOGFWD_DATAKIT_PORT":              "9533",
            "LOGFWD_DATAKIT_OPERATOR_ENDPOINT": "datakit-operator.datakit.svc:443",
            "LOGFWD_GLOBAL_SERVICE":            "{fieldRef:metadata.labels['app']}",
            "LOGFWD_POD_NAME":                  "{fieldRef:metadata.name}",
            "LOGFWD_POD_NAMESPACE":             "{fieldRef:metadata.namespace}",
            "LOGFWD_POD_IP":                    "{fieldRef:status.podIP}"
        },
        "log_configs": "",
        "log_volume_paths": []
    }
]

其中 envs 有如下可选：

日志设置¶

log_configs 用于调试或覆盖 CRD 内容。如果 log_configs 为空，logfwd 注入将被跳过。结构示例：

[
  {
    "type": "file",
    "disable": false,
    "source": "nginx-access",
    "service": "nginx",
    "path": "/var/log/nginx/access.log",
    "pipeline": "nginx-access.p",
    "storage_index": "app-logs",
    "multiline_match": "^\\d{4}-\\d{2}-\\d{2}",
    "remove_ansi_escape_codes": false,
    "from_beginning": false,
    "character_encoding": "utf-8",
    "tags": {
      "env": "production",
      "team": "backend"
    }
  }
]

挂载路径设置¶

log_volume_paths：需要挂载的宿主路径列表（字符串数组），用于让 sidecar 能访问真实日志文件，例如 ["/var/log", "/data/log"]。请避免父子路径同时存在，防止 Volume 冲突。

Annotation 支持¶

Operator logfwd 注入支持在应用 Pod 上增加如下 Annotation：

• admission.datakit/logfwd.enabled：控制是否允许注入，值为 "false" 时拒绝注入，值为 "true" 或不设置时允许注入（但需配置匹配规则和 log_configs 字段才能实际触发注入）
• admission.datakit/logfwd.log_configs： Version-1.7.0 已移除，日志采集配置应完全通过 ClusterLoggingConfig CRD 进行管理
• admission.datakit/logfwd.volume_paths： Version-1.7.0 已移除，日志采集配置应完全通过 ClusterLoggingConfig CRD 进行管理

注入用例¶

下面是一个 Deployment 示例，使用 CRD 方式配置日志采集：

apiVersion: apps/v1
kind: Deployment
metadata:
    name: logging-demo
    namespace: middleware
    labels:
    app: logging
spec:
    replicas: 1
    selector:
    matchLabels:
        app: logging
    template:
    metadata:
        labels:
        app: logging
        annotations:
        admission.datakit/logfwd.enabled: "true"
    spec:
        containers:
        - name: log-app
        image: nginx:1.25

同时需要创建对应的 ClusterLoggingConfig CRD 资源来配置日志采集规则。

使用 yaml 文件创建资源：

$ kubectl apply -f logging.yaml
...

验证如下：

$ kubectl get pod

NAME                                   READY   STATUS    RESTARTS      AGE
logging-deployment-5d48bf9995-vt6bb       1/1     Running   0             4s

$ kubectl get pod logging-deployment-5d48bf9995-vt6bb -o=jsonpath={.spec.containers\[\*\].name}
log-container datakit-logfwd

最终可以在观测云日志平台查看日志是否采集。