Cluster Options

Options for configuring individual clusters within a lab, including Kubernetes settings, provisioners, phases, and authentication.

All options are under lab.clusters.<name>.

`cluster.certSANs`

Extra Subject Alternative Names added to CAPI cluster API server certificates. Includes 127.0.0.1 so kubeconfigs rewritten for host access work with valid TLS.

Type: list of string

Default:

[
  "127.0.0.1"
  "localhost"
]

Declared in: modules/lab/cluster/types.nix

`cluster.kubernetes.controlPlanes`

Number of control plane nodes

Type: positive integer, meaning >0

Default: 1

Declared in: modules/lab/cluster/types.nix

`cluster.kubernetes.distribution`

Kubernetes distribution to use

Type: one of "talos", "k3s", "k8s"

Default: "talos"

Declared in: modules/lab/cluster/types.nix

`cluster.kubernetes.version`

Kubernetes API version for type generation (e.g., ‘1.31’)

Type: string

Default: "1.31"

Declared in: modules/lab/cluster/types.nix

`cluster.kubernetes.workers`

Number of worker nodes

Type: unsigned integer, meaning >=0

Default: 1

Declared in: modules/lab/cluster/types.nix

`cluster.name`

Unique name for this cluster

Type: string

Example: "local"

Declared in: modules/lab/cluster/types.nix

`cluster.network.podSubnet`

Pod network CIDR

Type: string

Default: "10.244.0.0/16"

Declared in: modules/lab/cluster/types.nix

`cluster.network.serviceSubnet`

Service network CIDR

Type: string

Default: "10.96.0.0/12"

Declared in: modules/lab/cluster/types.nix

`cluster.out.phaseOrder`

Phase names sorted by deployment order

Type: list of string

Default: [ ]

Declared in: modules/lab/cluster/out.nix

`cluster.out.phases`

Computed phases with rendered manifest packages. Each entry has: order, dependsOn, keepResources, pruneStrategy, waitForReady, timeout, package (derivation).

Type: raw value

Default: { }

Declared in: modules/lab/cluster/out.nix

`cluster.out.sbom`

Software bill of materials

Type: attribute set

Default: { }

Declared in: modules/lab/cluster/out.nix

`cluster.out.topology`

Computed topology/network map

Type: attribute set

Default: { }

Declared in: modules/lab/cluster/out.nix

`cluster.provider`

Computed provider category (derived from cluster.provisioner)

Type: one of "docker", "crossplane", "external"

Declared in: modules/lab/cluster/types.nix

`cluster.provisioner`

How this cluster is provisioned:

k3d: k3s-in-Docker (local development)
talos: Talos-in-Docker (local development)
crossplane: Provisioned via Crossplane from another cluster
external: Pre-existing cluster, just configure it

Type: one of "k3d", "talos", "crossplane", "external"

Default: "k3d"

Declared in: modules/lab/cluster/types.nix

`cluster.ref.kubeContext`

Kubernetes context name for kubectl/velero/etc. Set by provisioner modules.

Type: string

Declared in: modules/lab/cluster/types.nix

`cluster.security.auditLogging.enable`

Enable Kubernetes API server audit logging. Provisioner-specific.

Type: boolean

Default: false

Declared in: modules/lab/cluster/types.nix

`cluster.security.networkPolicies.enable`

Generate default-deny NetworkPolicies for lab namespaces. Components add allow rules.

Type: boolean

Default: false

Declared in: modules/lab/cluster/types.nix

`cluster.security.podSecurity.default`

Default PSA level for lab namespaces. Components can override per-namespace.

Type: one of "restricted", "baseline", "privileged"

Default: "restricted"

Declared in: modules/lab/cluster/types.nix

`cluster.security.podSecurity.enable`

Apply Pod Security Admission labels to lab-managed namespaces

Type: boolean

Default: false

Declared in: modules/lab/cluster/types.nix

`cluster.security.podSecurity.namespaceOverrides`

