Deploying with resolve-only tokens
This guide will show you how to deploy a NixOS configuration published on FlakeHub.
The NixOS configuration is for an EtherCalc instance and it’s an output of the DeterminateSystems/demo
flake.
After some initial setup, you’ll be able to deploy this configuration with one command:
fh apply nixos DeterminateSystems/demo/0.1#nixosConfigurations.ethercalc-demo
Two security-related features showcased here:
- The target will have read-only Flakehub cache access only for the exact closure of the configured NixOS system (and for no other store paths).
- The target machine will not be able to access any flake source code or other artifacts.
Prerequisites
- The target machine must already be running Determinate.
- The target machine must have fh version 0.1.18 or newer.
- Your user must be an administrator of your FlakeHub organization.
- Your FlakeHub organization must have a published flake with:
include-output-paths: true
in the GitHub Action inputs and- a NixOS, nix-darwin, or Home Manager configuration, and that configuration must also be running Determinate for continued deployments.
Create a resolve-only token
Visit FlakeHub, log in, and navigate to your organization’s Device tokens tab. If you know your organization’s name already, you can reach that tab via the URL with this structure:
https://flakehub.com//:org/settings?editview=device+tokens
staticrequired
Otherwise, you can navigate manually:
- Click on your face in the upper-right corner of the FlakeHub UI, then select Settings.
- Click on Organizations.
- Next to your organization, click Settings.
- Select the Device tokens tab.
Once you’re in the tab, create a resolve-only token:
- Click New Token.
- Fill in a short description, like
Deploy to raspberrypi-garage
. - Select Resolve only for the token type
- In the project menu, select the project you want to deploy.
For this demo, for example, you’d select
DeterminateSystems/demo
. - In the field above the list of published versions, enter in the SemVer version requirement the clients will request.
For this demo,
0.1
. The versions below will indicate whether that version is allowed to be deployed. Note that the version requirement in the token form must exactly match thefh apply
command used by the client. - Select the attribute path the machine can deploy.
For the demo, select
nixosConfigurations.ethercalc-demo
. - Finally, click Create token and copy the created token.
Log the target machine in to FlakeHub
Log in to the target machine and log in to FlakeHub:
sudo determinate-nixd login token
Paste the just-created token, hit Enter, and you’ll see a confirmation like this:
Logged in: true
FlakeHub user name: DeterminateSystems
FlakeHub organizations: []
Execute your first deploy
Now that you’re logged in, run this fh apply
command to perform the deploy:
sudo fh apply nixos DeterminateSystems/demo/0.1#nixosConfigurations.ethercalc-demo
fh apply nixos
creates a short-lived token to access the cached closure of the NixOS configuration.
The generated token is valid for one hour.
Next Steps
Continuous deployment
You can orchestrate the execution of the fh apply
command across your fleet using tools like Amazon Systems Manager (SSM) or a systemd unit on a timer.
Precise roll-forward / roll-back semantics
The version number in DeterminateSystems/demo/0.1
is not a specific version but rather a SemVer version requirement.
Specifically, 0.1
means any release with a major and minor version of 0.1
.
This means that if you use a “loose” version like 0.1
you won’t be able to roll back using a previously run fh apply
step because it ressolves to the newest release
Resolve-only tokens can pass one of two version requirements:
- The exact version requirement in the creation token process (
0.1
in this case) or - An exact version requirement that is acceptable by the original token’s requirement.
In other words, a resolve-only token can deploy with exactly the same version requirement…
sudo fh apply nixos DeterminateSystems/demo/0.1#nixosConfigurations.ethercalc-demo
…or an exact version within that requirement…
sudo fh apply nixos DeterminateSystems/demo/=0.1.175#nixosConfigurations.ethercalc-demo
…but not a similar but imprecise version requirement:
sudo fh apply nixos DeterminateSystems/demo/0.1.123#nixosConfigurations.ethercalc-demo
When integrating fh apply
in a CI/CD pipeline, strive to pass an exact version requirement to fh apply
.
The exact version match is available from the flakeref_exact
output of the flakehub-push
GitHub Action.