Configuration

DataKit configuration is split between CLI configuration (hierarchical YAML files and environment variables) and runtime store configuration (Store manifests plus Kubernetes Secrets). Operators usually touch both: CLI config for local/admin workflows, Store manifests for package execution.

Configuration precedence

    flowchart TD
    A[Command flags] --> B[Environment variables]
    B --> C[Repo config .dk/config.yaml]
    C --> D[User config ~/.config/dk/config.yaml]
    D --> E[System config /etc/datakit/config.yaml]
    E --> F[Built-in defaults]

dk config documents three scopes in cli/cmd/config.go, and sdk/localdev/config.go implements the merge order as system → user → repo with defaults applied afterward.

Config file locations

Scope	Path	Notes
Repo	`{git-root}/.dk/config.yaml`	Highest file precedence; unavailable outside a git repo
User	`~/.config/dk/config.yaml`	Default writable scope for `dk config set --scope user`
User (XDG)	`${XDG_CONFIG_HOME}/dk/config.yaml`	Used when `XDG_CONFIG_HOME` is set
System	`/etc/datakit/config.yaml`	Lowest precedence shared config

Config keys

The table below lists every implemented key or key pattern handled by sdk/localdev/config.go and cli/cmd/config.go.

Key	Scope	Default	Purpose
`dev.runtime`	repo, user, system	`k3d`	Default local dev runtime
`dev.workspace`	repo, user, system	unset	Optional workspace path for dev commands
`dev.k3d.clusterName`	repo, user, system	`dk-local`	k3d cluster name
`dev.charts.<name>.version`	repo, user, system	unset	Override Helm chart version for a dev dependency
`dev.charts.<name>.values.<path>`	repo, user, system	unset	Override arbitrary Helm values for a dev dependency
`plugins.registry`	repo, user, system	`ghcr.io/infobloxopen`	Default OCI registry for plugin images
`plugins.mirrors[]`	repo, user, system	empty	Ordered fallback registries
`plugins.overrides.<name>.version`	repo, user, system	unset	Pin a plugin version
`plugins.overrides.<name>.image`	repo, user, system	unset	Replace a plugin image completely
`plugins.destinations.<name>.connection_string`	repo, user, system	unset	Force destination DSN for a plugin
`plugins.destinations.<name>.bucket`	repo, user, system	unset	Override S3 bucket
`plugins.destinations.<name>.region`	repo, user, system	unset	Override S3 region
`plugins.destinations.<name>.endpoint`	repo, user, system	unset	Override S3 endpoint
`plugins.destinations.<name>.path`	repo, user, system	unset	Override file or key-prefix path
`safety.productionIdentifiers`	repo, user, system	`prod,prd,com`	Prevent destructive/import operations against production-like targets

Example config

# .dk/config.yaml
dev:
  runtime: k3d
  workspace: /Users/example/dk-workspace
  k3d:
    clusterName: dk-local
  charts:
    redpanda:
      version: v25.2.0
      values:
        statefulset.resources.limits.memory: 1Gi
plugins:
  registry: ghcr.io/infobloxopen
  mirrors:
    - ghcr.io/backup-org
  overrides:
    postgresql:
      version: v8.14.1
  destinations:
    postgresql:
      connection_string: postgresql://user:pass@db:5432/analytics?sslmode=disable
safety:
  productionIdentifiers: prod,prd,com

Environment variables

These environment variables are read directly by the current CLI and controller sources.

