Ansible/scripts/addons/webgui/docs/MIGRATION-3.1.md

Historical reference retained from the preceding release. Current deployment/contracts and evidence are in DEPLOYMENT.md, REPORTS.md, JOURNAL.md and VERIFICATION.md. Do not treat old limitations or tests as current qualification.

Historical major-migration guide for the 1.x-to-2.x architecture. An existing 2.0.0rc8 deployment uses the ordinary 2.1 update in DEPLOYMENT.md; no schema change or migration acknowledgement is needed. Current capabilities are in API.md.

Major migration: WebGUI 1.x / rc18 -> WebGUI 2.0 / AIM 3.1

Read CORE-3.1-REVIEW.md first. This is an explicit major migration. Core and add-on are separate releases with separate backups and rollback decisions.

Before downtime

1. Let active jobs finish; cancel deliberately only if their remote effects are understood.
2. Back up the old core using its OWN deployment procedure. Back up the WebGUI's source/config/units/database with its managed deployment checkpoint. Do not reset users or remove /var/lib/aim/webgui.
3. Deploy AIM 3.2.1rc2 independently using its included guide. Check terminal AIM first. Do not copy core into the old WebGUI tree or install WebGUI into core's interpreter.
4. Choose an existing non-root execution account, normally svc_bf-ansible. It must already satisfy AIM required_group, read its config/inventory/Vault, own each selected customer key 0600, and see native collections. The add-on does not provision these core permissions. runtime.private_key_owner does not migrate old keys or switch UID.
5. Check aimctl as that account, not merely from a root shell:

sudo -u svc_bf-ansible /usr/local/bin/aimctl   --config /etc/ansible/scripts/aim.yml capabilities
printf '%s\n' '{"api_version":"1.0","operation":"list_customers"}' |   sudo -u svc_bf-ansible /usr/local/bin/aimctl   --config /etc/ansible/scripts/aim.yml request

The core config remains operator-owned. Its actual 3.1 settings include addons.execution_enabled, runtime.ansible_playbook and runtime.private_key_owner (NOT the earlier proposed execution_user/runtime_group fields). Configure/qualify those using the core guide. The add-on never edits them.

The core acquires a stable customer .aim.lock during execution. The executor needs access to that lock, or creation permission if it does not exist; a read-only customer directory without an accessible lock is not sufficient. Use the core/operator's permission procedure rather than widening the whole tree from WebGUI.

Activation

Unpack the new ZIP into a fresh staging path and run:

sudo python3 deploy/deploy.py update --migrate-core

The explicit flag acknowledges: schema 4, stopped legacy pending/running work, retirement of old key-export sudo bridge and its known worker capability drop-in, HTTP API v2, a new executor service and release-config replacement.

The installer stages an isolated WebGUI venv/assets, probes the real public core metadata as the selected executor account, checkpoints old files, stops add-on services, migrates state, replaces source/config/units, then starts executor, web and the opt-in queue worker. It never stops terminal AIM or writes core files. Unknown systemd drop-ins block installation for deliberate operator review.

What is preserved

Users/password hashes/sessions, named admin onboarding, grants, audit, selections, all old job records/events, and all saved plan payloads. Pending/queued old-core jobs become blocked; running ones become interrupted. Their state is not replayed. Historical duplicates in saved-plan names remain separate records.

Legacy saved plans are reusable INPUTS only: open one, use its New run link and review mode/key handling again. Old Custom credentials cannot silently become native inventory credentials. A new valid review is required; no credentials are migrated.

What is retired

Private core imports, rc18 adapter, command rewriting, private Ansible credential resolver/strategy, sudo key export, CAP_SETUID/CAP_SETGID worker capability grant and raw console interception. Known old helper/sudoers/drop-in files are backed up and removed. There is no need to give aim-web canonical key read access.

Rollback

Schema4 cannot be opened by old schema 3 WebGUI. Downgrading requires the explicit --restore-auth-db flag, with loss of changes since that snapshot and possible restoration of older passwords. Services and config/code/venv must match the snapshot. Restoring a 1.x WebGUI while AIM 3.1 remains installed is NOT a working rollback: the installer restores the files/database but leaves legacy services stopped/disabled. Coordinate an independent core rollback before enabling them. Core is never rolled back by this add-on. Interrupted remote operations are never undone automatically.

Unsupported old behavior

There is no Custom forced credential override or password-only verification in core API 1.0. No raw task/host output. Platform-group selection remains; recursive subgroup paths are unavailable. These limitations are shown in the interface and are recorded for an additive core extension, not bypassed through private access.

Executor HOME and host trust

The release profile sets [core] home = "/var/lib/aim-web-executor". aimctl and native commands use that separate writable HOME, not /root or WebGUI's private SQLite home. The executor remains the configured existing UID; no identity is changed by HOME. Install independently verified SSH host records under the effective SSH UserKnownHostsFile, owned by the execution account, or the already-reviewed system /etc/ssh/ssh_known_hosts policy. Process HOME alone does not select OpenSSH's known_hosts path. Do not blindly trust ssh-keyscan output. Existing per-user collections under the old home are not automatically copied: use the core's documented runtime.ansible_collections_path configuration if required. System collections remain native-core-discovered.

The shipped systemd profile targets the documented /etc/ansible inventory layout. Nonstandard inventory roots require a separately reviewed ReadWritePaths service profile for core locks; this installer does not inspect private config to infer it.