01. Orientation: what Kix is and why it exists

This first tutorial is a map. You won’t write code yet. The goal is to give you enough vocabulary that the next tutorial feels like running a small system, not copying unfamiliar Nix into a terminal.

Prerequisites

You only need basic Kubernetes familiarity for now: namespaces, Deployments, Services, Pods, and kubectl. You don’t need to know Nix yet.

What Kix Is

Kix is a way to build, connect, check, explain, and deploy Kubernetes systems from one explicit model of the cluster.

The output is still Kubernetes manifests. Kix does not replace the Kubernetes API server, kubectl, or the objects you already know. It gives you a more structured way to build those objects, connect them, check them, and deploy them before they reach the cluster.

A small Kix cluster usually has:

• a flake.nix that exposes one or more named clusters;
• a cluster.nix that says which packages are installed where;
• package definitions that know how to produce Kubernetes resources;
• the kix CLI, which renders, checks, diffs, deploys, and inspects the result.

You can think of Kix as sitting one step before YAML: it builds the YAML, keeps track of relationships while doing so, and gives the CLI enough structure to operate on the result.

Explanation

See Kix as a strict Kubernetes superset for the design argument behind “the output is still Kubernetes.”

Why It Exists

Kubernetes teams often accumulate layers: YAML for resources, Helm for packaging, Kustomize for patches, CDK8s for code generation, Argo CD or Flux for sync, and Kargo for promotion. Each tool can be useful, but the stack can make a simple question feel scattered: what should this cluster look like now?

Kix is trying to make the graph explicit enough that tools can use it. That is where the interesting parts start.

Know Before Deploy

Evaluate, check, diff, and inspect the cluster before anything touches the Kubernetes API server.

Derive Network Policy

Use declared service relationships to generate network policy instead of hand-maintaining it beside the app graph.

Prove Ownership And Policy

Track which package owns each manifest, then run checks against the rendered system before it ships.

See Blast Radius

Ask what depends on the thing you are changing before the change lands in a real cluster.

Once Kix has the graph, it can do more than render YAML. It can use the same model for deploy order, network policy, ownership, policy checks, diffs, and change impact.

Kix can coexist with the tools you already use. It gets more powerful as you use it for more of the cluster, because more of the system becomes visible to the same graph.

Explanation

See How Kix compares with Helm, Kustomize, CDK8s, GitOps controllers, and raw YAML when you want a deeper comparison.

The First Mental Model

These words show up throughout the tutorials. For now, keep the definitions small.

Package

A reusable Kubernetes blueprint: “how to build an echo server”, “how to build ingress-nginx”, and so on.

Instance

One installed copy of a package in a cluster: run this package here, with this name and config.

Config

The values passed into an instance, such as an HTTP response message, image tag, storage size, or backup setting.

Deps

Other instances this instance needs. For now, read deps as “the wiring between instances.”

Out

The public information Kix exposes after building something: names, ports, DNS names, selectors, and similar values.

Scope

The context Kix gives a package while it builds resources: instance name, namespace, helper functions, labels, and cluster facts.

Root

The main resource for a package instance. For a service-shaped package, this is usually the Service another workload should talk to.

That gives you the core sentence:

A cluster installs package instances, configures them, wires deps between them, and each package uses its scope to build Kubernetes resources with a useful root and out surface.

You do not need to memorize this. The next tutorial makes the first half of it visible with one tiny service.

Who Kix Is For

Kix is mostly used by three overlapping roles.

App maintainer

Package a service once, expose useful config, and avoid copying Kubernetes boilerplate into every environment.

Platform team

Publish shared packages and cluster defaults: ingress, cert-manager, monitoring, storage, policy, and other platform capabilities.

Cluster operator

Decide what is installed in a real cluster, review diffs, deploy changes, roll back activations, and handle migration work.

In a small team one person may do all three. Kix still uses the separation because it keeps package code, cluster composition, and operations from turning into one large YAML pile.

How To Use These Docs

The docs are split by job.

Tutorials are the path you are on now. They are lessons, meant to be read in order. They introduce one new idea at a time.

How-to guides are recipes. Use them when you already know the model and need the steps for a task, like deploying to kind or using kix pf.

Reference is for exact command flags, schema fields, helper names, and defaults.

Explanation is for design reasoning and tradeoffs.

When a tutorial links to a how-to, reference page, or explanation page, it is usually optional background. Stay on the tutorial path when you want the guided route.

What Comes Next

You now have the names for the pieces. In the next tutorial you will run the smallest useful example: one Kix package instance deployed to a local kind cluster, then reached through kix pf and curl.