Prerequisites
Before starting Day 1, work through this page completely. Missing a prerequisite mid-build is disruptive — some steps cannot be paused once started (particularly Harvester bare-metal install and RKE2 cluster formation).
Hardware Prerequisites
- All hardware procured per the Hardware spec
- All systems physically racked, cabled, and powered on
- Switch ports configured (VLANs if applicable, trunks on Harvester node ports)
- nuc-00 can reach all other nodes by IP (verify with
pingfrom nuc-00 before proceeding) - KVM/IP-KVM access confirmed for nuc-01, nuc-02, nuc-03 (needed for bare-metal Harvester install)
- NAS is online and NFS exports are configured
Credentials
All credentials are stored in ~/.config/RGS/creds on each operator machine and on nuc-00. This file is never committed to any git repository — it lives outside any repo directory.
The file follows the key=value shell variable format. Source it at the start of any session:
source ~/.config/RGS/creds
See scripts/env.d/creds.example in the infra repo for the template. Here is what must be populated before Day 1 begins:
| Credential Variable | How to Obtain | Notes |
|---|---|---|
CARBIDE_USERNAME | portal.ranchercarbide.dev — your account username | Required for Hauler sync; grants access to Carbide registry |
CARBIDE_PASSWORD | Same portal — generate a registry token/PAT | Do not use your portal login password directly |
DOCKER_USERNAME | hub.docker.com — your account username | Required to avoid Docker Hub rate limits during Hauler sync |
DOCKER_PASSWORD | Docker Hub → Account Settings → Security → New Access Token | Use a PAT, not your Docker Hub login password |
HARBOR_ADMIN_PASSWORD | Choose your own — minimum 12 characters, mixed case + numbers + symbols | Used when bootstrapping Harbor admin account |
STEP_CA_PASSWORD | Choose your own, or auto-generated by 20_bootstrap-step-ca.sh | Encrypts the step-ca intermediate key on disk |
RKE2_TOKEN | Generate: openssl rand -hex 32 | Shared secret joining all RKE2 nodes; treat like a password |
DOCKER_USERNAME and DOCKER_PASSWORD are needed even though Docker images are pulled through Hauler. Hauler authenticates to Docker Hub during the sync phase on the internet side. Without credentials, Docker Hub's unauthenticated pull rate limit (100 pulls/6 hours per IP) will cause Hauler sync to fail partway through.
Generate the RKE2_TOKEN and STEP_CA_PASSWORD now and write them down in a secure location separate from the creds file. If nuc-00 has to be rebuilt and you lose the creds file, you will need them to rejoin existing RKE2 nodes.
Operator Workstation Prerequisites
You can operate the enclave from an Apple Silicon MacBook or from nuc-00 directly. Either way, the following tools must be available in your PATH:
| Tool | Minimum Version | Purpose |
|---|---|---|
kubectl | v1.30+ | Interacting with RKE2 and downstream clusters |
helm | v3.14+ | Installing and upgrading Helm charts |
openssl | 3.x | Generating tokens, verifying certificates |
git | Any recent | Pulling the infra repo and pushing doc changes |
ssh | Any | Accessing all nodes; key must be deployed to mansible user |
SSH key deployment: the mansible operator user must have your public key in ~/.ssh/authorized_keys on nuc-00 and eventually on all RKE2 nodes (added by cloud-init during VM provisioning). Deploy to nuc-00 now:
ssh-copy-id mansible@nuc-00.carbide-enclave.kubernerdes.com
nuc-00 Prerequisites
The bootstrap script (scripts/10_bootstrap-nuc-00.sh) installs and configures all services on nuc-00. As of the current build state, this is already complete. The following services are running and verified:
| Service | Package | Status |
|---|---|---|
| NTP | chrony | Active — syncing time, serving to LAN |
| DNS | bind (named) | Active — authoritative for carbide-enclave.kubernerdes.com |
| DHCP + iPXE | dhcp-server | Active — static leases and dynamic pool configured |
| Web / file server | apache2 + PHP 8 | Active — serving at http://10.0.0.10/ |
| TFTP | tftp | Active — serving iPXE EFI binary |
| Internal CA | step-ca | Active — ACME server at https://ca.carbide-enclave.kubernerdes.com:8443 |
| Hauler | hauler | Installed — sync/save/load/serve/push via scripts/hauler.sh |
| kubectl | v1.33 | Installed — available to mansible user |
If you need to rebuild nuc-00:
sudo bash /srv/www/htdocs/carbide-enclave.kubernerdes.com/scripts/10_bootstrap-nuc-00.sh
The script is idempotent — safe to re-run.
:::note OpenSUSE Leap 15.6 package quirks (learned the hard way)
- BIND: root hints file is
root.hint(notnamed.ca); zone files live at/var/lib/named/root, not inmaster/ dhcpd: nodhcpdgroup exists — use the numeric GID fromid -g dhcpd- TFTP: package is
tftp(nottftp-server) - kubectl: not in default repos — the bootstrap script adds
https://pkgs.k8s.io/core:/stable:/v1.33/rpm/with--gpg-auto-import-keys php8-yaml: not available in any standard Leap 15.6 repo —kubernerdes.phphas a built-in fallback YAML parser; do not attempt to install this package :::
Knowledge Prerequisites
You do not need to be an expert in every tool, but the following knowledge is assumed throughout the docs:
| Area | What's assumed |
|---|---|
| Linux CLI | ssh, systemctl start/stop/status/enable, journalctl -u <service>, basic file editing with vim or nano |
| Networking | Subnets and CIDR notation, DNS resolution, DHCP basics, what a VIP (virtual IP) is |
| YAML syntax | Indentation rules, strings vs. numbers, lists vs. maps, multi-line strings |
| Kubernetes | Pods, Deployments, Services, Namespaces, Helm installs, kubectl get/describe/logs |
| Airgap concepts | Helpful but not assumed — Airgap Design explains the model from scratch |
If you're new to any of these areas, spending a few hours on the basics now will save many hours of debugging later.