Operator guide

This page is the single setup reference for sites that use YAIDAP under UMKIM. It complements the introduction, inventory model, UMKIM integration, and workflows pages.

Canonical implementation detail lives in the UMKIM repo: docs/components/yaidap-integration.md.

How it works

UMKIM does not ship YAIDAP. The hub stores intent (FleetSite provision binding + per-site Ansible YAML). A site jumphost runs the YAIDAP git checkout and inventory tree. Connector Jobs (fleet-ansible-runner → site-provision-connector.yml) SSH to the jumphost and invoke ansible-playbook with --limit on the subject host.

Operator / console / umkim CLI
        │
        ▼
Hub ConfigMap fleet-site-{site}-yaidap-inventory  (YAML files + _meta/)
        │  inventory sync (push bundle)
        ▼
Jumphost: $inventoryPath  (guests, hypervisors, host_vars, group_vars, …)
        │  ansible-playbook @ $yaidapRoot
        ▼
Hypervisors · bare metal · libvirt guests  (SSH-ready Rocky / Proxmox)
        │
        ▼
UMKIM L1: FleetClusterJoin enroll · bootstrap · provision · FleetApp

Default provider noop: skip YAIDAP; enroll SSH-ready hosts with FleetClusterJoin only.

Provider yaidap: use this guide.

Configuration checklist

Complete these before the first provision action:

Step	What	Where
1	FleetSite exists (registry site, not only management seed)	Console Sites or API
2	Provision binding: `provider=yaidap`, jumphost, `inventoryPath`, `sshSecretRef`	`FleetSite.spec.provision` or `umkim site provision set`
3	Hub Secret with jumphost private key	`fleet-console` namespace, e.g. `fleet-site-{site}-provision-ssh`
4	Jumphost accepts that key; passwordless sudo for Ansible if required	Jumphost `authorized_keys`
5	YAIDAP repo on jumphost (`yaidapRoot`)	`umkim site provision yaidap-sync SITE` after `yaidapRepo` / ref set
6	Hub inventory store seeded	Migrate legacy JSON once, or create files via console / CLI
7	`group_vars/all/all.yml` catalogs (`networks`, `storages`, …)	Hub file API or Provisioner inventory editor
8	SSH from jumphost to HV / BM / guest management IPs	Site LAN
9	Optional: cluster intent `{cluster}.yml` + `group_vars/{cluster}.yml`	For `autoApply` FleetClusterJoin

Site bootstrap jumphost (FleetSite.spec.jumphost) may match the provision jumphost but is configured separately for cluster SSH during enroll.

Site binding (FleetSite.spec.provision)

Field	Required	Meaning
`provider`	yes	`yaidap`
`jumphost`	yes	`user@host` or `user@host:port` — SSH target for connector Jobs
`sshSecretRef`	yes	Hub Secret name (private key) in `fleet-console`
`inventoryPath`	yes	Absolute path on the jumphost to this site’s inventory root
`yaidapRoot`	no	YAIDAP checkout on jumphost (default `~/yaidap`)
`yaidapRepo`	no*	Git remote for hub-managed sync
`yaidapRef`	no	Branch, tag, or commit (default `main`)
`yaidapGitSecretRef`	no**	Deploy key Secret for `git@…` remotes
`defaultExtraVars`	no	Non-secret `-e` pairs on every connector run

*Required for POST …/provision/yaidap/sync.
**Required for private SSH git remotes.

CLI example:

umkim site provision set SITE --provider yaidap \
  --jumphost USER@JUMPHOST \
  --ssh-secret fleet-site-SITE-provision-ssh \
  --inventory /opt/yaidap-inventory/SITE \
  --yaidap-root ~/yaidap \
  --yaidap-repo https://github.com/rborso/yaidap.git \
  --yaidap-ref main

Secret keys: id_ed25519 / id_rsa (and optional .pub). The Job mounts them under /root/.ssh on the ansible-runner pod.

Hub inventory store

All editable YAML for the site lives in ConfigMap fleet-site-{site}-yaidap-inventory (file.* keys). Hub-only metadata under _meta/ is never pushed to the jumphost.

File roles (summary)

Path	On jumphost after sync	Purpose
`group_vars/all/all.yml`	yes	`networks`, `storages`, site defaults
`hypervisors.yml`	yes	Hypervisor group (`kind: hypervisor`)
`guests.yml`	yes (VM index on hub)	`guests.hosts`; hub merges `bare_metals.yml` → `external.hosts` on jumphost
`bare_metals.yml`	hub only	Bare-metal cluster nodes (`kind: bare_metal`)
`{cluster}.yml`	yes	Ansible group `hosts:` list
`group_vars/{cluster}.yml`	yes	Fleet cluster intent (`topology`, `autoApply`, `mode`, …)
`host_vars/{name}.yml`	yes	Uplinks, disks, `vm_location`, TempXE discovery
`_meta/*.json`	no	Sync phase, guest provision phase, revisions, import preview

