0aee2c0981
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
64 lines
4.2 KiB
Markdown
64 lines
4.2 KiB
Markdown
# Fleet Configuration Management
|
|
|
|
This book documents the local roster-v2 desired-state control plane delivered under issue #758. The normative requirements are the [FCM section of the repository PRD](../PRD.md#fleet-declarative-configuration-management-workstream-fcm-758), not the older fleet-suite or observability planning pages.
|
|
|
|
## Authority boundary
|
|
|
|
`<MOSAIC_HOME>/fleet/roster.yaml` is the sole writable desired-state authority for local fleet membership, launch policy, and persisted lifecycle. Generated environment files, systemd enablement, tmux sessions, heartbeat files, and status output are derived or observed. Rebuild projections from the roster; never edit them as desired state.
|
|
|
|
This control plane is local tmux/systemd only. Remote/SSH entries and connectors are inventory, not reconciliation targets. Arbitrary commands, channels, secret references, gateway catalog convergence, and UI configuration storage are outside this workstream. `mos-comms` is temporary transport glue, not permanent fleet architecture.
|
|
|
|
## Choose the right workflow
|
|
|
|
1. **Need to inspect intent?** Read the roster and use `mosaic fleet get`; see [desired versus observed state](concepts/desired-vs-observed-state.md).
|
|
2. **Need to inspect reality?** Use `status` or `doctor`; use `verify` for a strict non-zero drift/ownership gate. These commands do not repair anything.
|
|
3. **Need to change membership or persisted policy?** Use generation-guarded `plan`, `create`, `update`, or `delete`; see [safe CRUD](how-to/create-update-delete-agent.md).
|
|
4. **Need a one-time runtime action?** Use `start`, `stop`, or `restart`. These do not change persisted desired state.
|
|
5. **Need convergence?** Review `apply --dry-run`, resolve blockers, then use `apply` with the same current generation; see [reconcile and recover](operations/reconcile-and-recover.md).
|
|
6. **Need v1 migration evidence?** Use preview only. Cutover, canary, and rollback remain held for FCM-M4-002.
|
|
7. **Need the gateway-backed agent catalog?** That is the separate `mosaic agent` surface, not local fleet desired state.
|
|
|
|
## Concepts
|
|
|
|
- [Desired versus observed state](concepts/desired-vs-observed-state.md)
|
|
- [Identity, class, runtime, provider, and model](concepts/identity-class-runtime.md)
|
|
- [Role authority and leases](concepts/role-authority-and-leases.md)
|
|
- [Generated environment launch chain](concepts/generated-env-launch-chain.md)
|
|
|
|
## Operator how-to
|
|
|
|
- [Create, inspect, update, and delete](how-to/create-update-delete-agent.md)
|
|
- [Start, stop, restart, and reconcile](how-to/start-stop-restart.md)
|
|
- [Configure an interaction instance](how-to/configure-tess-interaction.md)
|
|
- [Configure a validator instance](how-to/configure-ultron-validator.md)
|
|
- [Customize roles](how-to/customize-roles.md)
|
|
|
|
## Operations and recovery
|
|
|
|
- [Reconcile and recover](operations/reconcile-and-recover.md)
|
|
- [Environment quarantine](operations/env-quarantine.md)
|
|
- [Systemd/tmux troubleshooting](operations/systemd-tmux-troubleshooting.md)
|
|
- [Backup and restore boundary](operations/backup-restore.md)
|
|
- [Upgrade and asset-drift hold](operations/upgrade-assets.md)
|
|
|
|
## Reference and migration
|
|
|
|
- [Roster v2 fields](reference/roster-v2-fields.md) · [executable JSON Schema](reference/roster-v2.schema.json) · [validated example](examples/roster-v2.yaml)
|
|
- [CLI and exit codes](reference/cli.md)
|
|
- [Role classes](reference/role-classes.md)
|
|
- [Lifecycle transitions](reference/lifecycle-transitions.md)
|
|
- [Status and drift](reference/status-and-drift.md)
|
|
- [Generated environment boundary](reference/generated-env-boundary.md)
|
|
- [v1-to-v2 preview](migration/v1-to-v2.md)
|
|
- [Example/profile dispositions](migration/example-profile-disposition.md)
|
|
- [Legacy class aliases](migration/legacy-class-aliases.md)
|
|
|
|
## Acceptance evidence and holds
|
|
|
|
- [M0/M5 IA checklist](FLEET-CONFIG-DOCS-IA-CHECKLIST.md)
|
|
- [Legacy example/profile inventory](LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md)
|
|
- [M5 closure evidence](../reports/documentation/758-fleet-config-ia-closure.md)
|
|
- [Approved-existing deferrals and live-action holds](../reports/deferred/758-fleet-config-deferrals.md)
|
|
|
|
The canonical publishing source remains this repository. This card does not publish externally, run a migration, operate a live fleet, or close parent issue #758.
|