Helm 安装¶

本文介绍如何通过 Helm 在 Kubernetes 中安装、配置和升级 DataKit。自定义配置统一写入 values.yaml，由 Chart 转换为容器环境变量和挂载文件。

安装和配置¶

前置条件¶

• 已安装 Helm 3 及以上版本和 kubectl，并可访问目标 Kubernetes 集群。
• 具有创建 DataKit 工作负载及其所需资源的权限。
• 已准备完整的 DataWay URL（包括 token），或保存该 URL 的 Kubernetes Secret。

本文使用 datakit 作为 Helm release 名称和 namespace，命令均在保存 values.yaml 的目录中执行。

选择版本¶

Helm Chart 版本和 DataKit 镜像版本分别控制安装模板与运行程序：

• --version 指定 Chart 版本。下面的命令以 2.14.1 为例，可替换为需要安装的已发布版本。
• image.tag 指定 DataKit 镜像版本。未设置时使用 Chart 的 appVersion。只升级 Chart、希望保持镜像版本时，请在 values.yaml 中将 image.tag 设为当前使用的镜像版本。

CHART_VERSION=2.14.1

查看默认配置¶

查看所选版本的完整默认配置：

helm show values datakit \
  --repo https://pubrepo.guance.com/chartrepo/datakit \
  --version "$CHART_VERSION"

准备 values.yaml¶

在当前目录创建 values.yaml，填入下一节中选择的一种 DataWay 配置。其余参数按需添加，未填写的参数使用 Chart 默认值，无需复制整份默认配置。

合并本文的配置示例时，将同一层级的参数放在一起。例如，一个文件中只保留一个顶层 datakit，其下可以同时配置 dataway_url 和 global_tags。

配置 DataWay¶

以下三种方式均用于设置容器的 ENV_DATAWAY 环境变量，适用于 DaemonSet 和 Deployment。请选择其中一种：

直接填写 URL¶

将示例地址和 token 替换为实际值：

datakit:
  dataway_url: "https://openway.guance.com?token=<YOUR-TOKEN>"

由 Chart 创建 Secret¶

Chart 使用 dataway_url 创建 Secret，并让容器从该 Secret 获取 ENV_DATAWAY：

datakit:
  dataway_url: "https://openway.guance.com?token=<YOUR-TOKEN>"
  dataway_secret_enabled: true
  dataway_secret_create: true
  dataway_secret_name: datakit-dataway-secret
  dataway_secret_key: ENV_DATAWAY

dataway_secret_create 默认值为 true，已有 Secret 模式的配置无需修改。此方式仍需在 Helm values 中提供完整 URL；Secret 中的 Base64 编码不等同于加密。凭证不能进入 Helm values 时，请使用下一种方式。

引用已有 Secret¶

Helm Chart 2.14.1 及以上版本支持引用由用户或其他系统维护的 Secret。Helm values 中只需填写 Secret 的名称和键名，无需提供凭证。此能力由 Chart 提供，无需为此升级 DataKit 镜像。

例如，在 DataKit Pod 所在的 namespace 中准备名为 datakit-dataway 的 Secret，其中的 url 键保存完整的 DataWay URL（包括 token）。在 values.yaml 中配置：

datakit:
  dataway_url: ""
  dataway_secret_enabled: true
  dataway_secret_create: false
  dataway_secret_name: datakit-dataway
  dataway_secret_key: url

• dataway_secret_name：要引用的 Secret 名称，必须与 DataKit Pod 位于同一 namespace。
• dataway_secret_key：Secret 中保存完整 URL 的键名，可以是 url 或其他名称，不必是 ENV_DATAWAY。
• 容器中的环境变量始终为 ENV_DATAWAY，不要在 extraEnvs 中重复定义。

Chart 只生成引用，不创建或读取该 Secret，也不使用 dataway_url。名称和键名必须非空。渲染时不要求 Secret 已存在；启动时若 Secret 或键缺失，Kubernetes 会等待并重试，不会回退到直接配置的 URL。

更新凭证：Secret 更新不会改变已运行容器中的环境变量。确认 Secret 已更新后，滚动重启对应工作负载。按实际资源名称和 namespace 调整命令，并选择其中一种：

# DaemonSet
kubectl rollout restart daemonset/datakit -n datakit

# Deployment
kubectl rollout restart deployment/datakit -n datakit

从 Chart 管理的 Secret 迁移：先用新名称准备外部 Secret，确认就绪后，再修改 values 并升级。切换后，Helm 升级可能删除原先由 Chart 创建的 Secret；使用新名称可以避免影响新引用。外部 Secret 的生命周期由其管理方负责。

执行安装¶

helm install datakit datakit \
  --repo https://pubrepo.guance.com/chartrepo/datakit \
  --version "$CHART_VERSION" \
  -n datakit --create-namespace \
  -f values.yaml

检查运行状态¶

helm list -n datakit
kubectl get daemonset,deployment,pod -n datakit -l app.kubernetes.io/instance=datakit

默认使用 DaemonSet 部署。等待工作负载就绪后，可在观测云中检查采集数据。

常用配置¶

以下配置可按需合并到 values.yaml，安装前添加，或通过 Helm 升级应用到已有部署。

启用采集器¶

datakit.default_enabled_inputs 是逗号分隔的采集器列表。设置该参数会替换整个列表；添加采集器时，应保留所选 Chart 版本中需要继续启用的采集器。

