Lab Options

Cluster configurations. Each cluster is provisioned directly by the CLI (e.g. via k3d for local dev). Any cluster can optionally enable CAPI to manage external clusters.

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/types.nix

`dns.containerName`

Docker container name for the DNS server

Type: string

Default: "catallaxy-dns"

Declared in: modules/lab/dns.nix

`dns.enable`

Whether to enable Lab DNS server (Knot DNS with RFC2136 for ExternalDNS).

Type: boolean

Default: false

Example: true

Declared in: modules/lab/dns.nix

`dns.hostPort`

Host-mapped port for the DNS server (for host access). Avoids 5353 which conflicts with mDNS.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: 5354

Declared in: modules/lab/dns.nix

`dns.image`

Knot DNS container image

Type: string

Default: "cznic/knot:latest"

Declared in: modules/lab/dns.nix

`dns.out.dnsInfo`

DNS server info for host resolver configuration

Type: attribute set

Default: { }

Declared in: modules/lab/dns.nix

`dns.out.service`

Computed container service definition for the lab DNS server

Type: attribute set

Default: { }

Declared in: modules/lab/dns.nix

`dns.port`

Port for the DNS server (as seen from clusters, defaults to hostPort)

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: 5354

Declared in: modules/lab/dns.nix

`dns.server`

IP address where the DNS server is reachable from clusters (Docker gateway by default)

Type: string

Default: "172.19.0.1"

Declared in: modules/lab/dns.nix

`dns.tsigKeyname`

TSIG key name for RFC2136 dynamic updates

Type: string

Default: "externaldns-key"

Declared in: modules/lab/dns.nix

`dns.tsigSecret`

Base64-encoded TSIG secret (pre-generated for local dev)

Type: string

Default: "kp4bgnFAVCmajGIqOW7rj0MNwRNZHBqMvYaLTwzPHgI="

Declared in: modules/lab/dns.nix

`dns.tsigSecretAlg`

TSIG algorithm

Type: string

Default: "hmac-sha256"

Declared in: modules/lab/dns.nix

`dns.zone`

DNS zone for the lab (defaults to ‘.test’)

Type: string

Default: "docs-placeholder.test"

Declared in: modules/lab/dns.nix

`environment`

Lab environment. Components can adjust defaults based on this:

development: minimal replicas, relaxed resource limits, self-signed TLS
staging: moderate replicas, production-like config, self-signed or ACME TLS
production: HA replicas, strict resource limits, ACME TLS, destructive ops require –force

Type: one of "development", "staging", "production"

Default: "development"

Declared in: modules/lab/types.nix

`images.allowedRegistries`

When non-empty, the lint check warns about images from registries not in this list. Example: [“ghcr.io” “registry.k8s.io” “docker.io”]

Type: list of string

Default: [ ]

Declared in: modules/lab/images.nix

`images.pins`

Pinned container images. Each pin declares an image with optional tag and digest. Components can reference pins via lab.images.pins.<name>.ref to get the full image reference string.

Example: lab.images.pins.grafana = { image = “docker.io/grafana/grafana”; tag = “11.4.0”; digest = “sha256:abc123…”; };

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/images.nix

`images.pins.<name>.digest`

Image digest (e.g., sha256:abc123…). Immutable — ensures reproducibility.

Type: null or string

Declared in: modules/lab/images.nix

`images.pins.<name>.image`

Full image path (e.g., docker.io/grafana/grafana)

Type: string

Declared in: modules/lab/images.nix

`images.pins.<name>.ref`

Computed full image reference (image:tag@digest)

Type: string

Declared in: modules/lab/images.nix

`images.pins.<name>.tag`

Image tag (e.g., 11.4.0). Mutable — use digest for reproducibility.

Type: null or string

Declared in: modules/lab/images.nix

`images.requireDigest`

When true, the lint check errors on container images without digest pins. Use this to enforce reproducible deployments.

Type: boolean

Default: false

Declared in: modules/lab/images.nix

