meta/architecture-docs/NixOps4-based-installation-process.md

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