nixidy

Nixidy configuration is defined in environment modules (e.g., env/dev.nix). You define where manifests should be stored and what applications to build.

Target Configuration

Use nixidy.target to specify the Git repository, branch, and the root path where generated manifests will be stored.

• nixidy.target.repository: The Git URL for your manifests.
• nixidy.target.branch: The target branch (e.g., main).
• nixidy.target.rootPath: The directory within the repository where manifests are written.

Application Configuration

Use applications.<name> to define a Kubernetes application.

• namespace: The Kubernetes namespace for the application.
• createNamespace: Boolean to automatically create the namespace.
• resources: A set of Kubernetes resources (e.g., deployments, services, configMaps, statefulSets) defined using their spec structure.

{
  # Target configuration
  nixidy.target.repository = "https://github.com/YOUR_USERNAME/my-cluster.git";
  nixidy.target.branch = "main";
  nixidy.target.rootPath = "./manifests/dev";

  # Define an application
  applications.nginx = {
    namespace = "nginx";
    createNamespace = true;

    resources = {
      deployments.nginx.spec = {
        replicas = 2;
        # ... rest of spec
      };
      services.nginx.spec = {
        # ... rest of spec
      };
    };
  };
}

Nixidy provides strongly-typed options for Kubernetes resources. While you can define resources using their full GVK (Group, Version, Kind) path under applications.<applicationName>.resources.<group>.<version>.<kind>, Nixidy also provides convenient camelCase plural aliases for common resources.

Path Formats:

• Full Path: applications.<applicationName>.resources.<group>.<version>.<kind>
• Alias Path: applications.<applicationName>.resources.<attrName> (where <attrName> is the camelCase plural of the Kind).

Examples:

• resources.core.v1.Service can be accessed via resources.services
• resources."networking.k8s.io".v1.NetworkPolicy can be accessed via resources.networkPolicies

Note: If a resource does not have typed options defined, it cannot be patched by Nixidy and will instead be passed directly to the application output.

applications.my-app = {
  resources.services.my-service = { ... }; # Using full path
  resources.services.my-service = { ... }; # Using alias
};

Nixidy allows you to define Kubernetes resources using Nix modules. This approach provides strong typing, composability, and reproducibility.

1. Define: Write your Kubernetes resources (Deployments, Services, etc.) in Nix files using the applications.<name>.resources structure.
2. Build: Use the nixidy build command to generate plain, reviewable YAML manifests.
3. Deploy: Commit the generated YAML to your repository for Argo CD to pick up, or use nixidy apply for direct deployment.

{
  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;
      };
    };
  };
}

Warnings are messages printed during evaluation that do not fail the build. Use warnings for deprecation notices, unusual configurations, or reminders that do not render the configuration invalid.

Warnings can be defined in three ways:

1. Per-application (conditional): Using applications.<name>.warnings with a when condition.
2. Per-application (unconditional): Using a shorthand string in applications.<name>.warnings.
3. Global: Using nixidy.warnings for system-wide notices.

# Conditional per-application warning
applications.my-app = {
  warnings = [
    {
      when = config.applications.my-app.createNamespace == false;
      message = "Not creating namespace for my-app, make sure it exists on the cluster";
    }
  ];
};

# Unconditional per-application warning (shorthand)
applications.my-app = {
  warnings = [ "my-app is using a deprecated configuration, see the docs for migration steps" ];
};

# Global warning
nixidy.warnings = [
  {
    when = config.nixidy.target.branch != "main";
    message = "Target branch is not 'main', make sure this is intentional";
  }
];

Assertions are conditions that must be true. If an assertion fails, the Nixidy build will fail with a descriptive error message. Use assertions for invalid configurations, such as missing required resources or conflicting settings, that should prevent a build from proceeding.

Assertions can be defined at two levels:

1. Per-application: Defined under applications.<name>.assertions to validate settings specific to that application.
2. Global: Defined under nixidy.assertions to validate invariants that span multiple applications or the entire configuration.

# Per-application assertion example
applications.my-app = {
  assertions = [
    {
      assertion = builtins.length (builtins.attrNames config.applications.my-app.resources.deployments) > 0;
      message = "my-app must have at least one deployment";
    }
  ];
};

# Global assertion example
nixidy.assertions = [
  {
    assertion = config.applications ? app-a && config.applications ? app-b;
    message = "Both app-a and app-b must be defined";
  }
];

Nixidy organizes all Kubernetes resources using a Group/Version/Kind (GVK) hierarchy. This allows for strongly-typed resource definitions.

Full GVK Path

You can access resources using their full path:

resources.<group>.<version>.<kind>.<name> = { ... };

# Examples:
resources.core.v1.ConfigMap.my-config = { ... };
resources.apps.v1.Deployment.nginx = { ... };
resources."networking.k8s.io".v1.Ingress.main = { ... };

Aliases

For convenience, Nixidy provides aliases to common resources:

• resources.configMaps.<name> maps to core.v1.ConfigMap
• resources.deployments.<name> maps to apps.v1.Deployment
• resources.ingresses.<name> maps to networking.k8s.io.v1.Ingress

resources.core.v1.ConfigMap.my-config = { ... };
resources.apps.v1.Deployment.nginx = { ... };
resources."networking.k8s.io".v1.Ingress.main = { ... };

# Using aliases:
resources.configMaps.my-config = { ... };
resources.deployments.nginx = { ... };
resources.ingresses.main = { ... };