Install the hub

Experimental and unsupported: hub installation changes hosts and creates control-plane credentials. Use an isolated, reviewed environment and validate the result before relying on it.

Use a fresh inventory generated from the hub-only template. Set the hub identity, public address, DNS, and encrypted vault values with deployment-specific values; do not put them in documentation or source control.

1. Create inventory

cd <workspace>/umkim
./scripts/bootstrap-hub-inventory.sh
export INV="-i inventory/hosts.yml -i inventory/hosts-from-hub.yml"
./scripts/preflight-hub-inventory.sh
ansible $INV -m ping hub

Edit the generated inventory files and replace every template value before continuing. Per-site ingress / hub-gateway profiles live in examples/site-profiles/.

2. Create encrypted secrets

Choose one path. Store the vault password and an encrypted vault backup outside the repository. See secrets.

Manual:

cp docs/vault.example.yml inventory/group_vars/all/vault.yml
# Edit inventory/group_vars/all/vault.yml — set all required secrets
openssl rand -base64 32 > ~/.umkim-vault-pass
chmod 600 ~/.umkim-vault-pass
env -u ANSIBLE_VAULT_PASSWORD_FILE ansible-vault encrypt \
  inventory/group_vars/all/vault.yml \
  --vault-password-file ~/.umkim-vault-pass \
  --encrypt-vault-id default

Generated:

./scripts/generate-vault-secrets.sh --encrypt \
  --vault-pass-file ~/.umkim-vault-pass

Use --force only when intentionally overwriting an existing vault.yml.

export ANSIBLE_VAULT_PASSWORD_FILE=~/.umkim-vault-pass
./scripts/preflight-v1.sh

3. Install and verify

export INV="-i inventory/hosts.yml -i inventory/hosts-from-hub.yml"
export ANSIBLE_VAULT_PASSWORD_FILE=~/.umkim-vault-pass
./scripts/install-hub.sh
./scripts/verify-hub-install.sh

Image builds can take a long time. To resume a known failed phase, use a targeted tag:

ansible-playbook $INV hub-install.yml -l hub --tags harbor_push_fleet

After the hub verifies, use the authenticated console to create a non-management site and a workload cluster. Optional GPU inference and the hub LiteLLM proxy are not installed by install-hub.sh — see fleet-llm. The hub lifecycle describes the ordered services; secrets and security describe the required safeguards.

Teardown and reinstall

./scripts/teardown-hub.sh --confirm deletes console-managed workload clusters by default (cleanupKubernetes=true), then removes the hub stack (K3s, Harbor, controllers, Traefik, WireGuard). Inventory and encrypted vault under inventory/ are kept.

For a hub-only wipe while spokes keep independent K3s:

./scripts/teardown-hub.sh --confirm --skip-cluster-delete

Then ./scripts/install-hub.sh and ./scripts/verify-hub-install.sh when reinstalling. See hub install lifecycle.

4. WireGuard operator client

Console and management APIs are reached over the hub overlay. After install, generate a split-tunnel client on the hub or a trusted Ansible controller:

export INV="-i inventory/hosts.yml -i inventory/hosts-from-hub.yml"
./scripts/wg-dev-client.sh <client-name>

Copy the generated config to your operator device and bring it up. Treat the config as a secret. See WireGuard clients.