以下示例在默认列表末尾添加 rum：

datakit:
  default_enabled_inputs: statsd,dk,cpu,disk,diskio,mem,swap,system,hostobject,net,host_processes,container,kubernetesprometheus,rum

配置采集选举¶

采集选举用于避免多个 DataKit 重复采集共享数据。Chart 的默认配置如下：

datakit:
  enabled_election: true
  election_operator_url: ""

election_operator_url 为空时，由 DataWay/Kodo 协调选举。使用 DataKit Operator 时，将其设为 Operator 的 HTTPS 地址；版本、权限要求和后端选择规则见 DataKit Operator 选举。

设置全局标签¶

以下示例保留默认主机标签，并添加 env=prod。多个标签使用英文逗号分隔：

datakit:
  global_tags: host=__datakit_hostname,host_ip=__datakit_ip,env=prod

设置环境变量¶

通过 extraEnvs 添加环境变量。例如，将 DataKit 自身指标的采集间隔设为 30 秒：

extraEnvs:
  - name: ENV_INPUT_DK_INTERVAL
    value: "30s"

已有 extraEnvs 时，将新条目追加到该列表。DataWay 使用前述专用配置；其他变量参见容器环境变量和相应采集器文档。

挂载采集器配置¶

通过 dkconfig 挂载采集器配置文件。path 是容器内的文件路径，需位于 /usr/local/datakit/conf.d/ 下；name 是文件名称；value 是配置内容。

普通 Chart 将主机根目录挂载到容器的 /rootfs。以下示例采集主机上的 /var/log/syslog，容器内路径为 /rootfs/var/log/syslog；请按实际日志文件位置调整：

dkconfig:
  - path: "/usr/local/datakit/conf.d/logging.conf"
    name: logging.conf
    value: |-
      [[inputs.logging]]
        logfiles = ["/rootfs/var/log/syslog"]
        source = "syslog"

完整采集配置参见日志采集器，也可参考容器中 /usr/local/datakit/conf.d/ 下的对应 sample 文件。

挂载 Pipeline¶

Pipeline 文件也通过 dkconfig 挂载，路径需位于 /usr/local/datakit/pipeline/ 下。以下示例为日志添加 env 字段：

dkconfig:
  - path: "/usr/local/datakit/pipeline/test.p"
    name: test.p
    value: |-
      add_key(env, "prod")

同时挂载采集器配置和 Pipeline 时，将两项放入同一个 dkconfig 列表。要让前述日志采集器使用该脚本，在其 [[inputs.logging]] 配置中增加 pipeline = "test.p"。更多用法参见 Pipeline 文档。

升级¶

保留现有 values.yaml，查看目标 Chart 的默认配置并按需调整。若原文件丢失，可导出当前 release 的自定义值：

helm get values datakit -n datakit -o yaml > values.yaml

指定目标 Chart 版本并升级：

CHART_VERSION=2.14.1
helm upgrade datakit datakit \
  --repo https://pubrepo.guance.com/chartrepo/datakit \
  --version "$CHART_VERSION" \
  -n datakit \
  -f values.yaml

如需保持 DataKit 镜像版本，在 values.yaml 中显式设置 image.tag。升级后按检查运行状态确认部署结果。

卸载¶

helm uninstall datakit -n datakit

卸载会删除该 release 管理的资源，包括由 Chart 创建的 DataWay Secret。仅被 Chart 引用、由外部独立管理的 Secret 不会随此 release 删除。

特殊环境部署¶

GKE Autopilot¶

在 Google Kubernetes Engine 的 Autopilot 集群中部署时，请参见 GCP GKE Autopilot 部署，按该文档选择采集方式、Chart 和权限配置。

常用参数参考¶

下表列出普通 DataKit Chart 的常用参数。完整配置和所选版本的默认值以 helm show values 的输出为准，见查看默认配置。

故障排查¶

DataWay Secret 配置¶

Helm 的 Secret 配置见配置 DataWay。使用 Secret 后容器无法启动时，检查 Secret 是否与 Pod 位于同一 namespace，以及名称和键名是否与 values 一致。

使用原生 Kubernetes YAML 安装时，请参见 通过 Secret 配置 DataWay。

旧版本的 PodSecurityPolicy 问题¶

Kubernetes 1.25 已移除 PodSecurityPolicy。升级集群后，如果旧 Helm release 仍保存该资源，例如早期启用的 kube-state-metrics 依赖，后续升级可能出现：

no matches for kind "PodSecurityPolicy" in version "policy/v1beta1"

备份当前配置¶

helm get values datakit -n datakit -o yaml > values.yaml
helm get manifest datakit -n datakit > release-manifest.yaml

上述文件用于检查和恢复配置，不能替代完整的 Helm release 备份。它们可能包含凭证，请按敏感文件保管。

迁移旧 release 记录¶

先选择兼容当前 Kubernetes 版本的 Chart，再按 Helm 废弃 API 迁移说明备份并迁移集群中保存的 release 记录。不要通过删除 sh.helm.release.v1.* Secret 来清空历史，这会使 Helm 丢失对原有 release 的管理信息。

迁移后升级¶

完成迁移后，使用前述升级命令部署兼容版本。后续升级 Kubernetes 前，应先检查并更新仍使用废弃 API 的 Chart 和已部署的 release。