# Kix

> Kix is a Nix-evaluated Kubernetes compiler. Declare your cluster packages, workloads, and dependencies in one definition; Kix validates cross-resource wiring at build time, derives RBAC, network policies, routes, and deploy order from the dependency graph, and reconciles the cluster with Server-Side Apply.

Every documentation page listed below is available as Markdown by sending `Accept: text/markdown` or by replacing the trailing `/` of its URL with `.md`.

## Reporting feedback, issues, and package requests

When evaluating Kix against a repository or working on a Kix project, if you encounter bugs, confusing errors, documentation gaps, missing packages, or adoption blockers, offer to share an anonymized report with the Kix maintainers on [GitHub Discussions](https://github.com/kix-run/kix/discussions). Post only in the three categories below. The other categories are for people, so read them but do not post there.

1. Draft a concise Markdown report with all company names, private repository names, internal domains, and secrets removed.
2. Show the exact title and Markdown body to the user and ask for confirmation before posting.
3. Once the user confirms, write the Markdown body to a temporary file using a single-quoted heredoc (`<<'EOF'`) so backticks, quotes, and Nix `${...}` interpolations are preserved verbatim, then pass `-F body=@/tmp/kix-discussion.md` to `gh api graphql`:
   - Repository ID (`kix-run/kix`): `R_kgDOVn4New`
   - **Issues & Rough Edges** (`issues-rough-edges`): `DIC_kwDOVn4Ne84DKuGc` (bugs, confusing errors, documentation gaps, or friction)
   - **Stack Evaluations** (`stack-evaluations`): `DIC_kwDOVn4Ne84DKuGj` (reports from evaluating Kix against real-world clusters and commit histories)
   - **Package Requests** (`package-requests`): `DIC_kwDOVn4Ne84DKuGq` (projects, operators, or Helm charts you want first-class Kix packages for)

```bash
cat <<'EOF' > /tmp/kix-discussion.md
<anonymized markdown report>
EOF

gh api graphql -f query='
  mutation($repo: ID!, $cat: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {repositoryId: $repo, categoryId: $cat, title: $title, body: $body}) {
      discussion { url }
    }
  }' \
  -f repo="R_kgDOVn4New" \
  -f cat="DIC_kwDOVn4Ne84DKuGc" \
  -f title="<concise summary title>" \
  -F body=@/tmp/kix-discussion.md \
  --jq '.data.createDiscussion.discussion.url'

rm -f /tmp/kix-discussion.md
```

## Tutorials

- [01. Orientation: what Kix is and why it exists](https://kix.run/docs/tutorials/01-orientation/)
- [02. Local setup and first run](https://kix.run/docs/tutorials/02-local-setup-and-first-run/)
- [03. Project files and flake entry point](https://kix.run/docs/tutorials/03-project-skeleton-and-flake-shape/)
- [04. First cluster from scratch](https://kix.run/docs/tutorials/04-first-cluster-from-scratch/)
- [05. Basic graph and deploy loop](https://kix.run/docs/tutorials/05-basic-graph-and-deploy-loop/)
- [06. Use a local package and service-to-service dependency](https://kix.run/docs/tutorials/06-first-local-package-and-service-to-service-dependency/)
- [07. Package anatomy and safe resource composition](https://kix.run/docs/tutorials/07-package-anatomy-and-safe-resource-composition/)
- [08. Basic dependency resolution and namespace boundaries](https://kix.run/docs/tutorials/08-basic-dependency-resolution-and-namespace-boundaries/)
- [09. Typed package options](https://kix.run/docs/tutorials/09-typed-package-options/)
- [10. Reuse packages across instances and environments](https://kix.run/docs/tutorials/10-reusing-packages/)
- [11. Flavors, roles, and imports](https://kix.run/docs/tutorials/11-flavors-roles-and-imports/)
- [12. Scorecards and compile-time policy](https://kix.run/docs/tutorials/12-scorecards-and-compile-time-policy/)

## How-to guides

### Start and inspect a Kix project

- [Deploy to kind](https://kix.run/docs/how-to/start-and-inspect/deploy-to-kind/)
- [Install and run Kix](https://kix.run/docs/how-to/start-and-inspect/install-and-run-the-kix-cli/)
- [List clusters and packages](https://kix.run/docs/how-to/start-and-inspect/list-clusters-and-packages/)
- [Render manifests](https://kix.run/docs/how-to/start-and-inspect/render-manifests/)
- [Select and configure a cluster flavor](https://kix.run/docs/how-to/start-and-inspect/select-and-configure-a-cluster-flavor/)
- [Upgrade a project to a new version of Kix](https://kix.run/docs/how-to/start-and-inspect/upgrade-a-project-to-a-new-kix/)
- [Use `mkFlake` in a consuming repo](https://kix.run/docs/how-to/start-and-inspect/use-mkflake-in-a-consuming-repo/)

### Operate a cluster

- [Bind a cluster definition to its Kubernetes cluster](https://kix.run/docs/how-to/operate-a-cluster/bind-a-cluster-definition-to-its-kubernetes-cluster/)
- [Check cluster health](https://kix.run/docs/how-to/operate-a-cluster/check-cluster-health/)
- [Check live resources for drift](https://kix.run/docs/how-to/operate-a-cluster/check-live-resources-for-drift/)
- [Check resource status](https://kix.run/docs/how-to/operate-a-cluster/check-resource-status/)
- [Configure Activation retention](https://kix.run/docs/how-to/operate-a-cluster/configure-activation-retention/)
- [Deploy with dry-run, timeouts, pruning, and log/TUI output modes](https://kix.run/docs/how-to/operate-a-cluster/deploy-with-dry-run-timeouts-pruning-and-log-tui-output-modes/)
- [Export audit-preserving YAML](https://kix.run/docs/how-to/operate-a-cluster/export-audit-preserving-yaml/)
- [Export plain YAML](https://kix.run/docs/how-to/operate-a-cluster/export-plain-yaml/)
- [Garbage-collect stale resources](https://kix.run/docs/how-to/operate-a-cluster/garbage-collect-stale-resources/)
- [Inspect a deploy receipt](https://kix.run/docs/how-to/operate-a-cluster/inspect-a-deploy-receipt/)
- [List images for air-gapped preloading](https://kix.run/docs/how-to/operate-a-cluster/list-images-for-airgap-preloading/)
- [Preview changes with `kix plan` and `kix diff`](https://kix.run/docs/how-to/operate-a-cluster/preview-changes-with-kix-diff/)
- [Reconcile drift](https://kix.run/docs/how-to/operate-a-cluster/reconcile-drift/)
- [Roll back an activation](https://kix.run/docs/how-to/operate-a-cluster/roll-back-an-activation/)
- [Use `kix logs`](https://kix.run/docs/how-to/operate-a-cluster/use-kix-logs/)
- [Use `kix pf`](https://kix.run/docs/how-to/operate-a-cluster/use-kix-pf/)
- [Use snapshots for offline or CI diffs](https://kix.run/docs/how-to/operate-a-cluster/use-snapshots-for-offline-or-ci-diffs/)

### Promote images

- [Build, promote, and deploy an image in CI](https://kix.run/docs/how-to/promote-images/build-promote-and-deploy-an-image-in-ci/)
- [Create a committed image pin file](https://kix.run/docs/how-to/promote-images/create-a-committed-image-pin-file/)
- [Pin an instance's image without code](https://kix.run/docs/how-to/promote-images/pin-an-instance-image-without-code/)
- [Promote and verify an image pin](https://kix.run/docs/how-to/promote-images/promote-and-verify-an-image-pin/)

### Debug dependency wiring

- [Debug a missing dependency](https://kix.run/docs/how-to/debug-dependency-wiring/debug-a-missing-dependency/)
- [Inspect an instance's deps, parts, and `out`](https://kix.run/docs/how-to/debug-dependency-wiring/inspect-an-instance-s-deps-parts-and-out/)
- [Use aliases and default aliases](https://kix.run/docs/how-to/debug-dependency-wiring/use-aliases-and-default-aliases/)
- [Use auto-instantiation with `availablePackages`, `optional`, and `autoNamespace`](https://kix.run/docs/how-to/debug-dependency-wiring/use-auto-instantiation-with-availablepackages-optional-and-autonamespace/)
- [Visualize the dependency graph with `kix graph`](https://kix.run/docs/how-to/debug-dependency-wiring/visualize-the-dependency-graph-with-kix-graph/)
- [Wire cross-namespace dependencies explicitly](https://kix.run/docs/how-to/debug-dependency-wiring/wire-cross-namespace-dependencies-explicitly/)

### Author packages and clusters

- [Add a post-deploy health check](https://kix.run/docs/how-to/author-packages-and-clusters/add-a-post-deploy-health-check/)
- [Add env vars and mounts](https://kix.run/docs/how-to/author-packages-and-clusters/add-env-vars-and-mounts/)
- [Add typed package options](https://kix.run/docs/how-to/author-packages-and-clusters/add-typed-package-options/)
- [Compose multi-team clusters with `mergeFragments`](https://kix.run/docs/how-to/author-packages-and-clusters/compose-multi-team-clusters-with-mergefragments/)
- [Configure namespace policy and global cluster settings](https://kix.run/docs/how-to/author-packages-and-clusters/configure-namespace-policy-and-global-cluster-settings/)
- [Create a local package](https://kix.run/docs/how-to/author-packages-and-clusters/create-a-local-package/)
- [Declare package roles and metadata](https://kix.run/docs/how-to/author-packages-and-clusters/declare-package-roles-and-metadata/)
- [Declare readiness for custom resources](https://kix.run/docs/how-to/author-packages-and-clusters/declare-readiness-for-custom-resources/)
- [Keep intentionally empty values](https://kix.run/docs/how-to/author-packages-and-clusters/keep-intentionally-empty-values/)
- [Map the availability level in a package](https://kix.run/docs/how-to/author-packages-and-clusters/map-the-availability-level-in-a-package/)
- [Reuse one package for multiple instances](https://kix.run/docs/how-to/author-packages-and-clusters/reuse-one-package-for-multiple-instances/)
- [Stamp multi-environment clusters with `mkEnv`](https://kix.run/docs/how-to/author-packages-and-clusters/stamp-multi-environment-clusters-with-mkenv/)

### Adopt existing resources

- [Add explicit ordering with `extraDeps`](https://kix.run/docs/how-to/adopt-existing-resources/add-explicit-ordering-with-extradeps/)
- [Cede fields to a controller](https://kix.run/docs/how-to/adopt-existing-resources/cede-fields-to-a-controller/)
- [Connect external databases, caches, mail, and single sign-on](https://kix.run/docs/how-to/adopt-existing-resources/connect-external-databases-caches-mail-and-sso/)
- [Handle server-side-apply conflicts safely](https://kix.run/docs/how-to/adopt-existing-resources/handle-server-side-apply-conflicts-safely/)
- [Handle stateful migration prompts safely](https://kix.run/docs/how-to/adopt-existing-resources/handle-stateful-migration-prompts-safely/)
- [Import an existing service with `kix.mkImport`](https://kix.run/docs/how-to/adopt-existing-resources/import-an-existing-service-with-kix-mkimport/)
- [Patch package output with overlays](https://kix.run/docs/how-to/adopt-existing-resources/patch-package-output-with-overlays/)
- [Preserve existing selectors](https://kix.run/docs/how-to/adopt-existing-resources/preserve-existing-selectors/)
- [Preserve Helm-compatible labels](https://kix.run/docs/how-to/adopt-existing-resources/preserve-helm-compatible-labels/)
- [Shadow a flavor-provided import with a managed package](https://kix.run/docs/how-to/adopt-existing-resources/shadow-a-flavor-provided-import-with-a-managed-package/)
- [Take ownership of Helm-managed resources](https://kix.run/docs/how-to/adopt-existing-resources/take-ownership-of-helm-managed-resources/)
- [Take ownership of kubectl-managed resources](https://kix.run/docs/how-to/adopt-existing-resources/take-ownership-of-kubectl-managed-resources/)
- [Use Helm charts through the Kix Helm bridge](https://kix.run/docs/how-to/adopt-existing-resources/use-helm-charts-through-the-kix-helm-bridge/)

### Platform capabilities

- [Add TLS through a cluster issuer](https://kix.run/docs/how-to/platform-capabilities/add-tls-through-a-cluster-issuer/)
- [Auto-monitor a service](https://kix.run/docs/how-to/platform-capabilities/auto-monitor-a-service/)
- [Configure storage classes and PVCs](https://kix.run/docs/how-to/platform-capabilities/configure-storage-classes-and-pvcs/)
- [Declare platform intents for non-Kix-managed pods](https://kix.run/docs/how-to/platform-capabilities/declare-platform-intents-for-non-kix-managed-pods/)
- [Enable generated network policy](https://kix.run/docs/how-to/platform-capabilities/enable-generated-network-policy/)
- [Expose a service through Cloudflare Tunnel](https://kix.run/docs/how-to/platform-capabilities/expose-a-service-through-cloudflare-tunnel/)
- [Expose a service with Gateway API](https://kix.run/docs/how-to/platform-capabilities/expose-a-service-with-gateway-api/)
- [Expose a service with Ingress](https://kix.run/docs/how-to/platform-capabilities/expose-a-service-with-ingress/)
- [Mount node-local storage with `hostPath`](https://kix.run/docs/how-to/platform-capabilities/mount-node-local-storage-with-hostpath/)
- [Set the cluster availability level](https://kix.run/docs/how-to/platform-capabilities/set-the-cluster-availability-level/)
- [Use externally managed secrets](https://kix.run/docs/how-to/platform-capabilities/use-externally-managed-secrets/)
- [Use Kix-managed secrets](https://kix.run/docs/how-to/platform-capabilities/use-kix-managed-secrets/)
- [Use SOPS-backed secrets](https://kix.run/docs/how-to/platform-capabilities/use-sops-backed-secrets-if-production-ready/)

### Policy, CI, and compliance

- [Add scorecard rules](https://kix.run/docs/how-to/policy-ci-and-compliance/add-scorecard-rules/)
- [Attest a deployment from its cluster receipt](https://kix.run/docs/how-to/policy-ci-and-compliance/attest-a-deployment-from-its-cluster-receipt/)
- [Disable scorecard rules](https://kix.run/docs/how-to/policy-ci-and-compliance/disable-scorecard-rules/)
- [Fail the build on scorecard findings](https://kix.run/docs/how-to/policy-ci-and-compliance/fail-the-build-on-scorecard-findings/)
- [Generate a CycloneDX SBOM](https://kix.run/docs/how-to/policy-ci-and-compliance/generate-a-cyclonedx-sbom/)
- [Generate an audit bundle](https://kix.run/docs/how-to/policy-ci-and-compliance/generate-an-audit-bundle/)
- [Generate PR-review markdown from `kix diff`](https://kix.run/docs/how-to/policy-ci-and-compliance/generate-pr-review-markdown-from-kix-diff/)
- [Generate SLSA provenance](https://kix.run/docs/how-to/policy-ci-and-compliance/generate-slsa-provenance/)
- [Override scorecard severity](https://kix.run/docs/how-to/policy-ci-and-compliance/override-scorecard-severity/)
- [Run `kix check --sarif` in CI](https://kix.run/docs/how-to/policy-ci-and-compliance/run-kix-check-sarif-in-ci/)
- [Save and diff snapshots for offline CI](https://kix.run/docs/how-to/policy-ci-and-compliance/save-and-diff-snapshots-for-offline-ci/)

### Package task guides

- [Configure cert-manager issuers](https://kix.run/docs/how-to/package-task-guides/configure-cert-manager-issuers/)
- [Deploy StackGres](https://kix.run/docs/how-to/package-task-guides/deploy-stackgres/)
- [Deploy Valkey / Redis](https://kix.run/docs/how-to/package-task-guides/deploy-valkey-redis/)
- [Deploy Velero](https://kix.run/docs/how-to/package-task-guides/deploy-velero/)
- [Install Cilium / network policy support](https://kix.run/docs/how-to/package-task-guides/install-cilium-network-policy-support/)
- [Install Envoy Gateway](https://kix.run/docs/how-to/package-task-guides/install-envoy-gateway/)
- [Install ingress-nginx](https://kix.run/docs/how-to/package-task-guides/install-ingress-nginx/)
- [Install Mayastor](https://kix.run/docs/how-to/package-task-guides/install-mayastor/)
- [Install the monitoring stack](https://kix.run/docs/how-to/package-task-guides/install-the-monitoring-stack/)
- [Install the VictoriaMetrics HA monitoring stack](https://kix.run/docs/how-to/package-task-guides/install-the-victoriametrics-ha-monitoring-stack/)
- [Provision persistent storage](https://kix.run/docs/how-to/package-task-guides/provision-persistent-storage/)
- [Publish DNS records with external-dns](https://kix.run/docs/how-to/package-task-guides/publish-dns-records-with-external-dns/)

## Reference

### Core reference

- [Annotations, CRDs, and receipts](https://kix.run/docs/reference/annotations-crds-and-receipts/): How Kix records resource dependencies, field ownership, and deployment history using annotations and custom resources.
- [Cluster configuration](https://kix.run/docs/reference/cluster-configuration/): Cluster-wide settings passed to kix.
- [Composition helpers](https://kix.run/docs/reference/composition-helpers/): Helper functions on the kix argument for wiring environment variables, mounts, Services, routes, and monitoring.
- [Dependency contracts](https://kix.run/docs/reference/dependency-contracts/): Field schemas, credential rules, and validation helpers for Kix dependency contracts (kix.
- [Flavors and capabilities](https://kix.run/docs/reference/flavors-and-capabilities/): Built-in provider profiles that tell Kix what your Kubernetes distribution or cloud provider already supplies.
- [Helm and imports](https://kix.run/docs/reference/helm-and-imports/): How to wrap upstream Helm charts as Kix packages and declare external or pre-installed services with kix.
- [Instances and composition](https://kix.run/docs/reference/instances-and-composition/): How to place packages into namespaces, wire dependencies between them, and compose multi-environment clusters.
- [kix.toml](https://kix.run/docs/reference/kix-toml/): Project configuration file that names the Kix version a project uses and chooses whether Kix evaluates it with the Kix runtime or the machine's Nix installation.
- [Package anatomy](https://kix.run/docs/reference/package-anatomy/): The structure of a Kix package file, how it declares options, and how it returns Kubernetes resources.
- [Resources and out](https://kix.run/docs/reference/resources-and-out/): How scope builders create Kubernetes resources and expose.
- [Scorecard and rules](https://kix.run/docs/reference/scorecard-and-rules/): How to write and configure build-time policy rules, plus the complete catalog of built-in scorecard checks.
- [Secrets, CRDs, and RBAC](https://kix.run/docs/reference/secrets-crds-and-rbac/): Dedicated builders for Secrets, CustomResourceDefinitions, and RBAC permissions that catch mistakes at build time.
- [Validation checks](https://kix.run/docs/reference/validation-checks/): The 24 always-on checks that verify cross-resource references, selectors, and CRD ordering on every build.

### CLI

- [API server retries and request limits](https://kix.run/docs/reference/cli/api-server-transport/)
- [`build`](https://kix.run/docs/reference/cli/build/)
- [`check`](https://kix.run/docs/reference/cli/check/)
- [`completions`](https://kix.run/docs/reference/cli/completions/)
- [`compliance` commands](https://kix.run/docs/reference/cli/compliance-commands/)
- [`deploy` / `apply`](https://kix.run/docs/reference/cli/deploy-apply/)
- [`diff`](https://kix.run/docs/reference/cli/diff/)
- [`doctor`](https://kix.run/docs/reference/cli/doctor/)
- [`drift`](https://kix.run/docs/reference/cli/drift/)
- [Eval cache behavior](https://kix.run/docs/reference/cli/eval-cache-behavior/)
- [Exit codes](https://kix.run/docs/reference/cli/exit-codes/)
- [`export`](https://kix.run/docs/reference/cli/export/)
- [`gc`](https://kix.run/docs/reference/cli/gc/)
- [Global flags](https://kix.run/docs/reference/cli/global-flags/)
- [`graph`](https://kix.run/docs/reference/cli/graph/)
- [`health`](https://kix.run/docs/reference/cli/health/)
- [`images`](https://kix.run/docs/reference/cli/images/)
- [`inspect`](https://kix.run/docs/reference/cli/inspect/)
- [`lib`](https://kix.run/docs/reference/cli/lib/)
- [`list`](https://kix.run/docs/reference/cli/list/)
- [`logs`](https://kix.run/docs/reference/cli/logs/)
- [`migrate`](https://kix.run/docs/reference/cli/migrate/)
- [Operator mode](https://kix.run/docs/reference/cli/operator-mode/)
- [Output formats](https://kix.run/docs/reference/cli/output-formats/)
- [`pf`](https://kix.run/docs/reference/cli/pf/)
- [`pin`](https://kix.run/docs/reference/cli/pin/)
- [`plan`](https://kix.run/docs/reference/cli/plan/)
- [`rollback`](https://kix.run/docs/reference/cli/rollback/)
- [`self`](https://kix.run/docs/reference/cli/self/)
- [`snapshot`](https://kix.run/docs/reference/cli/snapshot/)
- [`status`](https://kix.run/docs/reference/cli/status/)
- [`upgrade`](https://kix.run/docs/reference/cli/upgrade/)

### Package catalog

- [cert-manager](https://kix.run/docs/reference/package-catalog/cert-manager/)
- [cilium](https://kix.run/docs/reference/package-catalog/cilium/)
- [echo-server](https://kix.run/docs/reference/package-catalog/echo-server/)

## Explanation

- [Availability levels](https://kix.run/docs/explanation/availability-levels/)
- [Dependency contracts](https://kix.run/docs/explanation/dependency-contracts/)
- [Helm integration](https://kix.run/docs/explanation/helm-integration/)
- [Network policy](https://kix.run/docs/explanation/network-policy/)
- [Packages and clusters](https://kix.run/docs/explanation/packages-and-clusters/)
- [Scorecard levels](https://kix.run/docs/explanation/scorecard-levels/)
- [Server-side apply and drift](https://kix.run/docs/explanation/server-side-apply-and-drift/)
- [The dependency graph](https://kix.run/docs/explanation/the-dependency-graph/)