From 5b46270d3c598d15d9e549ba5bb4d06d9524f1ec Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Fri, 6 Sep 2024 19:00:35 +0100 Subject: [PATCH] Add architecture-docs/NixOps4-based-installation-process.md --- .../NixOps4-based-installation-process.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 architecture-docs/NixOps4-based-installation-process.md diff --git a/architecture-docs/NixOps4-based-installation-process.md b/architecture-docs/NixOps4-based-installation-process.md new file mode 100644 index 0000000..bced1f3 --- /dev/null +++ b/architecture-docs/NixOps4-based-installation-process.md @@ -0,0 +1,69 @@ +--- +status: draft +--- + + +# NixOps4-based Installation Process + +This documents explains how NixOps4 could be leveraged to provide a smooth installation experience for a simple, monolithic deployment. + +It does not go into detail about the way Nix Panel hooks into this, or whether Nix Panel manages the same NixOps4 deployment that also contains the infrastructure; a single NixOps4 deployment could provide a nice simplification in the early stages of the project. + +## Components + +Required for the setup steps in this document: + +- `nixops4`: generic deployment tool using Nix +- `landscaper.iso`: installation image that bootstraps a completely new and independent Fedi cluster - a NixOS installer with a handful of extra definitions (@roberth: easy) +- `nixops4-modules-ssh-keypair`: NixOps4 resource provider that generates keys +- `nixops4-pxe-nbp`: NixOps4 resource provider that inserts an NBP image into a (local) PXE server configuration +- `nixops4-modules-ssh`: A module that calls `ssh` using `nixops4-resources-local` +- `nixops4-resources-local`: A module that can create files and call commands locally (prototyped) +- `nixops4-modules-nixos`: A module that calls `nixos-rebuild switch --target-host` or implements similar functionality + +Expected needs: + +- `nixops4-resources-proxmox` +- A resource provider that talks to a DNS server's API + +## Steps + +### 1. `landscaper` setup + +1. connect your first server into the network + +2. boot `landscaper.iso` from a usb stick, and install NixOS onto this server we'll call `landscaper` + +`landscaper.iso` is a slightly customized NixOS installer that includes the `landscaper` NixOS module + in the default config that it generates + - mvp: copy and import the landscaper module by hand into the normal NixOS live system + +The `landscaper` module contains + - nixops4 (mvp and initial setup) + - a nixops4 service (if/when nix-panel is capable of managing the infra) + - a tftp server + +The NixOS installer puts the template NixOps4 expression in `/root/fediversity-network` + +### 2. Add a proxmox host + +1. - add a MAC address and IP address to the `proxmoxMACs` option (or similar) + - this automatically declares resources that will set up the new server + - `installation_host_key`: a temporary SSH host key pair + - `installation_pxe_nbp`: an entry in `landscaper`'s PXE server, referring to/including a kernel and initrd that run disko and performs a NixOS installation on the server disk(s) + - `ssh_host_public_key`: a resource that waits for SSH to come up, logs in to replace the host key and sends the returns the new public key as its resource output + - `nixos`: a resource that `nix copy`-es a NixOS toplevel, then updates the system profile and activates it + + - unknown: built-in services like Nix-panel, perhaps depending on the number of `proxmoxMACs` +2. `nixops apply` + - this starts to create resources, + - up to the point that `ssh_host_public_key` waits for the server to boot +3. turn on the server +4. wait for `nixops apply` to complete + +## Notes + +Unknown: add to step 2 or step 3 (new), depending on the amount of shared infra: + - resources for certain objects in the proxmox api + - this creates nixpanel, and shared infrastructure +