Reference

The Reference section documents the options, functions, schemas, and policy rules that make up Kix. Each page is organized for quick lookup with field tables, default values, and compact examples.

Reference sections

Cluster and instance configuration

Page	Covers
kix.toml	Project configuration beside flake.nix that chooses whether Kix evaluates with the Kix runtime (builder = "kix") or the machine’s Nix (builder = "nix").
Cluster configuration	How to configure cluster-wide settings such as availability targets, namespaces, network policies, and scorecard enforcement.
Instances and composition	How to declare package instances in a cluster, wire dependencies across namespaces, and stamp environments across teams.
Flavors and capabilities	Built-in provider profiles (kix.flavors.*) that pre-configure cloud capabilities, storage classes, and platform services.

Package authoring and helpers

Page	Covers
Package anatomy	The structure of a Kix package file, how it declares typed options, and how it builds Kubernetes resources.
Resources and out	How scope builders construct Kubernetes resources and expose .out fields that track dependencies automatically.
Composition helpers	Shorthand kix.* functions for environment variables, volume mounts, Services, ingress routes, monitoring, and health checks.
Secrets, CRDs, and RBAC	Specialized builders that validate Secret keys, CustomResourceDefinitions, and RBAC permissions at build time.
Helm and imports	How to wrap upstream Helm charts as Kix packages and model pre-existing cluster services with kix.mkImport.

Policy, validation, and runtime records

Page	Covers
Dependency contracts	Shared kix.contracts.* schemas, credential rules (out.credentials), and kix.mkImport shapes for databases, Redis, mail (smtp), single sign-on (oidc), Gateways, and OpenTelemetry.
Scorecard and rules	How build-time scorecard rules work, how to customize severities, and the full catalog of built-in checks.
Validation checks	The 24 always-on cross-resource checks that verify selectors, ports, volumes, and CRD ordering on every build.
Annotations, CRDs, and receipts	Bookkeeping kix.run/* annotations, in-cluster Activation and PackageInstance records, and deploy receipts.

I want to…

Goal	Where to look
Choose whether a project uses the Kix runtime or the machine’s Nix installation	kix.toml
Understand how dependencies control deploy order and network policies	The dependency graph
Write a package with a Deployment and Service	Package anatomy, Resources and out, and Composition helpers
Add typed configuration options to a package	Add typed package options and Package anatomy
Expose a Service with an Ingress or Gateway API HTTPRoute	Expose a service with Ingress, Expose a service with Gateway API, and Composition helpers
Wire a package to a specific database, cache, or storage instance	Instances and composition and Wire cross-namespace dependencies explicitly
Connect an external database, Redis cache, mail server (smtp), or single sign-on provider (oidc)	Connect external databases, caches, mail, and single sign-on, Import an existing service with kix.mkImport, and Dependency contracts
Manage Secrets, CRDs, or RBAC permissions in a package	Secrets, CRDs, and RBAC
Wrap an upstream Helm chart as a Kix package	Helm and imports and Helm integration
Set cluster availability levels and derive pod spread and PDBs	Cluster configuration and Availability levels
Configure or override scorecard rules	Scorecard and rules and Cluster configuration
Customize an instance’s resources from the cluster without editing the package	Instances and composition and Patch package output with overlays
Stamp the same application stack across multiple environments	Instances and composition

Top Nix DSL idioms

Common patterns used across Kix packages and cluster definitions:

# Reference a resource name while tracking the dependency:
self.service.out.name

# Reference a Service's in-cluster FQDN or URL:
self.service.out.fqdn
self.service.out.url { scheme = "http"; port = 8080; }

# Reference a workload's pod selector while tracking the dependency:
self.deployment.out.selector

# Read a workload's pod selector without creating a dependency cycle:
self.deployment.rawSelector

# Build a workload with volume mounts using the pipe operator:
{ name = "web"; spec = { ... }; }
  |> kix.withMounts [ self.dataMount ]
  |> scope.mkDeployment

# Derive a Service from a workload's selector and container ports:
self.deployment
  |> kix.service.fromWorkload { name = "web"; }
  |> scope.mkResource

# Expose a Service via Ingress or Gateway API HTTPRoute:
(kix.expose { service = "service"; })

# Create a ServiceMonitor and optional alert rules when Prometheus is present:
(kix.monitor { service = "service"; port = "metrics"; })

# Run a post-deploy health check Job against service outputs:
(kix.healthCheck {
  script = builtins.readFile ./health-check.py;
  env = { self, ... }: { TARGET_URL = self.service.out.url { }; };
})

# Reference a key from a Kix-managed Secret:
self.credentials.out.keyRef "password"

# Reference a key from an externally managed Secret:
(scope.mkSecretRef {
  name = "external-db-creds";
  keys = [ "username" "password" ];
}).out.keyRef "password"

# Read a container image from a committed pin file and render repo:tag@digest:
# (in cluster config) config.image = pins.get "web";
# (in package build) image = kix.image.ref config.image;

# Convert an attribute set of environment variables to a Kubernetes env list, dropping nulls:
kix.mkEnvVars {
  LOG_LEVEL = config.logLevel;
  OPTIONAL_FLAG = config.optionalFlag or null;
  DB_PASSWORD = database.out.credentials.out.keyRef "password";
}

# Gate an optional resource on a boolean condition:
scope.mkOptional config.metrics.enabled (_: scope.mkResource { ... })

# Write an intentional empty map (such as emptyDir) that must not be stripped:
emptyDir = { };

# Prevent a constructor-built map from collapsing when all optional fields are null:
kix.keep {
  medium = config.medium;
  sizeLimit = config.sizeLimit;
}