Configuring Kratix

Kratix can be configured and customised via two ConfigMaps; Kratix Config and Kratix Pipeline Adapter Config.

Kratix Config

When Kratix starts, it reads the kratix ConfigMap from the kratix-platform-system namespace. This ConfigMap allow you to configure various parts of Kratix and follows the format outlined below. It is loaded when the kratix-platform-controller-manager pod starts within the same namespace.

If any changes are made to the ConfigMap, you will need to restart the kratix-platform-controller-manager pod to apply the updated configuration.

apiVersion: v1
kind: ConfigMap
metadata:
  name: kratix
  namespace: kratix-platform-system
data:
  config: |
    numberOfJobsToKeep: 5
    selectiveCache: false
    reconciliationInterval: "10h"
    workPlacementRewriteInterval: "10h"
    controllerLeaderElection:
      leaseDuration: 15s
      renewDeadline: 10s
      retryPeriod: 2s
    resourceBindingVersionStrategy: "floating" # floating (default) or pinned
    featureFlags:
      dryRun: false # preview feature; see below
    workflows:
      reconcileAfterFailure: true
      jobOptions:
        defaultBackoffLimit: 6
        podTTLSecondsAfterFinished: 3600 # seconds to keep completed Job Pods before cleanup; omit to use Kubernetes default
      defaultImagePullPolicy: IfNotPresent # can be `IfNotPresent`, `Always`, or `Never`
      defaultContainerResources: # optional; default CPU/memory requests and limits for pipeline containers
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "200m"
          memory: "256Mi"
      defaultContainerSecurityContext:
        runAsNonRoot: false
      defaultContainerResources:
        requests:
          cpu: "100m"
          memory: "128Mi"
          ephemeral-storage: "256Mi"
        limits:
          cpu: "200m"
          memory: "256Mi"
          ephemeral-storage: "256Mi"
    logging:
      level: "info" # one of info, warning, debug, trace
      structured: false # if true, emit logs as json
    git:
      minimumFetchInterval: "5s" # how often to fetch remote Git state before a write; 0s fetches every time
    telemetry:
      traces:
        enabled: true # false to disable traces
      metrics:
        enabled: true # false to disable metrics
      endpoint: grafana-k8s-monitoring-alloy-receiver.default.svc.cluster.local:4317 # exporter endpoint
      protocol: grpc # or http
      insecure: true
      headers: # additional headers if required
        authorization: "Bearer <grafana-api-token>"

numberOfJobsToKeep (default: 5)

The total number of completed Kratix workflow jobs to keep in the cluster. The oldest jobs will be deleted as new jobs are created.

selectiveCache (default: false)

Enable label selector caching of Secrets on the cluster to optimise memory usage. Secrets used by Kratix must be labelled with app.kubernetes.io/part-of=kratix.

reconciliationInterval (default: 10h)

The interval on which Kratix will rerun Configure workflows for both Promises and Resources. This is the platform-wide default; a Promise can override it via spec.workflows.config.reconciliationInterval.

workPlacementRewriteInterval (default: 10h)

The interval on which each WorkPlacement re-writes its files to the destination's state store, even when nothing has changed, so drift in the state store is corrected.

WorkPlacements are already re-written whenever their Workflow re-runs on the reconciliationInterval. This setting adds a separate re-write timer that is independent of Workflow runs. Set it to 0 to disable it, so WorkPlacements are only re-written in response to changes.

The re-write is a no-op when the files already match, as Git only commits and pushes when there is an actual change.

warning

Setting this too low can put significant load on your platform. Every WorkPlacement re-reconciles on each interval, and the cost scales with the number of WorkPlacements across all destinations. A short interval can lead to:

• State store load: a Git fetch and reset per WorkPlacement on every interval, which can trip provider rate limits (for example the GitHub API).
• Lock contention: WorkPlacements sharing a state store are serialised behind a per-repository lock, so frequent re-writes can queue up and delay genuine changes.

Keep the interval as large as your drift-correction needs allow.

controllerLeaderElection

Timeouts for the kratix controller's leader election. Defaults:

• leaseDuration: 15s
• renewDeadline: 10s
• retryPeriod: 2s

resourceBindingVersionStrategy

Controls the spec.version Kratix sets on a Resource Binding when it is first created. This determines whether a Resource Request automatically follows new Promise Revisions or stays pinned to the version it was created at.

• floating (default): new Resource Bindings are set to latest. The binding always tracks whichever Promise Revision is currently marked as latest, so when the Promise is upgraded to a new version the Resource Request is automatically re-reconciled against it.
• pinned: new Resource Bindings are set to the resolved latest version at the time of creation (for example v1.2.0). The binding stays locked to that Promise Revision, and later Promise upgrades do not automatically flow through to the Resource.

This strategy only sets the initial value of the binding. You can always change a binding's spec.version later to upgrade or pin a Resource — see the Upgrading a Promise guide.

featureFlags

Opts in to features that are off by default. Feature flags are read once at startup, so changing one requires restarting the kratix-platform-controller-manager pod.

