Skip to content
kix /docs
Install the CLI

Tutorials

These tutorials form a sequential learning path. Each lesson builds on the previous one, introducing one concept at a time against runnable examples in the kix-examples repository. You only need basic familiarity with Kubernetes objects and kubectl to begin; Nix concepts are introduced as needed.

Part 1: Cluster fundamentals

Section titled “Part 1: Cluster fundamentals”

Start here to understand what a Kix repository looks like, deploy your first cluster to kind, and connect two services.

  1. 01. Orientation: what Kix is and why it exists: Learn the core vocabulary (packages, instances, config, deps, out, scope, and root) before running commands.
  2. 02. Local setup and first run: Clone kix-examples, create a local kind cluster, deploy 02-hello-world, and make your first configuration edit.
  3. 03. Project files and flake entry point: Read flake.nix and cluster.nix to see how mkFlake and kix.buildCluster expose clusters to the CLI.
  4. 04. First cluster from scratch: Write a new cluster file in your checkout, register it in flake.nix, and deploy an echo-server instance.
  5. 05. Basic graph and deploy loop: Practice the day-to-day workflow with kix check, kix build, kix diff, kix deploy, kix status, and kix graph.
  6. 06. Use a local package and service-to-service dependency: Import a local reverse-proxy package and see how it consumes a backend Service’s out values.

Part 2: Package authoring and policy

Section titled “Part 2: Package authoring and policy”

Continue here to read and customize packages, wire dependencies across namespaces, integrate existing cluster infrastructure, and enforce policy at build time.

  1. 07. Package anatomy and safe resource composition: Look inside the reverse-proxy package to see how scope.mkDeployment, kix.withMounts, kix.service.fromWorkload, and self assemble resources safely.
  2. 08. Basic dependency resolution and namespace boundaries: Place the gateway and backend in separate namespaces and connect them explicitly with deps and ref.
  3. 09. Typed package options: Declare validated configuration options with lib.mkOption, read config inside build, and catch invalid settings before deploy.
  4. 10. Reuse packages across instances and environments: Instantiate the same package multiple times with distinct config and deps while scope keeps resource names and selectors collision-free.
  5. 11. Flavors, roles, and imports: Connect Kix packages to pre-existing cluster services using cluster flavors, infrastructure roles, and kix.mkImport.
  6. 12. Scorecards and compile-time policy: Enable built-in scorecard rules and write custom package-level and cluster-level rules that fail evaluation when policy is broken.