Helm Installation¶

This document describes how to install, configure, and upgrade DataKit in Kubernetes with Helm. Custom settings go in values.yaml, which the Chart uses to configure container environment variables and mounted files.

Installation and Configuration¶

Prerequisites¶

• Helm 3 or later and kubectl installed, with access to the target Kubernetes cluster.
• Permissions to create the DataKit workload and its required resources.
• A complete DataWay URL, including the token, or a Kubernetes Secret containing that URL.

The examples use datakit as both the Helm release name and namespace. Run commands from the directory containing values.yaml.

Choose Versions¶

The Helm Chart version controls the installation templates; the DataKit image version controls the running program:

• --version selects the Chart version. The commands below use 2.14.1 as an example; replace it with the published version you need.
• image.tag selects the DataKit image version. If unset, it defaults to the Chart's appVersion. To keep the same image when upgrading only the Chart, set image.tag in values.yaml to your current image version.

CHART_VERSION=2.14.1

View Default Values¶

View the complete defaults for the selected version:

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

Prepare values.yaml¶

Create values.yaml in the current directory and add one of the DataWay configurations from the next section. Add other settings as needed. Omitted settings use Chart defaults, so you do not need to copy the entire default configuration.

When combining examples, merge settings under their existing keys. For example, keep one top-level datakit entry containing both dataway_url and global_tags.

Configure DataWay¶

All three options configure the container's ENV_DATAWAY environment variable and work with both DaemonSet and Deployment. Choose one:

Literal URL¶

Replace the example URL and token with your actual values:

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

Chart-Managed Secret¶

The Chart creates a Secret from dataway_url and configures the container to obtain ENV_DATAWAY from that Secret:

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 defaults to true, so existing Secret configurations continue to work. This mode still requires the complete URL in Helm values. Base64 encoding in a Secret is not encryption. If credentials must stay out of Helm values, use the next option.

Existing Secret¶

Helm Chart 2.14.1 and later supports referencing a Secret managed by you or another system. Helm values need only the Secret name and key, without credentials. This is a Chart capability and does not require a DataKit image upgrade.

For example, prepare a Secret named datakit-dataway in the same namespace as the DataKit Pod. Its url key must contain the complete DataWay URL, including the token. Configure values.yaml as follows:

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

• dataway_secret_name: the Secret to reference, in the same namespace as the DataKit Pod.
• dataway_secret_key: the key containing the complete URL. It can be url or another name; it does not have to be ENV_DATAWAY.
• The container environment variable is always named ENV_DATAWAY. Do not also define it in extraEnvs.

The Chart only creates the reference. It does not create or read the Secret, and it ignores dataway_url. The name and key must be nonempty. Rendering does not require the Secret to exist. If the Secret or key is missing at startup, Kubernetes waits and retries, without falling back to a literal URL.

Updating credentials: Secret updates do not change environment variables in running containers. After confirming that the Secret has been updated, restart the workload using the appropriate command below. Adjust the resource name and namespace for your deployment:

# DaemonSet
kubectl rollout restart daemonset/datakit -n datakit

# Deployment
kubectl rollout restart deployment/datakit -n datakit

Migrating from a Chart-managed Secret: Prepare the external Secret under a new name and confirm it is ready before changing values and upgrading. Helm may delete the previously Chart-managed Secret during the upgrade; using a new name keeps the new reference unaffected. The external Secret's lifecycle remains the responsibility of its manager.

Install DataKit¶

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

Check Workload Status¶

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

The default workload is a DaemonSet. Once the workload is ready, check the collected data in Guance.

Common Configuration¶

Merge these optional settings into values.yaml before installation, or apply them to an existing deployment with Helm upgrade.

Enable Collectors¶

datakit.default_enabled_inputs is a comma-separated collector list. Setting it replaces the entire list. When adding a collector, retain the collectors you need from the selected Chart version's defaults.

The following example appends rum to the default list:

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

Configure Collector Election¶

Collector election prevents multiple DataKit instances from collecting the same shared data. The Chart defaults are:

datakit:
  enabled_election: true
  election_operator_url: ""

With an empty election_operator_url, DataWay/Kodo coordinates the election. To use DataKit Operator, set this field to its HTTPS URL. For version and permission requirements and provider selection rules, see DataKit Operator election.

Set Global Tags¶

This example retains the default host tags and adds env=prod. Separate tags with commas:

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

Set Environment Variables¶

Add environment variables through extraEnvs. For example, set the DataKit self-monitoring collection interval to 30 seconds:

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

If extraEnvs already exists, append entries to that list. Use the dedicated DataWay settings described above. For other variables, see Container Environment Variables and the relevant collector documentation.

Mount Collector Configuration¶

Use dkconfig to mount collector configuration files. path is the file path inside the container, under /usr/local/datakit/conf.d/; name is the file name; value contains its configuration.

The standard Chart mounts the host root directory at /rootfs inside the container. This example collects the host's /var/log/syslog through /rootfs/var/log/syslog in the container. Adjust the path to match your log file:

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

For complete settings, see the Logging Collector, or the corresponding sample file under /usr/local/datakit/conf.d/ in the container.

Mount Pipeline¶

Pipeline files also use dkconfig, with paths under /usr/local/datakit/pipeline/. This example adds an env field to logs:

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

To mount both a collector configuration and a Pipeline, put both entries in the same dkconfig list. To use this script in the logging collector above, add pipeline = "test.p" to its [[inputs.logging]] configuration. For more details, see the Pipeline documentation.

Upgrade¶

Keep your existing values.yaml, review the target Chart's defaults, and adjust settings as needed. If the original file is unavailable, export the current release's custom values:

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

Select the target Chart version and upgrade:

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

To keep the current DataKit image version, explicitly set image.tag in values.yaml. After upgrading, check workload status.

Uninstall¶

helm uninstall datakit -n datakit

Uninstalling deletes resources managed by this release, including a DataWay Secret created by the Chart. A Secret that is independently managed outside the release and only referenced by the Chart is retained.

Special Environments¶

GKE Autopilot¶

For Google Kubernetes Engine Autopilot clusters, follow the GCP GKE Autopilot deployment guide to choose the collection mode, Chart, and required permissions.

Common Parameters¶

The table lists common parameters for the standard DataKit Chart. For the complete configuration and defaults of your selected version, use helm show values as described in View Default Values.

Troubleshooting¶

DataWay Secret Configuration¶

For Helm Secret settings, see Configure DataWay. If a container cannot start after enabling Secret mode, check that the Secret is in the Pod's namespace and that its name and key match the values.

For installation with native Kubernetes YAML, see Configure DataWay with a Secret.

Legacy PodSecurityPolicy¶

Kubernetes 1.25 removed PodSecurityPolicy. After a cluster upgrade, an old Helm release that still records this resource, such as a previously enabled kube-state-metrics dependency, may fail to upgrade with:

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

Back Up Configuration¶

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

These files help inspect and recover configuration; they are not a complete Helm release backup. They may contain credentials and must be stored securely.

Migrate Release Records¶

Choose a Chart compatible with the current Kubernetes version, then follow the Helm deprecated API migration guide to back up and migrate the release records stored in the cluster. Do not clear history by deleting sh.helm.release.v1.* Secrets: Helm would lose the original release's management records.

Upgrade After Migration¶

After migration, deploy the compatible version with the upgrade command above. Before future Kubernetes upgrades, check and update Charts and deployed releases that still use deprecated APIs.