Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

fleet.settings

62 options

fleet.settings.acmeEmail

Email for ACME account registration (internal CA and public Let’s Encrypt). null ⇒ no ACME issuance; required (asserted) by infra.ingress and by host-cert when an internal CA is configured.

Type: null or string

Default:

null

Example:

"admin@example.com"

Declared by: nix/fleet/settings.nix

fleet.settings.adminSshKeys

SSH public keys authorized for the built-in operator accounts (sysadmin / colmena / dev / root) on every fleet host. REQUIRED BY THE BASE LAYER — every NixOS fleet host creates these accounts, so building any host toplevel forces this option.

Type: list of string

Default:

[ ]

Example:

[
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIREPLACEMEexamplekeyexamplekeyexample operator@example.com"
]

Declared by: nix/fleet/settings.nix

fleet.settings.auth.oidcBaseUrl

Base URL of the fleet’s OIDC identity provider (e.g. Authentik). Required by modules that enable OIDC login (e.g. infra.observability.stack.oidc).

Type: null or string

Default:

null

Example:

"https://auth.example.dev"

Declared by: nix/fleet/settings.nix

fleet.settings.auth.outpostUrl

Base URL of the identity provider’s forward-auth outpost (e.g. the Authentik embedded outpost). null ⇒ no forward_auth injection by default.

Type: null or string

Default:

null

Example:

"http://192.0.2.13:9000"

Declared by: nix/fleet/settings.nix

fleet.settings.backend.bucket

Tofu S3 state bucket (type = s3). Shared estate substrate (ADR-097) — fleet separation is the state KEY prefix, not the bucket. When set, mkFleet’s backend argument may be omitted.

Type: null or string

Default:

null

Example:

"acme-tofu"

Declared by: nix/fleet/settings.nix

fleet.settings.backend.perStack

Per-stack backend overrides, keyed by stack SLUG (the dot-path with “.” replaced by “-”, e.g. “platform.core” -> “platform-core”). Each value is merged over the fleet-wide backend, so an override may set only what differs (usually just type).

The backend block is already emitted per stack, so this costs nothing structurally. Two uses it exists for:

  • Keep working when the shared bucket is unreachable — provision a NEW stack on type = "local" while every existing stack stays pointed at the remote it already lives in.
  • Break a bootstrap cycle — a stack that provisions the fleet’s own object storage should not keep its state inside that storage.

DELIBERATE ACT, NOT A FALLBACK. Pointing an EXISTING stack at an empty backend makes tofu read its entire inventory as “not created yet”, and an apply from there would recreate the fleet. Override a stack that has no remote state yet, or migrate the state first and record that you did.

Type: attribute set of attribute set of raw value

Default:

{ }

Example:

{ "platform-mcp" = { type = "local"; }; }

Declared by: nix/fleet/settings.nix

fleet.settings.backend.pg.connStrSopsPath

SOPS path to the libpq connection string, exported as PG_CONN_STR at run time.

The connection string is DELIBERATELY not emitted into the backend block: config.tf.json is built by Nix and therefore lands in /nix/store, which is world-readable. A password baked in there is readable by every user on every machine that builds the stack, and no amount of file permissions afterwards takes it back. OpenTofu reads PG_CONN_STR from the environment for exactly this reason.

Type: null or string

Default:

null

Example:

"[\"dbs\"][\"tofu-db\"][\"tofu\"][\"conn_str\"]"

Declared by: nix/fleet/settings.nix

fleet.settings.backend.pg.schemaPrefix

Schema-name prefix for the pg backend. Each stack gets its own schema (<prefix><slug>), which is how stacks stay isolated in one database — the equivalent of the S3 key prefix.

Type: string

Default:

"tf_"

Declared by: nix/fleet/settings.nix

fleet.settings.backend.region

AWS region of the state bucket (type = s3).

Type: string

Default:

"us-east-1"

Declared by: nix/fleet/settings.nix

fleet.settings.backend.s3.credsSopsPath

SOPS path to the S3 state-backend credentials — a mapping with access_key_id, secret_access_key, and optionally region — exported as AWS_* at run time. Defaults to ["integrations"]["aws"].