Per-namespace PSA level overrides (e.g., kube-system = privileged)

Type: attribute set of (one of "restricted", "baseline", "privileged")

Default: { }

Declared in: modules/lab/cluster/types.nix

`cluster.talos.cniNone`

Disable built-in CNI (for Cilium)

Type: boolean

Default: true

Declared in: modules/lab/cluster/types.nix

`cluster.talos.kubeProxyDisabled`

Disable kube-proxy (for Cilium kube-proxy replacement)

Type: boolean

Default: true

Declared in: modules/lab/cluster/types.nix

`cluster.talos.version`

Talos version

Type: string

Default: "v1.13.0"

Declared in: modules/lab/cluster/types.nix

`compose`

This option has no description.

Type: attribute set of (attribute set)

Default: { }

Declared in: modules/lab/cluster

`databases.postgres`

This option has no description.

Type: attribute set of (attribute set)

Default: { }

Declared in: modules/lab/cluster

`databases.redis`

This option has no description.

Type: attribute set of (attribute set)

Default: { }

Declared in: modules/lab/cluster

`lifecycle.teardown`

Ordered teardown steps executed before cluster deprovisioning

Type: list of (submodule)

Default: [ ]

Declared in: modules/lab/cluster

`lifecycle.teardown.*.description`

This option has no description.

Type: string

Default: ""

Declared in: modules/lab/cluster

`lifecycle.teardown.*.name`

Step name for display

Type: string

Declared in: modules/lab/cluster

`lifecycle.teardown.*.order`

Execution order (lower = first)

Type: signed integer

Default: 0

Declared in: modules/lab/cluster

`lifecycle.teardown.*.package`

Script to execute for this step

Type: package

Declared in: modules/lab/cluster

`lifecycle.teardown.*.waitTimeout`

How long to wait for completion

Type: string

Default: "5m"

Declared in: modules/lab/cluster

`ops`

Operational commands contributed by components (auto-collected by lab.ops)

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/cluster

`ops.<name>.args`

Positional arguments

Type: list of (submodule)

Default: [ ]

Declared in: modules/lab/cluster

`ops.<name>.args.*.description`

This option has no description.

Type: string

Default: ""

Declared in: modules/lab/cluster

`ops.<name>.args.*.name`

This option has no description.

Type: string

Declared in: modules/lab/cluster

`ops.<name>.args.*.required`

This option has no description.

Type: boolean

Default: true

Declared in: modules/lab/cluster

`ops.<name>.category`

Subcommand group (e.g. ‘backup’, ‘database’)

Type: string

Default: "general"

Declared in: modules/lab/cluster

`ops.<name>.description`

This option has no description.

Type: string

Declared in: modules/lab/cluster

`ops.<name>.options`

Named options (flags) for this command

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/cluster

`ops.<name>.options.<name>.default`

This option has no description.

Type: null or string

Declared in: modules/lab/cluster

`ops.<name>.options.<name>.description`

This option has no description.

Type: string

Default: ""

Declared in: modules/lab/cluster

`ops.<name>.options.<name>.required`

This option has no description.

Type: boolean

Default: false

Declared in: modules/lab/cluster

`ops.<name>.options.<name>.type`

This option has no description.

Type: one of "string", "enum", "bool"

Default: "string"

Declared in: modules/lab/cluster

`ops.<name>.options.<name>.values`

Valid values for enum type

Type: list of string

Default: [ ]

Declared in: modules/lab/cluster

`ops.<name>.package`

This option has no description.

Type: package

Declared in: modules/lab/cluster

`phases`

Not all kubernetes resources can be installed at once. There is an ordering to it. Phases are the mechanism to declare that a bundle has a dependency on another.

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles`

Set of bundles that belong in this phase.

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.createNamespaces`

Namespaces to create for this phase

Type: list of string

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts`

Helm charts to render for this phase. Charts are rendered at build time using helm template, with optional kustomize patching.

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.chart`

