aim-web2.1.0rc9
This commit is contained in:
admin_rb
@@ -0,0 +1,99 @@
|
||||
# AIM authoritative development guidelines
|
||||
|
||||
**Baseline: 3.3.0rc8.** This is the current Core guide. Operator instructions take
|
||||
precedence over earlier project documentation. Keep the built-in terminal in AIM.
|
||||
|
||||
## Product and release ownership
|
||||
|
||||
Core owns domain/execution truth, storage, reusable services and both first-party
|
||||
interfaces. Dependencies point interface -> services/domain/runtime; services must
|
||||
not import `aim.ui` or any add-on. Add-ons consume only `aim.services.v1` or `aimctl`.
|
||||
No Core change may require inspecting or editing an independent add-on's codebase.
|
||||
|
||||
Release complete source ZIPs with SHA-256 sidecars and the operational deployer. No
|
||||
Git/patch dependency, `.patch` file, release manifest, bundled test/validator machinery,
|
||||
cache, inventory, Vault, private key, environment, downloaded package or collection.
|
||||
Do not mutate a published candidate. Every source change updates the product version
|
||||
and CHANGELOG. Service/wire/event 1.0 evolves additively; breaking changes require a
|
||||
separately versioned contract. Product and API versions are not interchangeable.
|
||||
|
||||
## Layout and preservation
|
||||
|
||||
`/etc/ansible/scripts` contains source, pyproject, global `aim.yml`, docs and the WinRM
|
||||
helper. `playbooks` contains the catalog, schemas and report filter plugins. `roles`
|
||||
contains execution roles. Customer `.aim.yml` remains in its customer directory.
|
||||
|
||||
Deployment preserves operator config, inventory/Vault/keys, add-ons, environments and
|
||||
customer assets. Preview first; quiesce writers/runners; maintain source/launcher
|
||||
recovery. Retire only explicitly named old Core documents, never arbitrary Markdown.
|
||||
Do not reset LDAP groups, permissions or ownership recursively. Stable lock inodes and
|
||||
metadata-preserving atomic replacement apply. Source rollback cannot undo remote work.
|
||||
|
||||
## Execution and credentials
|
||||
|
||||
Canonical native runtime: ansible-core 2.19.11. AIM and add-on Python environments may
|
||||
be separate; do not install/upgrade Ansible during discovery or deployment. New service
|
||||
profiles stay opt-in. Require the actual execution UID/groups, owner-only private keys,
|
||||
usable collections and sandbox staging. Check both process/config HOME and passwd/NSS
|
||||
home paths where local delegation expands `~account`. Never override remote_tmp globally,
|
||||
switch UIDs or edit service units to hide a staging/access failure.
|
||||
|
||||
Credentials use bounded one-run providers/private descriptors/sockets, never request
|
||||
JSON, argv, environment, output, examples or persisted plans. Supplied passwords remain
|
||||
native defaults, not forced inventory overrides. Existing Vault unlock retries are
|
||||
pre-launch only. Preserve selection on typos and Ctrl+C cancellation; never replay a
|
||||
launched editor/playbook automatically. Source and prepared revisions are change
|
||||
detectors, not authorization tokens or isolation from uncooperative shell edits.
|
||||
|
||||
## Structured purposeful results
|
||||
|
||||
Use `ansible.builtin.set_stats` with `data.aim_output`, `protocol: aim_output_v1`, a static
|
||||
schema ID, `per_host` matching the declaration and `aggregate: false`. Exactly one
|
||||
publication per host (or one global publication) per execution. Result normalization
|
||||
belongs in runbook roles/filter plugins, not hard-coded playbook branches in Core.
|
||||
|
||||
Declare result shape/scope/required/sensitivity in the catalog. Define bounded types in
|
||||
`playbooks/schemas/`. The generic validator owns type/field/size/lifecycle enforcement;
|
||||
new schemas require no Core dispatch additions. Revalidate at the callback and public
|
||||
boundary. Preserve no_log provenance: final custom stats alone are not authorization
|
||||
to expose data. Unknown custom stats/debug/module results remain private.
|
||||
|
||||
Operation reports, target outcomes and progress are separate. A required missing or
|
||||
invalid report can fail result validation after native exit 0; preserve exit_code and
|
||||
native target stats, and never replay. Interrupted output is indeterminate. On native
|
||||
failure retain available final reports without replacing the original failure.
|
||||
|
||||
Declare operational field meanings precisely: bytes, observed versions, nullable
|
||||
unknowns, bounded fixed error codes. Never guess an installed version from a staged
|
||||
filename, imply a start return means a service stayed running, or call check-mode
|
||||
predictions completed changes. Patch reports must not silently truncate update lists.
|
||||
Checkmk config is parsed and redacted before publication; the filename alone does
|
||||
not make passphrases/MRPE command credentials safe. Raw configuration diffs stay private.
|
||||
|
||||
Windows patching is operator-wave controlled: let the supported `win_updates` module process the currently approved update wave with module reboot disabled, then treat any resulting reboot as the boundary. Post-reboot rediscovery/continuation must be an explicit catalog option defaulting false; never turn a normal patch run into an implicit "keep patching until current" workflow. Preserve bounded per-update HRESULT reporting and never equate `0x80240016` alone with a proven pending reboot.
|
||||
|
||||
## Existing compatibility and Checkmk boundaries
|
||||
|
||||
Keep HTTPS WinRM 5986 and guarded legacy certificate fallback. Preserve standalone
|
||||
local-account token handling. Do not add legacy-only external bootstrap dependencies.
|
||||
Windows bootstrap compatibility is separate from collection/module requirements;
|
||||
never claim every new playbook was tested on Server 2012 R2/PowerShell 4.
|
||||
|
||||
AIM owns catalogued check filenames, not whole directories. Unknown files stay.
|
||||
Windows configuration management owns only `plugins:`; preserve `local`, `mrpe`,
|
||||
`global`, unknown sections and comments. Keep the first-line notice plus section
|
||||
ownership marker. Unmanaged sections are not empty generated mappings. Avoid unmatched
|
||||
quote characters even in inline free-form shell comments. No unrelated firewall policy
|
||||
changes or cleanup expansions in a reporting release.
|
||||
|
||||
AIM-managed persistent Windows Checkmk files use the shared `checkmk_windows_acl` role: enable parent inheritance per file and guarantee well-known SID access for SYSTEM/local Administrators (FullControl) and both application-package principals (ReadAndExecute). Do not add customer-specific administrator/user ACEs, recurse over whole Checkmk directories, or rewrite unknown/operator-file ACLs.
|
||||
|
||||
## Verification and documentation
|
||||
|
||||
Tests live outside the shipped release. Parse/compile sources, validate YAML/Jinja,
|
||||
exercise credential/process/output boundaries and installer rollback. Use native
|
||||
Ansible/collections when available and label simulations distinctly. Record failures,
|
||||
missing dependencies and platform acceptance honestly in `scripts/docs/VALIDATION.md`.
|
||||
Keep exactly one current API, release notes, handoff, sanity checklist and validation
|
||||
record; the documentation index names the authority for each topic. Historical
|
||||
CHANGELOG entries are retained, not represented as present-day capability guarantees.
|
||||
Reference in New Issue
Block a user