Provisioners and facts

Provisioning is where Navi's lifecycle begins, before any machine exists. It creates the machines, installs NixOS onto them, and hands off to the configuration switch, all from the same Hive. Navi integrates Terranix and Terraform so that infrastructure and NixOS configuration live in one place.

The model

You declare provisioners under meta.provisioners and point a node at one with deployment.provisioner. Navi renders the Terranix expressions to Terraform, runs Terraform to create the resources, and captures the outputs as facts. Those facts — such as a freshly assigned IP address — become available to the rest of the deployment without you copying them between tools.

This closes the gap between provisioning and configuration. A single command can stand up cloud instances, install NixOS onto them, and switch them to their target configuration.

Provisioning commands

navi provision drives the Terraform lifecycle. With no argument it provisions everything; name a provisioner, or select nodes with --on, to scope it. It plans, applies, and manages the Terraform lock and state so that concurrent runs do not corrupt each other.

navi provision                      # everything
navi provision acme                 # one provisioner
navi provision --on 'acme-*'        # a slice of nodes
navi provision --list               # what is available

Common flags shape a run:

navi provision acme --reprovision      # destroy and recreate
navi provision acme --skip-install     # infrastructure only, no OS install
navi provision acme --update-tf-lock   # refresh the Terraform lock

Importing existing infrastructure into Navi's state is navi provision import.

Bootstrapping fresh machines

After provisioning creates a machine, it is a bare host with no NixOS on it. Navi integrates nixos-anywhere to install NixOS over SSH, turning a blank instance into a managed node. The navi install command loads the captured outputs and bootstraps the target:

navi install --on acme-app-1
navi install --on acme-app-1 --reinstall

For bare-metal hosts, the address can come from a flag rather than Terraform outputs; see Bare metal.

Provisioning at scale

Because selection accepts globs and tags, one command stands up a whole class of nodes. When a class is expensive to bring up and should be provisioned one at a time, list it and walk the list so a failure stops at the node it happened on:

navi provision --on 'acme-*'

for p in (navi provision --list)
    navi provision $p
end

Facts

Outputs captured from Terraform are stored as facts and persist between runs. Facts are how provisioning hands information to deployment. They are configured under meta.facts, and you can pre-compute a subset before provisioning with navi facts derive:

navi facts derive