dryRun (default: false)

Set to true to enable Dry Run, which previews the output of a Resource Request without applying it to a real Destination. While the flag is off, Kratix does not start the controller that reconciles DryRun objects and ignores dry-run labels elsewhere.

warning

Dry Run is a preview feature and is not production ready. Its API and behaviour may change without a migration path. See Dry Run before enabling it.

Workflows

Default configurations for Kratix Workflows. Any options configured within individual workflows will take precedence over those in the Kratix Config.

reconcileAfterFailure (default: true)

Controls whether periodic reconciliation reruns Promise and Resource Configure workflows after a failed run. When false, periodic reconciliation skips failed workflows, but manual reconciliation of a Promise or Resource still rerun them. This setting does not affect successful runs or Delete workflows.

jobOptions

Options for the Jobs that are created by Kratix Workflows.

defaultBackoffLimit

The number of times to retry a failing workflow Job before marking it failed. This configures the backoffLimit in Workflow Jobs. This will default to the Kubernetes Job default of 6.

podTTLSecondsAfterFinished

The number of seconds to retain completed workflow Job Pods before they are cleaned up. When set, Kratix runs a controller that deletes Pods belonging to completed Jobs after this TTL. Omit to use the Kubernetes default (Pods are retained until the Job is deleted). Must be greater than zero when set.

defaultContainerResources

Default CPU and memory requests and limits for pipeline containers. Pipeline-level resources override these defaults. When omitted, Kratix uses built-in defaults (100m/128Mi requests, 200m/256Mi limits).

defaultImagePullPolicy

When to pull the images specified in Workflows. This configures the imagePullPolicy in Workflow Jobs. Can be IfNotPresent, Always, or Never

defaultContainerSecurityContext

The Security Context to apply to all Workflow Pods.

defaultContainerResources

Defines the resource requirements that Workflow Jobs should default to. This controls the spec.resources for the generated pods.

logging

Logging configuration for the Kratix Controller Manager pod logs.

level (default: "info")

The log level. Can be "info", "warning", "debug" or "trace".

The different log levels and their meanings are described in the table below:

Level / Severity	Target Audience	Usage Guidelines	Examples
ERROR	All	Something is permanently broken and may require human intervention	Invalid YAMLs Can't talk to Git server Invalid Bucket endpoints
WARNING	All	Something is temporarily broken but may fix itself within the Reconciliation loop	Promise is unavailable State Store secret not found No available destinations
INFO	Platform Operator	Heartbeat of the platform Reconciliation-level logs Business relevant actions completed A resource status has changed	Reconciliation started and ended Scheduling work to a destination Next reconciliation time
DEBUG	Platform Operator / Platform Engineer	Function-level logs Transitional errors Code actions completed	Applying the Promise API Running a Pipeline for a Resource Creating a WorkPlacement
TRACE	Kratix Developer	Pre and Post actions Used to identify a particular line/area of code	Creating auxiliary resources Verifying if there's a pipeline in progress Calculating Promise Spec hash

structured (default: false)

Set to true to emit logs as json.

git

Configuration for how Kratix interacts with Git State Stores.

minimumFetchInterval (default: 5s)

Before writing to a Git State Store, Kratix fetches the latest remote state and resets its cached clone to match. This makes writes start from the true remote state, so Kratix recovers when the repository has been changed outside of Kratix (for example a manual commit, or a Flux or Argo prune).

minimumFetchInterval bounds how often that fetch happens. Writes to a State Store are serialised, so when many Workplacements reconcile against the same store in a burst, Kratix only refreshes the clone once per interval rather than fetching for every write. Set it to 0s to fetch before every write.

This value is loaded when the kratix-platform-controller-manager pod starts, so restart the pod after changing it.

telemetry

Telemetry configuration for Kratix. Configures OpenTelemetry export for traces and metrics.

• endpoint: OTLP exporter endpoint (e.g. grafana-k8s-monitoring-alloy-receiver.default.svc.cluster.local:4317).
• protocol: OTLP protocol; grpc (default) or http.
• insecure: Set to true to skip TLS verification when connecting to the endpoint.
• headers: Optional map of headers (e.g. authorization: "Bearer <token>") for authenticated endpoints.
• traces.enabled: Set to false to disable trace export. Defaults to true when telemetry is configured.
• metrics.enabled: Set to false to disable metrics export. Defaults to true when telemetry is configured.

Kratix Pipeline Adapter Config

When Kratix schedules work as part of either Promise or Resource workflows, by default, it uses the PIPELINE_ADAPTER_IMG image specified in the kratix-platform-pipeline-adapter-config configmap in the kratix-platform-system namespace. To override this image, which is necessary when deploying Kratix in an air-gapped environment, you can update this configmap to point to an internally hosted version of the image.

apiVersion: v1
kind: ConfigMap
metadata:
  name: kratix-platform-pipeline-adapter-config
  namespace: kratix-platform-system
...
data:
  PIPELINE_ADAPTER_IMG: org-registry.org/team/kratix-platform-pipeline-adapter:v0.2.0