Nereus/scripts/provision/README.md

Fedora host provisioning

This directory configures already-installed Fedora 44 hosts. Infrastructure can be created manually or by the hand-maintained Terraform configuration; both paths produce the same input: two reachable hosts in inventory.yml.

Node 1 runs the k3s server. Node 2 runs a k3s agent. The playbook is idempotent and may be rerun to converge package, firewall, k3s, and service state.

Automated path

Copy inventory.example.yml to inventory.yml, replace the addresses and node IP values, set k3s_node_cidr to the network containing only cluster nodes, set k3s_operator_cidrs to the authorized administration networks, and set the SSH user and connection options required by those hosts. The managed machines may be physical servers, VMs from any provider, or manually installed systems; the playbook does not depend on libvirt or the local lab subnet. Then provide the existing cluster token only in the process environment:

K3S_TOKEN="$(openssl rand -hex 32)" ./bootstrap.sh inventory.yml

The bootstrap checks for ansible-playbook and installs the declared Ansible collections. It does not install system packages on the operator machine.

Do not save the token in the inventory or repository. Preserve it in the operator's secret manager so a replacement agent can join the same cluster.

Manual path

Use manual-checklist.md when configuration must be performed interactively. It describes the same end state as the playbook, so a manually prepared host can later be managed by Ansible without rebuilding it.

Terraform path

Terraform is responsible only for creating machines, networks, and addresses. After terraform apply, put its resulting addresses into inventory.yml and run this playbook. Keeping configuration out of provisioner hooks makes the same Ansible workflow usable for physical hardware, VMs, and manually created hosts.

One-command local QEMU lab

lab.sh is only a disposable integration harness for this workstation. Its virbr0 interface, fixed test addresses, UFW forwarding rules, cloud image, and NetworkManager profiles are deliberately kept out of the reusable Ansible roles. Do not run it on the two production machines; put their real addresses in an inventory and run bootstrap.sh instead.

On an x86_64 Fedora or Arch-family workstation with hardware virtualization enabled:

./lab.sh

To reuse an existing Fedora 44 Cloud Base Generic QCOW2 image instead of downloading another copy:

FEDORA_IMAGE=/path/to/Fedora-Cloud-Base-Generic-44.x86_64.qcow2 ./lab.sh up

The lab intentionally supports x86_64 only. Both target Fedora hosts and the workstation used for the final project run x86_64, so maintaining a separate aarch64 image, firmware, and verification path would add an untested platform without helping the deployment demonstration.

The Fedora Server Guest Generic image is not suitable for this workflow because it starts the interactive initial-setup program instead of accepting cloud-init configuration.

The command installs missing host packages, enables libvirt, uses the selected local image or downloads the Fedora 44 cloud image, creates two reusable VMs, waits for ping and SSH, runs the Ansible configuration, and verifies applications, services, directories, ports, and Kubernetes node readiness. Its VM metadata and SSH key live under ${XDG_STATE_HOME:-$HOME/.local/state}/nereus-lab, outside the repository.

Subsequent operations are ./lab.sh check, ./lab.sh stop, and the explicitly destructive ./lab.sh destroy.

Deleting a VM also deletes any k3s local-path volumes stored on that machine. The lab recreates the host and its Kubernetes identity, but stateful demo data on the deleted disk must be recreated separately. This is acceptable for the disposable harness and is not a backup strategy.

Tested lab capacity

The complete two-node stack passed provisioning, reboot, node-disconnect recovery, workload readiness, and public API checks on 2026-08-24 with 2 vCPUs, 3 GiB RAM, and a 30 GiB virtual disk per node. These are the lowest settings tested for this project, not a production sizing recommendation. The thin QCOW2 files used approximately 2.0 GiB for node 1 and 3.3 GiB for node 2 during that verification.