Helm chart derivation

Type: package

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.createNamespace`

Whether to create the namespace if it doesn’t exist

Type: boolean

Default: true

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.extraOpts`

Extra options to pass to helm template

Type: list of string

Default:

[
  "--skip-tests"
]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.kustomize`

Kustomize patching configuration

Type: submodule

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.kustomize.enable`

Enable kustomize-based patching of helm output

Type: boolean

Default: false

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.kustomize.patches`

Strategic merge patches to apply to helm output. Each patch is an attribute set that will be merged with matching resources.

Type: list of (attribute set)

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.kustomize.patchesJson6902`

JSON Patch (RFC 6902) operations to apply to helm output.

Type: list of (attribute set)

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.kustomize.resources`

Additional resources to include alongside helm output. Can be paths to YAML files or inline YAML strings.

Type: list of (absolute path or string)

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.namespace`

Kubernetes namespace for the release

Type: string

Default: "default"

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.releaseName`

Helm release name (defaults to attribute name)

Type: string

Default: "‹name›"

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.helmCharts.<name>.values`

Helm values to pass to the chart

Type: attribute set

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources`

Typed Kubernetes resources to include in this phase. Resources are validated against the generated K8s 1.31 API types and CRD types.

Type: attribute set of (open submodule of (attribute set))

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.apiVersion`

Kubernetes API version (e.g., ‘v1’, ‘apps/v1’)

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.data`

Data for ConfigMap/Secret resources

Type: null or (attribute set of string)

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.kind`

Kubernetes resource kind (e.g., ‘Service’, ‘Deployment’)

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata`

Resource metadata

Type: open submodule of (attribute set)

Default:

{
  name = "‹name›";
}

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.annotations`

Arbitrary non-identifying metadata attached to objects.

Type: attribute set of string

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.finalizers`

List of finalizers that must be empty before the object is deleted.

Type: list of string

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.generateName`

Optional prefix for generated names when name is not specified.

Type: null or string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.labels`

Map of string keys and values for organizing and categorizing objects.

Type: attribute set of string

Default: { }

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.name`

Resource name. Must be unique within a namespace.

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.namespace`

Namespace for the resource. Null for cluster-scoped resources.

Type: null or string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences`

List of objects depended by this object.

Type: list of (open submodule of (attribute set))

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences.*.apiVersion`

API version of the referent.

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences.*.blockOwnerDeletion`

If true, the owner cannot be deleted until this reference is removed.

Type: null or boolean

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences.*.controller`

If true, this reference points to the managing controller.

Type: null or boolean

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences.*.kind`

Kind of the referent.

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences.*.name`

Name of the referent.

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.metadata.ownerReferences.*.uid`

UID of the referent.

Type: string

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.spec`

Resource spec (structure depends on kind)

Type: null or (attribute set)

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.resources.<name>.stringData`

String data for Secret resources

Type: null or (attribute set of string)

Declared in: modules/lab/cluster/phases

`phases.<name>.bundles.<name>.yamls`

Raw YAML manifests to include in this phase. Use this as an escape hatch when typed resources don’t fit. Can be inline strings or paths to YAML files.

Type: list of (string or absolute path)

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.crdNames`

CRD names to wait for (used when waitForCRDs = true)

Type: list of string

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.dependsOn`

Phases that must complete before this one

Type: list of string

Default: [ ]

Declared in: modules/lab/cluster/phases

`phases.<name>.keepResources`

Prevent deletion of resources in this phase

Type: boolean

Default: false

Declared in: modules/lab/cluster/phases

`phases.<name>.order`

Numeric ordering (lower = deployed earlier)

Type: signed integer

Declared in: modules/lab/cluster/phases

`phases.<name>.pruneStrategy`

Resource pruning behavior:

default: normal prune
never: never prune
orphan: orphan on deletion

Type: one of "default", "never", "orphan"

Default: "default"

