about summary refs log tree commit diff
path: root/ops/terraform/deploy-nixos/README.md
diff options
context:
space:
mode:
authorVincent Ambo <mail@tazj.in>2023-01-29T16·44+0300
committertazjin <tazjin@tvl.su>2023-03-03T10·48+0000
commitdbca46d05205bdaab07d4faf1899a6452f34dd0f (patch)
treecdaf75f1bcf73dc70075d6c570cf3e42856b7019 /ops/terraform/deploy-nixos/README.md
parent0b64577702ca7e412bb2af4af7af9e33efc5c0f5 (diff)
feat(ops/terraform): add module for deploying NixOS system closures r/5867
This module makes it fairly easy to deploy NixOS system closures using
Terraform, while properly separating the evaluation of a
derivation (to determine whether a deploy is needed) from the building
and copying of the closure itself.

This has been on my stack for a while. It was originally developed for
Resoptima, who agreed to open-sourcing it in depot back when we
completed our work with them. Their contribution has been acknowledged
in the README.

Co-Authored-By: Florian Klink <flokli@flokli.de>
Change-Id: Ica4c170658cd25f1fb7072c9a45735fcc4351474
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7950
Reviewed-by: tazjin <tazjin@tvl.su>
Tested-by: BuildkiteCI
Diffstat (limited to 'ops/terraform/deploy-nixos/README.md')
-rw-r--r--ops/terraform/deploy-nixos/README.md45
1 files changed, 45 insertions, 0 deletions
diff --git a/ops/terraform/deploy-nixos/README.md b/ops/terraform/deploy-nixos/README.md
new file mode 100644
index 000000000000..a51e6bdb5f1e
--- /dev/null
+++ b/ops/terraform/deploy-nixos/README.md
@@ -0,0 +1,45 @@
+deploy-nixos
+============
+
+This is a Terraform module to deploy a NixOS system closure to a
+remote machine.
+
+The system closure must be accessible by Nix-importing the repository
+root and building a specific attribute
+(e.g. `nix-build -A ops.machines.machine-name`).
+
+The target machine must be accessible normally over SSH, and an SSH
+key must be used for access.
+
+Notably this module separates the evaluation of the system closure from building
+and deploying it, and uses the closure's derivation hash to determine whether a
+deploy is necessary.
+
+## Usage example:
+
+```terraform
+module "deploy_somehost" {
+  source              = "git::https://code.tvl.fyi/depot.git:/ops/terraform/deploy-nixos.git"
+  attrpath            = "ops.nixos.somehost"
+  target_name         = "somehost"
+  target_host         = "somehost.tvl.su"
+  target_user         = "someone"
+  target_user_ssh_key = tls_private_key.somehost.private_key_pem
+}
+```
+
+## Future work
+
+Several things can be improved about this module, for example:
+
+* The repository root (relative to which the attribute path is evaluated) could
+  be made configurable.
+
+* The remote system closure could be discovered to restore remote system state
+  after manual deploys on the target (i.e. "stomping" of changes).
+
+More ideas and contributions are, of course, welcome.
+
+## Acknowledgements
+
+Development of this module was sponsored by [Resoptima](https://resoptima.com/).