`lint.checks`

Custom lint checks that run on rendered manifests. Each check is a shell command executed per YAML file. Checks run alongside built-in checks during cata lab lint.

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/lint.nix

Shell command to execute per YAML file. Environment variables: $FILE — path to the YAML manifest file $CLUSTER — name of the cluster being checked Exit 0 = pass, non-zero = fail. Stdout = diagnostic message (shown to user on failure).

Type: string

Declared in: modules/lab/lint.nix

`lint.checks.<name>.description`

Human-readable description of what this check validates

Type: string

Declared in: modules/lab/lint.nix

`lint.checks.<name>.severity`

Error = fails the lint, Warning = reported but doesn’t fail

Type: one of "error", "warning"

Default: "warning"

Declared in: modules/lab/lint.nix

`name`

Unique name for this lab

Type: string

Example: "homelab"

Declared in: modules/lab/types.nix

`network.dockerSubnet`

Subnet for the lab

Type: string

Default: "172.19.0.0/16"

Declared in: modules/lab/network.nix

`ops.commands`

Lab-global operational commands. These are not cluster-specific and appear directly in the ops tool under their category.

Components contribute cluster-scoped commands via the cluster-level ops.<name> option. Same-named commands from different clusters are automatically merged (enum options get their values unioned).

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/ops.nix

`ops.commands.<name>.args`

Positional arguments

Type: list of (submodule)

Default: [ ]

Declared in: modules/lab/ops.nix

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

This option has no description.

Type: string

Default: ""

Declared in: modules/lab/ops.nix

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

This option has no description.

Type: string

Declared in: modules/lab/ops.nix

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

This option has no description.

Type: boolean

Default: true

Declared in: modules/lab/ops.nix

`ops.commands.<name>.category`

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

Type: string

Default: "general"

Declared in: modules/lab/ops.nix

`ops.commands.<name>.description`

One-line description shown in help

Type: string

Declared in: modules/lab/ops.nix

`ops.commands.<name>.options`

Named options (flags)

Type: attribute set of (submodule)

Default: { }

Declared in: modules/lab/ops.nix

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

This option has no description.

Type: null or string

Declared in: modules/lab/ops.nix

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

This option has no description.

Type: string

Default: ""

Declared in: modules/lab/ops.nix

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

This option has no description.

Type: boolean

Default: false

Declared in: modules/lab/ops.nix

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

This option has no description.

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

Default: "string"

Declared in: modules/lab/ops.nix

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

Valid values for enum type

Type: list of string

Default: [ ]

Declared in: modules/lab/ops.nix

`ops.commands.<name>.package`

Package providing the command binary

Type: package

Declared in: modules/lab/ops.nix

`ops.out.tool`

Generated lab operations CLI tool (null if no commands defined)

Type: null or package

Declared in: modules/lab/ops.nix

`out.allClusters`

Computed attrset of all clusters in the lab. Keys are cluster names, values are evaluated cluster configs. Use this for cross-cluster references.

Type: attribute set of (attribute set)

Default: { }

Declared in: modules/lab/out.nix

`out.bootstrapManifests`

Per-cluster kapp-format manifests for direct-apply bootstrap. When strategy is kapp, this equals manifests. Otherwise renders with kapp for use by lab up (which always direct-applies).

Type: attribute set of package

Default: { }

Declared in: modules/lab/out.nix

`out.cliConfig`

JSON-serializable lab configuration for the CLI. Contains the fields that cata lab commands need: management, clusterNames, services, network, registryPort, dnsInfo.

Type: attribute set

Default: { }

Declared in: modules/lab/out.nix

`out.clusterNames`

List of all cluster names in the lab

Type: list of string

Default: [ ]

Declared in: modules/lab/out.nix

`out.deploymentPlan`

Computed deployment plan — an ordered list of typed steps for the CLI to execute. Inspect with cata lab plan.

Type: list of (submodule)

Keyboard shortcuts

Catallaxy