This is a setting rather than a constant because the AWS name is a site opinion, not a fact about the backend: a fleet whose state lives in Garage or MinIO files those keys under its own tree. When the CLI guessed, the extract simply returned non-zero and the credentials silently stayed unset — surfacing much later as tofu reporting no valid credential sources, with nothing pointing at the real cause.

Type: null or string

Default:

null

Example:

"[\"integrations\"][\"tofu\"][\"garage\"]"

Declared by: nix/fleet/settings.nix

fleet.settings.backend.type

Tofu state backend kind. “local” keeps terraform.tfstate inside each stack’s working dir (.tf//) — no bucket, no cloud creds; fine for a homelab, but the state only exists on the machine that ran the apply. “s3” (default) is the shared-bucket estate model (ADR-097). “pg” is Postgres, the on-prem option that provides REAL locking via advisory locks — S3-compatible stores that cannot do conditional writes (Garage, by design) leave use_lockfile silently ineffective, which is unsafe wherever more than one operator or agent applies.

Type: one of "s3", "local", "pg"

Default:

"s3"

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines

Remote build machines available to the fleet. Listing one here does NOT make any host use it: a host opts in via infra.build.remote.enable, because offloading means shipping that host an SSH private key.

Type: list of (submodule)

Default:

[ ]

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.hostName

Address the offloading host connects to over SSH. An in-fleet IP, not a public name.

Type: string

Default: none (required when its feature is enabled)

Example:

"192.0.2.101"

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.maxJobs

Jobs the offloading host may run on this machine concurrently.

Type: signed integer

Default:

4

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.publicHostKey

Base64 of the machine’s SSH host key line, produced by base64 -w0 < /etc/ssh/ssh_host_ed25519_key.pub. Leaving this null makes the offload depend on the client’s known_hosts, which nothing in the fleet populates — the first build then hangs on host-key verification rather than failing.

Type: null or string

Default:

null

Example:

"c3NoLWVkMjU1MTkgQUFBQUV4YW1wbGVFeGFtcGxlRXhhbXBsZQ=="

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.speedFactor

Relative speed weight. Only meaningful when more than one machine can serve the same system.

Type: signed integer

Default:

1

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.sshUser

User to connect as. Must appear in the builder’s infra.build.builder.trustedUsers, or its daemon refuses the store operations an offloaded build needs.

Type: string

Default:

"root"

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.supportedFeatures

Features this machine advertises. A derivation requiring a feature absent here is never sent to it. Do not advertise kvm on an unprivileged LXC builder.

Type: list of string

Default:

[
  "nixos-test"
  "benchmark"
  "big-parallel"
]

Example:

[
  "nixos-test"
  "benchmark"
  "big-parallel"
  "kvm"
]

Declared by: nix/fleet/settings.nix

fleet.settings.build.machines.*.systems

Platforms this machine will build for.

Type: list of string

Default:

[
  "x86_64-linux"
]

Declared by: nix/fleet/settings.nix

fleet.settings.cache.substituters

In-fleet nix binary caches trusted by fleet hosts (harmonia/attic/…).

Type: list of string

Default:

[ ]

Example:

[
  "http://192.0.2.101:5000"
]

Declared by: nix/fleet/settings.nix

fleet.settings.cache.trustedPublicKeys

Public keys matching substituters.

Type: list of string

Default:

[ ]

Example:

[
  "cache.example.dev:MExampleExampleExampleExampleExampleExampleExa="
]

Declared by: nix/fleet/settings.nix

fleet.settings.cli.extensionsDir

Repo-relative directory of consumer CLI extension modules (ADR-095 COMMANDS/ATTACH files).

Type: string

Default:

"cli-ext"

Declared by: nix/fleet/settings.nix

fleet.settings.domain.base

Public base domain (external DNS zone). null ⇒ no public-name features; required (asserted) by modules that mint public names: caddy devDomain vhosts, coredns split-horizon zone, acme-dns, hydra/grafana mail senders, pve-installer-answers.

Type: null or string

Default:

null

Example:

"example.dev"

Declared by: nix/fleet/settings.nix

fleet.settings.domain.internal

Internal search/zone domain served by fleet DNS. null ⇒ no internal-FQDN features; required (asserted) by caddy, coredns, host-cert (internal CA), step-ca, hydra, rabbitmq management vhosts.

Type: null or string

Default:

null

Example:

"example.pve"

Declared by: nix/fleet/settings.nix

fleet.settings.domain.tailnetSuffix

MagicDNS base domain of the fleet tailnet (headscale base_domain). null ⇒ no tailnet serveUI names; required (asserted) when infra.network.tailnet.serveUI entries exist.

Type: null or string

Default:

null

Example:

"hs.example.dev"

Declared by: nix/fleet/settings.nix

fleet.settings.githubAccessTokens

Provision a GitHub machine-user token (SOPS integrations/github/machine_user_token) into nix access-tokens on every host — needed when flake inputs fetch private GitHub repos.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.internalCa.acmeDirectory

ACME directory URL of the internal CA. null ⇒ modules default to public Let’s Encrypt.

Type: null or string

Default:

null

Example:

"https://ca.example.lan:9000/acme/acme/directory"

Declared by: nix/fleet/settings.nix

fleet.settings.internalCa.certFile

Root certificate of the fleet-internal CA (step-ca). Trusted on every host and used as the Caddy ACME root when set.

Type: null or absolute path

Default:

null

Example:

./certs/fleet-root-ca.crt

Declared by: nix/fleet/settings.nix

fleet.settings.mcp.grafanaTokenSopsPath

Sops key path of the read-only Grafana service-account token used by fleet mcp config.

Type: null or string

Default:

null

Example:

"services/grafana/mcp_token"

Declared by: nix/fleet/settings.nix

fleet.settings.name

Short fleet/org slug. Used for branding and resource-name prefixes (attic cache name, hydra project, step-ca CA name, pgweb bookmarks).

Type: string

Default:

"fleet"

Example:

"acme"

Declared by: nix/fleet/settings.nix

fleet.settings.network.lanCidr

Fleet LAN CIDR (mirrors fleet.network.internal_cidr for module convenience). null ⇒ modules that default network ACLs from it (e.g. infra.data.postgresql.allowedSubnets) default to an empty list instead.

Type: null or string

Default:

null

Example:

"192.0.2.0/24"

Declared by: nix/fleet/settings.nix

fleet.settings.network.mgmtCidr

Hypervisor/management network CIDR, if separate from the LAN.

Type: null or string

Default:

null

Example:

"198.51.100.0/24"

Declared by: nix/fleet/settings.nix

fleet.settings.network.staticWanCidrs

VM name → WAN-side CIDR for legacy name-dispatch VMs whose fleet entry keeps ip = "" (so Colmena resolves internal_ip) but still needs a pinned WAN address on eth0. Consumed by the headscale-router branch of nix/lib/tf/proxmox.nix mkVm. {} ⇒ no pins; the emitter throws if a VM hits that branch without an entry here.

Type: attribute set of string

Default:

{ }

Example:

{
  headscale-router = "198.51.100.7/24";
}

Declared by: nix/fleet/settings.nix

fleet.settings.network.upstreamResolvers

Upstream DNS servers the fleet DNS forwards non-fleet queries to (e.g. the LAN gateway or public resolvers).

Type: list of string

Default:

[
  "1.1.1.1"
  "9.9.9.9"
]

Example:

[
  "198.51.100.1"
  "1.1.1.1"
]

Declared by: nix/fleet/settings.nix

fleet.settings.network.wanIp

Public WAN IP of the fleet edge (stable pointer for public DNS pins). null ⇒ no public-edge features; required (asserted) by infra.pki.acmeDns (glue/apex A records).

Type: null or string

Default:

null

Example:

"203.0.113.10"

Declared by: nix/fleet/settings.nix

fleet.settings.observability.cpuAlertExcludeRegex

Prometheus instance-label regex excluded from the fleet-wide high-CPU alert (hosts that legitimately run hot). “” ⇒ no exclusions.

Type: string

Default:

""

Example:

"chain-node-.*|miner-.*"

Declared by: nix/fleet/settings.nix

fleet.settings.observability.grafanaDomain

Domain Grafana serves on (server.domain / root_url). null ⇒ no observability stack; required (asserted) when infra.observability.stack is enabled.

Type: null or string

Default:

null

Example:

"grafana.example.pve"

Declared by: nix/fleet/settings.nix

fleet.settings.observability.lokiPushUrl

Loki push endpoint every fleet host’s Alloy agent ships logs to (usually the grafana-stack host). null (together with prometheusRemoteWriteUrl = null) ⇒ Alloy stays disabled by default fleet-wide; required (asserted) when infra.observability.alloy is enabled.

Type: null or string

Default:

null

Example:

"http://192.0.2.4:3100/loki/api/v1/push"

Declared by: nix/fleet/settings.nix

fleet.settings.observability.lokiS3Endpoint

S3-compatible endpoint (e.g. in-fleet Garage) Loki writes chunks and index to. null ⇒ no Loki chunk store; required (asserted) when infra.observability.stack is enabled.

Type: null or string

Default:

null

Example:

"http://s3.example.lan:3900"

Declared by: nix/fleet/settings.nix

fleet.settings.observability.prometheusRemoteWriteUrl

Prometheus remote-write endpoint every fleet host’s Alloy agent ships metrics to (usually the grafana-stack host). null (together with lokiPushUrl = null) ⇒ Alloy stays disabled by default fleet-wide; required (asserted) when infra.observability.alloy is enabled.

Type: null or string

Default:

null

Example:

"http://192.0.2.4:9090/api/v1/write"

Declared by: nix/fleet/settings.nix

fleet.settings.observability.pveScrapeTargets

Proxmox VE hypervisors scraped via prometheus-pve-exporter: instance label → node API address. {} ⇒ no PVE targets.

Type: attribute set of string

Default:

{ }

Example:

{
  pve1 = "198.51.100.1";
  pve2 = "198.51.100.2";
}

Declared by: nix/fleet/settings.nix

fleet.settings.observability.tempoUrl

HTTP URL of the fleet’s Tempo trace store. null ⇒ no Tempo datasource is provisioned in Grafana.

Type: null or string

Default:

null

Example:

"http://192.0.2.9:3200"

Declared by: nix/fleet/settings.nix

fleet.settings.opsEmail

Operations contact. null ⇒ the CLI derives ops@<domain.base>.

Type: null or string

Default:

null

Example:

"ops@example.dev"

Declared by: nix/fleet/settings.nix

fleet.settings.pki.acmeDnsApiBase

acme-dns registration API on the fleet’s DNS edge. Consumed by fleet pki (required, asserted there).

Type: null or string

Default:

null

Example:

"http://192.0.2.100:8081"

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.defaultDatastore

PVE storage used wherever a compute entry does not name one: VM root/EFI/data disks, the cloud-init drive, clone targets, and the default of fleet.compute..root_disk_datastore. LEGACY DEFAULT “local-storage” is kept so existing fleets render unchanged; set it explicitly (PVE’s stock thin pool is “local-lvm”) — the default flips to “local-lvm” in the next major release.

Type: string

Default:

"local-storage"

Example:

"local-lvm"

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks

Hypervisor-side conveniences the community tools/pve/*.sh scripts used to apply by hand, now driven by ansible (roles proxmox/base and proxmox/pve) from these values. fleet ansible inventory exports them as the fleet_pve_host_tweaks variable.

Type: submodule

Default:

{ }

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.diskHealth

Install smartmontools + nvme-cli and run a weekly SMART short self-test on every disk. Legacy disk-health.sh.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.ipTag

Run the IP-Tag service that keeps a <ip> tag on every guest in the PVE UI. Legacy add-iptag.sh. PVE nodes only.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.kernelClean

Purge old PVE kernels on each ansible run, keeping the running one and the newest. Legacy kernel-clean.sh.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.kernelPin

Pin the node to this kernel version with proxmox-boot-tool (null = unpinned). Legacy kernel-pin.sh.

Type: null or string

Default:

null

Example:

"6.14.8-2-pve"

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.microcode

Install the CPU microcode package for the node’s vendor (intel-microcode / amd64-microcode; enables non-free-firmware). Legacy microcode.sh.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.monitorAll

Run the ping-instances service that restarts guests that stop answering. Legacy monitor-all.sh. PVE nodes only.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.nicOffloadingFix

Disable NIC offloading (ethtool) on Intel e1000/e1000e adapters at boot to work around hangs. Legacy nic-offloading-fix.sh.

Type: boolean

Default:

false

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.hostTweaks.scalingGovernor

CPU frequency scaling governor applied at boot (null = leave the kernel default). Legacy scaling-governor.sh.

Type: null or one of "performance", "powersave", "ondemand", "conservative", "schedutil"

Default:

null

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.lxcTemplateDatastore

PVE storage (content type vztmpl) that holds the NixOS LXC template nixos-lxc-template-x86_64.tar.xz every NixOS container is created from. LEGACY DEFAULT “nix-store” (a cluster-wide NFS SR registered by the ansible proxmox/pve nfs-storage task); a single-node fleet uploads the template to “local” instead via a kind = "file" resource with source = “nixos-lxc-image”.

Type: string

Default:

"nix-store"

Example:

"local"

Declared by: nix/fleet/settings.nix

fleet.settings.providers.proxmox.singleBridgeInstances

Proxmox provider-instance names (the <inst> in a fleet entry’s provider_instance = "proxmox.<inst>") whose PVE nodes carry the internal LAN directly on vmbr0 (single-NIC nodes, e.g. PVE-on-XCP-ng VMs). Containers on these instances default their internal bridge to vmbr0 instead of vmbr1; a per-host internal_bridge override still wins.

Type: list of string

Default:

[ ]

Example:

[
  "colo"
]

Declared by: nix/fleet/settings.nix

fleet.settings.pveInstall

Unattended-PVE-install constants for fleet pve install (serve_host, iso_sr_uuid, iso_sr_name, main_sr_name, network_name, installer_iso, presets). Freeform: substrate constants whose long-term home is the typed provider nodes (ADR-096); keys pass to the catalog verbatim.

Type: attribute set of raw value

Default:

{ }

Example:

{
  iso_sr_name = "NFS ISO Library";
  serve_host = "192.0.2.91";
}

Declared by: nix/fleet/settings.nix

fleet.settings.sopsFiles

Which SOPS file owns which TOP-LEVEL key tree, for fleets that split their store by resource group. Keys are tree names (“integrations”, “services”, “dbs”, …); values are repo-relative paths. Anything not listed falls back to sopsSecretsFile.

Splitting a store and leaving the original populated is the trap this exists to close: a consumer aimed at the old file ERRORS when the key is gone, but returns a diverged old value when a stale duplicate survives — and that case never fails. Declaring routes once means a consumer cannot hold a private, wrong opinion about where a tree lives.

Type: attribute set of string

Default:

{ }

Example:

{ integrations = "nix/secrets/integrations.yaml"; }

Declared by: nix/fleet/settings.nix

fleet.settings.sopsSecretsFile

Repo-relative path of the default sops file the CLI’s secrets commands operate on.

Type: string

Default:

"nix/secrets/secrets.yaml"

Declared by: nix/fleet/settings.nix

fleet.settings.tailnet.controlUrl

Login/control server URL of the fleet tailnet (headscale). Used as –login-server by infra.network.tailnet.fleetNode. null ⇒ fleetNode emits no –login-server flag.

Type: null or string

Default:

null

Example:

"https://vpn.example.dev"

Declared by: nix/fleet/settings.nix

fleet.settings.tailnet.preauthKeyUrl

HTTPS endpoint returning a tailnet preauth key as raw text (e.g. a source-IP-gated headscale vhost). Used by infra.network.tailnet.fleetNode to auto-fetch enrollment keys. null ⇒ hosts fall back to a SOPS-held auth key.

Type: null or string

Default:

null

Example:

"https://vpn.example.dev/internal/preauth/fleet-bot"

Declared by: nix/fleet/settings.nix

fleet.settings.tfSopsFile

Repo-relative SOPS file the TERRANIX layer reads at tofu apply time (the data.sops_file.secrets source). These are provider credentials — integrations.* — which need not live in the same file NixOS hosts default to. A fleet that splits its SOPS store per resource group must point this at whichever file holds the integrations tree, or every tofu plan fails with “The given key does not identify an element in this collection value”.

Type: string

Default:

"nix/secrets/secrets.yaml"

Example:

"nix/secrets/integrations.yaml"

Declared by: nix/fleet/settings.nix