Kubernetes GitOps with Nix and Argo CD

nixidy lets you describe everything running in your Kubernetes clusters with Nix and the NixOS module system. It renders your configuration to plain YAML manifests, which you commit to a Git repository for Argo CD to deploy.

Why nixidy?#

Kubernetes configuration tends to sprawl. Helm charts need ever-growing value overrides, Kustomize overlays repeat themselves, and raw YAML is copied between environments until nobody knows which copy is right. Reviewing what a change actually does to a cluster is hard.

nixidy brings the tools NixOS uses to manage a whole operating system to Kubernetes:

One language for everything. Your own resources, Helm charts and Kustomize applications are configured in the same place, with the same module system.
Typed resources. Every Kubernetes resource, and the CRDs you generate options for, is checked when you build, before anything reaches a cluster.
Reusable modules. Share a base configuration between environments and override only what differs.
Reviewable output. Every change is a diff of plain YAML in a pull request, so you see exactly what Argo CD will apply.
Reproducible builds. Charts and sources are pinned, so the same configuration always renders the same manifests.

How It Works#

Describe an application with Nix:

env/prod.nix

{
  applications.demo = {
    namespace = "demo";
    createNamespace = true;

    resources = {
      deployments.nginx.spec = {
        replicas = 3;
        selector.matchLabels.app = "nginx";
        template = {
          metadata.labels.app = "nginx";
          spec.containers.nginx = {
            image = "nginx:1.25.1";
            ports.http.containerPort = 80;
          };
        };
      };

      services.nginx.spec = {
        selector.app = "nginx";
        ports.http.port = 80;
      };
    };
  };
}

Build the environment:

nixidy build .#prod

And get plain manifests, including an Argo CD Application for each application:

result/
├── apps/
│   └── Application-demo.yaml
└── demo/
    ├── Deployment-nginx.yaml
    ├── Namespace-demo.yaml
    └── Service-nginx.yaml

Commit the manifests to your repository and Argo CD deploys them. This is the rendered manifests pattern: what's in Git is exactly what runs in the cluster.

Explore the Guides#

Getting Started: Set up a project with a flake, define your first environment and bootstrap Argo CD.
Helm Charts: Render Helm charts as part of an application and patch the resources they produce. nixhelm provides a large collection of charts ready to use.
Typed Resources: Use the typed options for Kubernetes resources, include existing YAML, and generate options from any CRD.
Templates: Package common patterns, such as a deployment with a service, into templates with their own options.
Git Strategies: Keep environments in a single repository, in separate branches or in separate repositories.
GitHub Actions: Build environments and push the rendered manifests from CI.
Transformers, Object Transforms and Post-processing: Modify resources from any source, such as Helm charts, before they're written, and process the rendered files.
Directly Apply Manifests: Skip GitOps and apply an environment to a cluster with nixidy apply.
Assertions & Warnings: Validate your configuration at build time, including references between resources.

The reference documents the command line interface, the library functions and every configuration option.

Learn More#

arnarg/cluster is a real-world cluster configured with nixidy.
Introduction to nixidy is a tutorial series about nixidy.
Questions and ideas are welcome in GitHub Discussions, and bugs in GitHub Issues.
Interested in contributing? The architecture guide explains how nixidy works internally.

Edit this page