Jumphost-only (never overwritten by hub push): controllers.yml, routers.yml, generated/ (discovery drafts, PXE tarballs).

Full field semantics: Inventory model.

Sync lifecycle

`syncPhase` (`_meta/meta.json`)	Meaning
`pending`	Never synced or freshly migrated
`dirty`	Hub edits not on jumphost
`syncing`	Push Job running
`synced`	Jumphost matches last successful push

umkim site inventory sync SITE --wait

Provision actions that need fresh YAML pre-sync the hub bundle automatically.

Migrate once from legacy hub JSON:

umkim site inventory migrate SITE

Setting up inventory schema (greenfield site)

Work top-down: shared catalogs, then host kinds, then cluster membership.

1. Shared catalogs (`group_vars/all/all.yml`)

Define at least:

networks — named L2/L3 objects referenced by uplink attachments.
storages — hypervisor pools and guest disk backends (OS family scoped with os:).

See examples in Inventory model.

Set site-wide defaults here (configure_firewalld, image URLs, etc.) per YAIDAP docs.

2. Hypervisors (`hypervisors.yml` + `host_vars/`)

For each libvirt (or Proxmox) host:

Add hostname under hypervisors.yml with ansible_host.
Create host_vars/{hv}.yml with uplinks (MAC on physical NICs), os, and prepare-related fields.
Optional PXE discovery stub: tempxe_discovery.enabled: true + uplink mac_address.

Console: Add hypervisor seeds these files.

Run discover (SSH) or discover_pxe (confirm) after sync; import apply promotes generated/ drafts.

3. VM guests (`guests.yml` + `host_vars/`)

For each libvirt guest:

Add entry under guests.hosts with ansible_host and vm_location (least-utilized or concrete HV).
Create host_vars/{guest}.yml with provisioning_provider: libvirt, uplinks, disks, os.
Do not put bare-metal nodes in guests.yml on the hub.

Console: Add VM guest uses templates (vm_location: least-utilized by default).

install_os: keep install_os: false (or omit) in host_vars. The hub adds -e install_os=true only for action install_bm.

4. Bare-metal cluster nodes (`bare_metals.yml` + `host_vars/`)

For TempXE-installed metal used as K3s nodes:

Add host under bare_metals.yml.
host_vars/{node}.yml with disks, uplinks, optional tempxe_discovery for PXE discover.
On sync, hub content appears under jumphost guests.yml → external.hosts.

Actions: discover_pxe (confirm), install_bm (confirm), then cluster enroll.

5. Cluster intent (optional automation)

lab-ha-0.yml          # hosts: [guest01, guest02, guest03]
group_vars/lab-ha-0.yml   # topology, autoApply, controlPlaneVip, mode: enroll

Members are listed only in the root {cluster}.yml, not duplicated in group_vars.

When autoApply: true and all member guests are Ready, the controller can create FleetClusterJoin. Manual: umkim site host cluster-apply SITE guest01.

6. Validate and push

Resolve CHANGE_ME placeholders (import preview warnings). Then:

umkim site inventory sync SITE --wait

On the jumphost you can run YAIDAP validate-all.yml before first prepare / create_vm.

Provision actions (hub → YAIDAP)

Action	Confirm	Typical use
`discover`	no	SSH hardware draft
`discover_pxe`	yes	TempXE collector (HV or BM in inventory)
`install_bm`	yes	Full OS install via TempXE
`plan_vm`	no	Dry-run placement
`create_vm`	no*	Libvirt guest create
`destroy`	yes	Remove guest
`status`	no	TempXE status

*Re-create on Ready guest with fixed vm_location may use yaidap_recreate=true; console may require confirm.

Results: parse YAIDAP_RESULT (schema: yaidap.integration.v1) from Job logs — handoff, vm_location, placement.

Full mapping table: UMKIM integration.

Editing surfaces

Surface	Use
Console Sites → Provisioner inventory	YAML tree, sync, import, Add VM / HV / BM
Console Sites → Site hosts	Provision, plan, discover, cluster apply
`umkim site inventory files …`	File CRUD
`umkim site provision run …`	Actions
HTTP API	OpenAPI in UMKIM `controllers/fleet-site/openapi.yaml`

Boundaries (do not cross)

Keep YAIDAP networks / uplinks / storages in Ansible YAML — not in Fleet CRDs.
YAIDAP stops at SSH-ready; K3s, OCM, Harbor, FleetApp are UMKIM-only.
One running provision action per site; wait for Jobs fleet-site-prov-* / fleet-site-inv-*.

Homelab reference

The published umkim tree does not include examples/homelab/. Use the commands on this page, YAIDAP inventory/example/, and playbooks/flows/site-provision-yaidap.yml.