Keys

Keys are secret files Navi delivers to a node out of band, rather than baking them into the world-readable Nix store. They are declared under deployment.keys and uploaded as part of a deploy, or on their own with navi upload-keys.

Declaring a key

Each entry under deployment.keys is a file to place on the host. Its contents come from inline text, a local file, or a command — and a command keeps the secret out of the Hive entirely:

web-01 = { ... }: {
  deployment.keys."tls.key" = {
    keyCommand = [ "pass" "show" "hosts/web-01/tls-key" ];
    destDir = "/run/keys";
    user = "nginx";
    group = "nginx";
    permissions = "0400";
  };
};

Exactly one of text, keyFile, or keyCommand must be set. The remaining fields control where the key lands and who may read it:

• destDir is the directory on the host; it defaults to /run/keys.
• name is the file name, defaulting to the attribute name.
• user, group, and permissions set ownership and mode, defaulting to root:root and 0600.

When keys are uploaded

uploadAt controls timing relative to activation:

• pre-activation (the default) uploads the key before the new profile is activated, so a service that needs it at startup finds it in place.
• post-activation uploads after a successful activation.

During an apply, keys are uploaded automatically according to this setting. Pass --no-keys to skip key upload for a run.

Uploading keys on their own

navi upload-keys uploads every declared key without doing a full deploy. This is the way to rotate a secret, or to place keys on a host before its first activation:

navi upload-keys --on web-01

When invoked this way, all keys are uploaded together regardless of their individual uploadAt setting.