Skip to content

Architectural Overview#

LLM Generated

This entire document is generated by an LLM by feeding the output of files-to-prompt to Gemini.

Nixidy is a tool designed to manage Kubernetes clusters declaratively using the Nix package manager and its language. It integrates with Argo CD by generating plain Kubernetes YAML manifests, adhering to the GitOps philosophy and the "Rendered Manifests Pattern".

Core Concepts#

  • Declarative Configuration with Nix: Users define their entire Kubernetes cluster state, including applications, resources, Helm charts, and Kustomize overlays, within Nix expressions.
  • NixOS Module System: Nixidy leverages a module system similar to NixOS, allowing for structured, modular, and recursively merged configurations. This provides strong typing and discoverability for Kubernetes resource options.
  • Manifest Generation: The primary output of Nixidy is a set of plain Kubernetes YAML manifests and ArgoCD Application custom resources. These are intended to be committed to a Git repository.
  • Argo CD Integration: Nixidy generates manifests in a structure that is easily consumable by Argo CD, typically following an "App of Apps" pattern for bootstrapping.
  • No Runtime Dependencies on Nix in Cluster: Nixidy is a build-time tool. The generated YAMLs are standard Kubernetes manifests that Argo CD can deploy without any Nix-specific components in the cluster.
  • Flake-centric (but supports flake-less): While Nixidy can be used without Nix Flakes, its primary development and examples lean towards a Flake-based setup for managing dependencies and outputs.

Key Architectural Components#

