eric/ansible-role-audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document the Audita version 2 role migration

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 13:47:33 +00:00
parent 52f67fe389
commit c3dd59f5ac
1 changed files with 68 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
README.md
View File

@@ -7,6 +7,9 @@ manage root-owned application state.
## Variables
Every invocation requires caller-supplied `audita_backends` and
`audita_llm_proposal_profile`. Neither has a role default.
```yaml
audita_version: v2.0.1
audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git
@@ -22,7 +25,6 @@ audita_config_directory_mode: "0755"
audita_config_file_mode: "0644"
audita_config_version: 2
audita_profiles_dir: null
# Required caller inputs: audita_backends, audita_llm_proposal_profile
audita_pipeline_modules: null
audita_output_schema: null
audita_llm_validation_profile: null
@@ -72,38 +74,83 @@ standalone defaults are `root:root`, directory mode `0755`, and file mode
`0644`. Composing roles may override these generic configuration inputs for
their own deployment policy.
Backend credential references name environment variables; they must never
contain secret values. The repository-local integration suite validates the
rendered file with Audita rather than executing the CLI during production
convergence.
Backend `credential` values are explicit environment-variable reference names,
not secret values. Every surviving reference must resolve to a nonempty value
when Audita loads configuration, including references on unselected backends.
An omitted or null credential permits unauthenticated local use. The role does
not supply secret values, start a service, or probe profiles during convergence.
## Migrating from the version-1 role
This revision renders version-2 configuration only. Existing version-1 users
can retain the previous role revision while planning a coordinated migration.
The old fields have no compatibility aliases:
| Previous role inputs | Version-2 destination |
| --- | --- |
| `audita_llm_{proposal,validation}_base_url` | `audita_backends.<id>.endpoint`; both selections may share one backend. |
| `audita_llm_{proposal,validation}_api_key_env` | `audita_backends.<id>.credential`, an explicit environment-variable name. |
| `audita_concurrency_{total_llm,proposal_llm,validation_llm}` | `audita_backends.<id>.concurrency` and optional `queue_capacity`; capacity is shared by roles using that backend. |
| `audita_llm_{proposal,validation}_model` | Model in caller-owned PromptKit profile files, selected by `audita_llm_proposal_profile` and optional `audita_llm_validation_profile`. |
| `audita_llm_{proposal,validation}_timeout` | Per-attempt `timeout_seconds` in profile files; `audita_llm_operation_timeout` separately bounds a logical call. |
| `audita_llm_{proposal,validation}_max_retries` | `audita_llm_transient_retries` and `audita_llm_repair_attempts` are separate native budgets; old values do not map directly. |
| Three `audita_normalization_*` gap/duration values | Same role variables, now numeric seconds rather than duration strings. |
| `audita_diagnostics_retention` | Removed; use `audita_diagnostics_debug` and `audita_diagnostics_work_dir` for v2 debug behavior. Reporting uses `audita_reporting_enabled` and `audita_reporting_stdout_dir`. |
Omitting `audita_llm_validation_profile` lets Audita inherit the proposal
selection. `audita_llm_operation_timeout` is a Go duration string, while
normalization times are numbers. See the tagged
[v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)
and [configuration reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md)
for exact validation and precedence rules.
## Example
Inventory can supply the required choices for a local backend:
```yaml
# host_vars/audita_host.yml (caller-owned)
audita_backends:
local:
endpoint: http://127.0.0.1:11434/v1
credential: null
audita_llm_proposal_profile: local-proposal
```
The caller also supplies `profiles/local-proposal.yaml` beside the managed
configuration, or selects another directory with `audita_profiles_dir`:
```yaml
# profiles/local-proposal.yaml (caller-owned)
id: local-proposal
backend: local
model: replace-with-an-available-local-model
timeout_seconds: 30
```
Choose a model available at the selected endpoint. These profile files must
exist before invoking Audita, but need not exist before applying the role.
The role neither deploys them nor selects a ConfigKit overlay.
```yaml
- hosts: audita_hosts
roles:
- role: ansible-role-audita
vars:
audita_backends:
local:
endpoint: http://127.0.0.1:11434/v1
credential: null
audita_llm_proposal_profile: local-proposal
```
The caller supplies `profiles/local-proposal.yaml` beside the managed
configuration before invoking Audita.
## Validation
The integration driver installs pinned collection dependencies, runs syntax
checking and ansible-lint, validates a caller-supplied local configuration and
profile offline, and requires clean repeated convergence. It also tests a
caller-supplied Go executable with dependency management disabled after removing
the managed binary. On a fresh host, the role may install Git through APT and
the Go Snap. The test uses a private temporary configuration and profile root;
the role still manages the local source checkout and binary. Cleanup removes
only the private fixture root:
checking and ansible-lint, and applies the role with local fixture backends and
caller-owned profiles. It checks the temporary configuration with native
`config validate` and the effective settings and profiles views, then requires
clean repeated convergence. It also tests a caller-supplied Go executable with
dependency management disabled after removing the managed binary. The fixture
configuration and sibling `profiles/` directory live under the script's private
temporary root, which cleanup removes. The role still mutates the local managed
source checkout and binary; an existing system configuration is not replaced.
These offline checks do not establish provider connectivity, runtime report
behavior, or compatibility with the unchanged D&D suite:
```sh
tests/integration