Variable	Consumer	Effect
`XDG_CONFIG_HOME`	CLI config loader	Moves the user config path to `${XDG_CONFIG_HOME}/dk/config.yaml`
`DK_WORKSPACE_PATH`	`dk dev`	Overrides `dev.workspace`
`DK_REGISTRY`	`dk publish`	Default artifact registry when `--registry` is omitted
`DK_REGISTRY_USERNAME` / `DK_REGISTRY_PASSWORD` / `DK_REGISTRY_TOKEN`	registry auth	Supplies generic OCI credentials
`GITHUB_TOKEN`	`dk promote`, `dk rollback`, registry auth for `ghcr.io`	Auth for PR creation/status and GHCR pulls
`GITHUB_OWNER` / `GITHUB_REPO` / `GITHUB_BASE_URL`	promote/rollback	Override the GitOps target repo or GitHub base URL
`OPENLINEAGE_URL`	`dk run`, controller, chart env injection	Enables lineage emission when no explicit flag overrides it
`OPENLINEAGE_NAMESPACE`	controller	Default OpenLineage namespace, fallback `dk`
`KUBECONFIG`	`dk logs`	Required for non-dev log collection
`DOCKER_CONFIG`	registry auth, controller chart	Points to Docker credentials directory
`DOCKER_USERNAME` / `DOCKER_PASSWORD`	registry auth	Used for Docker Hub credentials
`GOOGLE_APPLICATION_CREDENTIALS`	registry auth	Service-account JSON for `gcr.io` / `pkg.dev`
`DEV_REGISTRY_MIRROR_HOST`	localdev cache	Changes the k3d registry-mirror endpoint
`CI`, `GITHUB_ACTIONS`, `JENKINS_URL`	localdev cache	Marks the process as running in CI
`DK_STORE_DSN_<NAME>` / `DK_STORE_TYPE_<NAME>`	runners, controller-generated workloads	Store resolution output injected into package containers

`dk config` command behavior

The config subcommands in cli/cmd/config.go work like this:

dk config set <key> <value> --scope <repo|user|system> writes a single key
dk config get <key> shows the effective value and source scope
dk config unset <key> --scope ... removes a value from one scope
dk config list [--scope ...] shows effective or scope-local keys
dk config add-mirror / remove-mirror manage plugins.mirrors[]

Examples:

dk config set dev.k3d.clusterName dk-local --scope user
dk config set plugins.registry ghcr.io/infobloxopen --scope repo
dk config add-mirror ghcr.io/backup-org --scope repo
dk config get plugins.registry
dk config list

Store manifests and connection resolution

Store manifests are the operator-facing runtime config for packages. The Store CRD exposes three fields that matter operationally:

Field	Meaning
`spec.connection`	Non-secret connection parameters
`spec.secrets`	Secret-bearing values with `${VAR}` interpolation
`spec.secretRef`	Maps logical credential names to keys in a Kubernetes Secret

Minimal store example:

apiVersion: datakit.infoblox.dev/v1alpha1
kind: Store
metadata:
  name: events
spec:
  connector: kafka
  connection:
    brokers: redpanda.dk-local.svc.cluster.local:9092
    topic: analytics.orders.c0

The runner resolves DSNs from store content using connector-specific rules in sdk/runner/storeenv.go:

Connector	Expected fields	Result
`postgres`	`host`, `port`, `database`/`dbname`, `user`, optional password	`postgresql://...`
`clickhouse`	`host`, `port`, `database`, `user`, optional password	`clickhouse://...` or `http://...` for port `8123`
`s3`	`bucket`, optional `region`, `endpoint`	`s3://bucket?...`
`kafka`	`bootstrapServers` or `brokers`, optional `topic`	`kafka://broker/topic`

The controller and local runner then inject resolved values into workloads as DK_STORE_DSN_<NAME> and DK_STORE_TYPE_<NAME>.

Store scaffolding and secret mapping

dk store create is the operator-friendly way to scaffold manifests. Useful flags from cli/cmd/store_create.go:

--connector selects the connector type
--secret-name, --secret-namespace, and repeatable --secret-key map credentials
repeatable --set fills spec.connection keys
--host-override helps with local port-forward testing
--no-detect-cluster skips ClickHouse cluster autodetection

Example:

dk store create ch-prod --connector clickhouse \
  --secret-name ch-prod-secrets \
  --secret-key password=cube-password \
  --set host=chi-prod-cluster-0-0.ns.svc.cluster.local \
  --set port=9000 \
  --set database=dk \
  --set user=cube \
  --set cluster='{cluster}'

Next Steps

CLI Reference Troubleshooting