Nixidy's architecture can be broken down into several key areas:

  1. User Configuration (Nix Files):

    • Entrypoint: Typically a flake.nix (for Flakes) or a default.nix (for non-Flakes).
    • Environment Definition: Users define one or more "environments" (e.g., dev, prod) using nixidy.lib.mkEnv or nixidy.lib.mkEnvs. Each environment is a collection of Nixidy modules.
      • (Document 6: make-env.nix, Document 13: Getting Started)
    • Application Modules: Within these environment modules, users define applications.<appName>.* options to describe their desired state. This includes:
      • Kubernetes resources directly in Nix syntax (applications.<appName>.resources).
      • Helm chart releases (applications.<appName>.helm.releases).
      • Kustomize applications (applications.<appName>.kustomize.applications).
      • Raw YAML strings (applications.<appName>.yamls).
      • (Document 2: README example, Document 27: applications.nix, Document 32: modules/applications/default.nix)
    • Nixidy Library (lib.*): Nixidy provides a set of helper functions (e.g., lib.helm.downloadHelmChart, lib.kube.fromYAML) available to user modules for tasks like fetching charts or parsing YAML.
      • (Document 22: lib/default.nix, Document 23: lib/helm.nix, Document 24: lib/kube.nix, Document 25: lib/kustomize.nix)

  2. Nixidy Core Engine:

    • Module System: Located primarily in ./modules.
      • modules/default.nix (Document 29): Orchestrates the evaluation of user and internal Nixidy modules. It injects an extended lib (Nixpkgs lib + Nixidy lib) and other special arguments.
      • modules/nixidy.nix (Document 31): Defines global nixidy.* configurations like target Git repository details, default sync policies for ArgoCD applications, and App of Apps settings.
      • modules/applications/*: A collection of modules that define how applications are processed:
        • applications.nix (Document 27): Defines the top-level applications option.
        • default.nix (Document 32): Defines the submodule for a single application, collecting all resources (from Nix, Helm, Kustomize, YAMLs) into config.objects.
        • helm.nix (Document 33), kustomize.nix (Document 34), yamls.nix (Document 37): Handle the specifics of rendering Helm charts, Kustomize overlays, and parsing raw YAMLs, respectively. They utilize functions from nixidy.lib.
        • namespaced.nix (Document 36): Sets default namespaces for namespaced Kubernetes resources.
    • Build Logic (modules/build.nix, Document 28):
      • Takes the evaluated config.applications.*.objects (a list of Nix attribute sets representing Kubernetes resources).
      • Generates the final output directory structure:
        • A directory for each application (e.g., result/demo/).
        • YAML files for each resource within its application directory (e.g., Deployment-nginx.yaml). Uses yq-go for pretty-printing YAML.
        • An apps/ directory containing ArgoCD Application CRs for each user-defined application.
      • Produces Nix derivations for different purposes:
        • environmentPackage: Contains all generated manifests for an environment.
        • activationPackage: Contains environmentPackage plus an activate script (for nixidy switch).
        • bootstrapPackage: Contains the "App of Apps" ArgoCD Application manifest (for nixidy bootstrap).

  3. Nixidy CLI (nixidy/nixidy, Document 42):

    • A Bash script that acts as a user-friendly wrapper around underlying nix commands (nix build, nix eval, nix-build, nix-instantiate).
    • Commands:
      • nixidy build <env>: Builds the environmentPackage.
      • nixidy switch <env>: Builds the activationPackage and runs its activate script to sync manifests to the local filesystem (defined by nixidy.target.rootPath).
      • nixidy info <env>: Displays metadata about the specified environment (repository, branch).
      • nixidy bootstrap <env>: Outputs the "App of Apps" ArgoCD Application manifest for initial cluster bootstrapping.
    • Handles both Flake-based and traditional Nix (attribute-based) invocations.
      • (Document 43: nixidy.nix package definition)

  4. External Dependencies (Managed by Nix):

    • Nixpkgs: The standard Nix package collection, providing tools like bash, jq, kubectl, yq-go, etc.
      • (Document 3: default.nix top-level)
    • Kubenix:
      • Primarily used for its pre-generated Nix modules that provide typed options for standard Kubernetes resources (e.g., Deployment, Service). Nixidy imports these options.
      • Nixidy's CRD generator is also heavily inspired by Kubenix's.
      • (Document 2: Special Thanks, Document 3, Document 5, Document 10, Document 29)
    • Nix-Kube-Generators (kubelib):
      • Provides the core Nix functions for rendering Helm charts and Kustomize overlays. Nixidy's lib.helm and lib.kustomize often wrap or re-export functions from nix-kube-generators.
      • (Document 2: Special Thanks, Document 3, Document 5, Document 22, Document 23, Document 25)

  5. CRD and Schema Generation:

    • fromCRD Generator (pkgs/generators/crd.nix, Document 44):
      • Allows users to generate Nixidy-compatible Nix modules from Kubernetes Custom Resource Definition (CRD) YAML files.
      • Uses crd2jsonschema.py (Document 45) to preprocess CRDs into a JSON schema format.
      • Then, jsonschema.nix (Document 47) converts this JSON schema into Nix options.
    • Generated Modules: The output is a Nix file (e.g., modules/generated/argocd.nix for ArgoCD CRDs, Document 38) that can be imported via nixidy.applicationImports to provide typed options for these CRDs.
      • (Document 18: Typed Resource Options)

  6. Documentation System (docs/):

    • Uses MkDocs with the Material theme.
      • (Document 12: docs.nix)
    • Documentation for configuration options, library functions, and user guides are generated/written.
    • Option search is powered by NuschtOS.
      • (Document 8, 9, 10, 11)

  7. Testing Framework (modules/testing/, tests/):

    • Module Tests (modules/testing/default.nix, eval.nix, Documents 39, 40): A system for defining and running tests against Nixidy modules. Assertions are made on the evaluated Nix configuration.
    • Lib Tests (lib/tests.nix, Document 26): Unit tests for functions in nixidy.lib using nix-unit.
    • Example tests are in tests/ (Documents 50-62, 70-72).

  8. GitHub Actions (actions/):

    • Provides reusable GitHub Actions for CI/CD.
      • actions/build/action.yml (Document 49): Wraps nixidy build.
      • actions/switch/action.yml (Document 48): Wraps nixidy switch.
      • (Document 15: GitHub Actions user guide)

Workflow / Data Flow#

  1. Definition: The user defines their cluster configuration as Nix expressions using nixidy.lib.mkEnv and the Nixidy module system. This includes applications, their resources (Kubernetes objects, Helm charts, Kustomize overlays), namespaces, and ArgoCD settings.
  2. Evaluation & Processing (Triggered by nixidy CLI):
    • The Nixidy CLI invokes Nix to evaluate the user's configuration.
    • Nixidy's core modules process the defined applications:
      • Helm charts are templated via nix-kube-generators.
      • Kustomize overlays are built using kubectl kustomize (via nix-kube-generators).
      • Plain Nix resources and raw YAMLs are parsed.
      • Resource options are validated against types (from Kubenix and generated CRD modules).
      • Transformers (lib.kube.*) can be applied to modify rendered manifests.
  3. Manifest Generation:
    • The processed resources (now Nix attribute sets) are converted into Kubernetes YAML strings.
    • yq-go is used to format these YAMLs.
    • The manifests are organized into a directory structure:
      • A root directory for the environment (e.g., result/ or specified by nixidy.target.rootPath).
      • Subdirectories for each application (e.g., result/demo/).
      • An apps/ subdirectory containing ArgoCD Application CRs that point to the respective application manifest directories.
  4. Deployment (GitOps via Argo CD):
    • The generated manifests in the result/ directory (or the path configured with nixidy switch) are committed to a Git repository.
    • Argo CD monitors this Git repository (or specific paths/branches within it).
    • Argo CD applies the "App of Apps" manifest from the apps/ directory, which in turn manages the deployment of individual applications from their respective manifest directories.

Architectural Diagram (Conceptual)#

graph LR
    subgraph User Input
        A[Nix Configuration] -- Defines --> EnvSetup
    end

    subgraph Nixidy Core
        EnvSetup[nixidy.lib.mkEnv/.mkEnvs] -- Loads --> NixidyModules[Nixidy Internal Modules]
        NixidyModules -- Uses --> NixidyLib[Nixidy Library]
        NixidyLib -- Wraps --> Kubelib[nix-kube-generators]
        NixidyModules -- Uses --> KubenixTypes[Kubenix Resource Types]
        NixidyModules -- Uses --> GeneratedCRDTypes[Generated CRD Types]

        subgraph Resource Processing
            direction LR
            Helm[Helm Charts] --> NixidyModules
            Kustomize[Kustomize Overlays] --> NixidyModules
            NixResources[Direct Nix Resources] --> NixidyModules
            YAMLStrings[Raw YAML Strings] --> NixidyModules
        end

        NixidyModules -- Processes & Merges --> AppConfig[Evaluated Application Config]
        AppConfig -- Input to --> BuildLogic[Build Logic]
        BuildLogic -- Generates --> OutputPkgs["environmentPackage <br/> activationPackage <br/> bootstrapPackage"]
    end

    subgraph Nixidy CLI
        CLI_Build["nixidy build <env>"] -- Triggers --> OutputPkgs
        CLI_Switch["nixidy switch <env>"] -- Triggers & Executes --> ActivateScript{activate script}
        CLI_Info["nixidy info <env>"] -- Reads --> EnvSetup
        CLI_Bootstrap["nixidy bootstrap <env>"] -- Outputs --> AppOfAppsYAML((App of Apps YAML))

        OutputPkgs --> ResultDir[./result]
        ActivateScript -- Rsyncs --> ResultDir
        ResultDir --> ArgoCD[Argo CD]
    end

    subgraph Tooling & Extensibility
        CRDs[CRD YAMLs] --> CRDGen[CRD Generator]
        CRDGen --> GeneratedCRDTypes
        UserDocs[User Guides] --> DocsGen[Documentation Generator]
        DocsGen --> DocsSite((Static Docs Site))
        NixidyModules --> Tests[Testing Framework]
        GitHubActions[GitHub Actions] -- Wraps --> NixidyCLI[Nixidy CLI Commands]
    end

    A --> NixidyCLI

This overview highlights Nixidy's reliance on the Nix ecosystem for configuration management and its role in producing standard, GitOps-friendly YAML manifests for Kubernetes deployment via Argo CD. Its modular design, coupled with dependencies like Kubenix and nix-kube-generators, allows it to offer a typed and declarative approach to Kubernetes management.