Declared in: modules/lab/cluster/phases

`phases.<name>.timeout`

Timeout for this phase’s deployment

Type: string

Default: "10m"

Declared in: modules/lab/cluster/phases

`phases.<name>.waitForCRDs`

Wait for CRDs to be established before deploying this phase

Type: boolean

Default: false

Declared in: modules/lab/cluster/phases

`phases.<name>.waitForReady`

Wait for all resources to become ready

Type: boolean

Default: true

Declared in: modules/lab/cluster/phases

`provisioner.docker.clusterName`

Docker cluster name

Type: string

Default: "catallaxy-‹name›"

Declared in: modules/lab/provisioners/docker.nix

`provisioner.docker.colima.cpu`

Number of CPUs for the VM

Type: signed integer

Default: 4

Declared in: modules/lab/provisioners/docker.nix

`provisioner.docker.colima.disk`

Disk size in GiB for the VM

Type: signed integer

Default: 60

Declared in: modules/lab/provisioners/docker.nix

`provisioner.docker.colima.enable`

Use Colima on macOS (auto-detected, ignored on Linux)

Type: boolean

Default: true

Declared in: modules/lab/provisioners/docker.nix

`provisioner.docker.colima.memory`

Memory in GiB for the VM

Type: signed integer

Default: 8

Declared in: modules/lab/provisioners/docker.nix

`provisioner.docker.colima.profile`

Colima profile name (isolates from other VMs)

Type: string

Default: "catallaxy"

Declared in: modules/lab/provisioners/docker.nix

`provisioner.docker.waitTimeout`

Timeout waiting for cluster to be ready

Type: string

Default: "10m"

Declared in: modules/lab/provisioners/docker.nix

`provisioner.k3d.autoDeployManifests`

Manifests to mount into k3s auto-deploy directory (/var/lib/rancher/k3s/server/manifests/). k3s applies these at boot. Used for pre-deploying CNI (Cilium) so nodes become Ready immediately.

Type: list of (submodule)

Default: [ ]

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.autoDeployManifests.*.content`

Nix store path to rendered manifest YAML

Type: absolute path

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.autoDeployManifests.*.name`

Manifest filename (without .yaml)

Type: string

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.clusterName`

k3d cluster name

Type: string

Default: "‹name›"

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.extraApiServerArgs`

Extra kube-apiserver arguments passed to k3d via –k3s-arg “–kube-apiserver-arg=@server:*”. Automatically populated from components.oidc and pki-auth.

Type: list of string

Default: [ ]

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.extraVolumes`

Extra volume mounts for k3d server nodes (e.g., CA certs)

Type: list of (submodule)

Default: [ ]

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.extraVolumes.*.containerPath`

Path inside k3d node

Type: string

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.extraVolumes.*.hostPath`

Path on the Docker host

Type: string

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.image`

Custom k3s image (null = k3d default)

Type: null or string

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.network`

Docker network to create k3d cluster on (uses –network flag). When set, all clusters share this network for cross-cluster DNS.

Type: null or string

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.noFlannel`

Disable default Flannel CNI (for Cilium)

Type: boolean

Default: true

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.noServiceLB`

Disable default ServiceLB (Klipper)

Type: boolean

Default: true

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.noTraefik`

Disable default Traefik ingress

Type: boolean

Default: true

Declared in: modules/lab/provisioners/k3d.nix

`provisioner.k3d.ports`

Port mappings for k3d (passed as -p flags). Format: “:@server:0” e.g. “8080:80@server:0”

Type: list of string

Default: [ ]

Declared in: modules/lab/provisioners/k3d.nix

`resources`

This option has no description.

Type: attribute set of (attribute set)

Default: { }

Declared in: modules/lab/cluster

Secret projections map lab-level managed secrets into Kubernetes Secrets. Each projection creates one K8s Secret with keys derived from a source managed secret, optionally transformed (base64, json-wrap).

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/cluster/components/secrets