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

Migrate the standalone Audita role to version 2 configuration

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 13:42:17 +00:00
parent 66ebea9a47
commit 6137ff217b
6 changed files with 159 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@@ -8,7 +8,7 @@ manage root-owned application state.
## Variables
```yaml
audita_version: v0.9.1
audita_version: v2.0.1
audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git
audita_source_dir: /usr/local/src/audita
audita_binary_path: /usr/local/bin/audita
@@ -20,22 +20,16 @@ audita_config_owner: root
audita_config_group: root
audita_config_directory_mode: "0755"
audita_config_file_mode: "0644"
audita_config_version: 1
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_proposal_base_url: null
audita_llm_proposal_model: null
audita_llm_proposal_api_key_env: null
audita_llm_proposal_timeout: null
audita_llm_proposal_max_retries: null
audita_llm_validation_base_url: null
audita_llm_validation_model: null
audita_llm_validation_api_key_env: null
audita_llm_validation_timeout: null
audita_llm_validation_max_retries: null
audita_concurrency_total_llm: null
audita_concurrency_proposal_llm: null
audita_concurrency_validation_llm: null
audita_llm_validation_profile: null
audita_llm_transient_retries: null
audita_llm_repair_attempts: null
audita_llm_operation_timeout: null
audita_validation_max_prompt_tokens: null
audita_chunking_target_sections: null
audita_chunking_max_section_tokens: null
audita_chunking_min_section_tokens: null
@@ -48,8 +42,10 @@ audita_thresholds_homophones: null
audita_thresholds_spoken_word: null
audita_thresholds_grammar: null
audita_context_description: null
audita_reporting_enabled: null
audita_reporting_stdout_dir: null
audita_diagnostics_debug: null
audita_diagnostics_work_dir: null
audita_diagnostics_retention: null
```
When `audita_manage_build_dependencies` is `false`, Git and the executable
@@ -63,22 +59,23 @@ selecting `audita_version`. The role builds Audita directly to
the checkout changes or the binary is absent. The source tree is recursively
owned by `root:root`; the binary is `root:root` mode `0755`.
The configuration variables map directly to Audita's versioned YAML fields.
Every optional variable defaults to `null`; null values and their empty parent
sections are omitted, allowing Audita to retain ownership of its built-in
The configuration variables map directly to Audita's version-2 YAML fields.
`audita_backends` and `audita_llm_proposal_profile` are required caller inputs;
the role has no defaults for them. Callers own the selected PromptKit profile
files. Every optional variable defaults to `null`; null values and their empty
parent sections are omitted, allowing Audita to retain ownership of its built-in
defaults. `audita_config_version` always renders as `version` and defaults to
`1`. The role manages `audita_config_path | dirname` and the resulting file
`2`. The role manages `audita_config_path | dirname` and the resulting file
with the `audita_config_owner`, `audita_config_group`,
`audita_config_directory_mode`, and `audita_config_file_mode` inputs. The
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.
LLM API-key settings name environment variables through
`audita_llm_proposal_api_key_env` and `audita_llm_validation_api_key_env`; 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 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.
## Example
@@ -86,25 +83,27 @@ production convergence.
- 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, and validates the default configuration with Audita
before requiring clean repeated convergence. It also covers one representative
field-specific configuration with nested values, null omission, and intentional
falsey values, then validates it natively. A combined recovery scenario proves
that a missing binary is rebuilt with a caller-supplied Go executable while
dependency management is disabled. Audita currently has no native
release-identity command, so the suite intentionally does not use a source
commit as a version-test proxy.
On a fresh host, default convergence may also install Git through APT, refresh
the APT cache, and install the Go Snap. Application state is limited to
`/usr/local/src/audita`, `/usr/local/bin/audita`, and
`/usr/local/etc/audita/config.yml`; temporary test-specific files remain inside
the suite's private temporary directory. The suite restores the default
deployment during cleanup:
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:
```sh
tests/integration

27
defaults/main.yml
View File

@@ -1,5 +1,5 @@
---
audita_version: v0.9.1
audita_version: v2.0.1
audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git
audita_source_dir: /usr/local/src/audita
audita_binary_path: /usr/local/bin/audita
@@ -11,22 +11,15 @@ audita_config_owner: root
audita_config_group: root
audita_config_directory_mode: "0755"
audita_config_file_mode: "0644"
audita_config_version: 1
audita_config_version: 2
audita_profiles_dir: null
audita_pipeline_modules: null
audita_output_schema: null
audita_llm_proposal_base_url: null
audita_llm_proposal_model: null
audita_llm_proposal_api_key_env: null
audita_llm_proposal_timeout: null
audita_llm_proposal_max_retries: null
audita_llm_validation_base_url: null
audita_llm_validation_model: null
audita_llm_validation_api_key_env: null
audita_llm_validation_timeout: null
audita_llm_validation_max_retries: null
audita_concurrency_total_llm: null
audita_concurrency_proposal_llm: null
audita_concurrency_validation_llm: null
audita_llm_validation_profile: null
audita_llm_transient_retries: null
audita_llm_repair_attempts: null
audita_llm_operation_timeout: null
audita_validation_max_prompt_tokens: null
audita_chunking_target_sections: null
audita_chunking_max_section_tokens: null
audita_chunking_min_section_tokens: null
@@ -39,5 +32,7 @@ audita_thresholds_homophones: null
audita_thresholds_spoken_word: null
audita_thresholds_grammar: null
audita_context_description: null
audita_reporting_enabled: null
audita_reporting_stdout_dir: null
audita_diagnostics_debug: null
audita_diagnostics_work_dir: null
audita_diagnostics_retention: null

96
meta/argument_specs.yml
View File

@@ -55,6 +55,14 @@ argument_specs:
type: int
required: true
description: Version of the Audita configuration schema.
audita_profiles_dir:
type: path
required: false
description: Optional caller-managed PromptKit profile directory.
audita_backends:
type: dict
required: true
description: Native backend mapping supplied by the caller.
audita_pipeline_modules:
type: list
elements: str
@@ -64,58 +72,30 @@ argument_specs:
type: str
required: false
description: Optional output schema.
audita_llm_proposal_base_url:
audita_llm_proposal_profile:
type: str
required: true
description: Caller-selected proposal PromptKit profile ID.
audita_llm_validation_profile:
type: str
required: false
description: Optional proposal LLM base URL.
audita_llm_proposal_model:
type: str
required: false
description: Optional proposal LLM model.
audita_llm_proposal_api_key_env:
type: str
required: false
description: Optional proposal LLM API key environment variable name.
audita_llm_proposal_timeout:
type: raw
required: false
description: Optional proposal LLM timeout in seconds or duration form.
audita_llm_proposal_max_retries:
description: Optional validation PromptKit profile ID; omission inherits proposal.
audita_llm_transient_retries:
type: int
required: false
description: Optional proposal LLM retry count.
audita_llm_validation_base_url:
description: Optional additional transient attempts per generation.
audita_llm_repair_attempts:
type: int
required: false
description: Optional additional structural repair generations.
audita_llm_operation_timeout:
type: str
required: false
description: Optional validation LLM base URL.
audita_llm_validation_model:
type: str
required: false
description: Optional validation LLM model.
audita_llm_validation_api_key_env:
type: str
required: false
description: Optional validation LLM API key environment variable name.
audita_llm_validation_timeout:
type: raw
required: false
description: Optional validation LLM timeout in seconds or duration form.
audita_llm_validation_max_retries:
description: Optional logical-operation deadline as a Go duration.
audita_validation_max_prompt_tokens:
type: int
required: false
description: Optional validation LLM retry count.
audita_concurrency_total_llm:
type: int
required: false
description: Optional total LLM concurrency.
audita_concurrency_proposal_llm:
type: int
required: false
description: Optional proposal LLM concurrency.
audita_concurrency_validation_llm:
type: int
required: false
description: Optional validation LLM concurrency.
description: Optional validation batching token budget.
audita_chunking_target_sections:
type: int
required: false
@@ -129,17 +109,17 @@ argument_specs:
required: false
description: Optional minimum section token count.
audita_normalization_max_segment_gap:
type: raw
type: float
required: false
description: Optional maximum segment gap in seconds or duration form.
description: Optional maximum segment gap in numeric seconds.
audita_normalization_ellipsis_gap:
type: raw
type: float
required: false
description: Optional ellipsis gap in seconds or duration form.
description: Optional ellipsis gap in numeric seconds.
audita_normalization_max_segment_duration:
type: raw
type: float
required: false
description: Optional maximum segment duration in seconds or duration form.
description: Optional maximum segment duration in numeric seconds.
audita_normalization_max_segment_tokens:
type: int
required: false
@@ -164,11 +144,19 @@ argument_specs:
type: str
required: false
description: Optional transcript context description.
audita_reporting_enabled:
type: bool
required: false
description: Optional ordinary report-bundle policy.
audita_reporting_stdout_dir:
type: str
required: false
description: Optional report directory for stdout output.
audita_diagnostics_debug:
type: bool
required: false
description: Optional detailed debug-artifact policy.
audita_diagnostics_work_dir:
type: str
required: false
description: Optional diagnostics work directory.
audita_diagnostics_retention:
type: str
required: false
description: Optional diagnostics retention policy.

96
templates/config.yml.j2
View File

@@ -1,4 +1,22 @@
version: {{ audita_config_version }}
version: {{ audita_config_version | to_json }}
{% if audita_profiles_dir is not none %}
profiles_dir: {{ audita_profiles_dir | to_json }}
{% endif %}
backends: {{ audita_backends | to_json }}
llm:
proposal_profile: {{ audita_llm_proposal_profile | to_json }}
{% if audita_llm_validation_profile is not none %}
validation_profile: {{ audita_llm_validation_profile | to_json }}
{% endif %}
{% if audita_llm_transient_retries is not none %}
transient_retries: {{ audita_llm_transient_retries | to_json }}
{% endif %}
{% if audita_llm_repair_attempts is not none %}
repair_attempts: {{ audita_llm_repair_attempts | to_json }}
{% endif %}
{% if audita_llm_operation_timeout is not none %}
operation_timeout: {{ audita_llm_operation_timeout | to_json }}
{% endif %}
{% if audita_pipeline_modules is not none %}
pipeline:
modules: {{ audita_pipeline_modules | to_json }}
@@ -7,56 +25,9 @@ pipeline:
output:
schema: {{ audita_output_schema | to_json }}
{% endif %}
{% if audita_llm_proposal_base_url is not none or audita_llm_proposal_model is not none or audita_llm_proposal_api_key_env is not none or audita_llm_proposal_timeout is not none or audita_llm_proposal_max_retries is not none or audita_llm_validation_base_url is not none or audita_llm_validation_model is not none or audita_llm_validation_api_key_env is not none or audita_llm_validation_timeout is not none or audita_llm_validation_max_retries is not none %}
llm:
{% if audita_llm_proposal_base_url is not none or audita_llm_proposal_model is not none or audita_llm_proposal_api_key_env is not none or audita_llm_proposal_timeout is not none or audita_llm_proposal_max_retries is not none %}
proposal:
{% if audita_llm_proposal_base_url is not none %}
base_url: {{ audita_llm_proposal_base_url | to_json }}
{% endif %}
{% if audita_llm_proposal_model is not none %}
model: {{ audita_llm_proposal_model | to_json }}
{% endif %}
{% if audita_llm_proposal_api_key_env is not none %}
api_key_env: {{ audita_llm_proposal_api_key_env | to_json }}
{% endif %}
{% if audita_llm_proposal_timeout is not none %}
timeout: {{ audita_llm_proposal_timeout | to_json }}
{% endif %}
{% if audita_llm_proposal_max_retries is not none %}
max_retries: {{ audita_llm_proposal_max_retries | to_json }}
{% endif %}
{% endif %}
{% if audita_llm_validation_base_url is not none or audita_llm_validation_model is not none or audita_llm_validation_api_key_env is not none or audita_llm_validation_timeout is not none or audita_llm_validation_max_retries is not none %}
validation:
{% if audita_llm_validation_base_url is not none %}
base_url: {{ audita_llm_validation_base_url | to_json }}
{% endif %}
{% if audita_llm_validation_model is not none %}
model: {{ audita_llm_validation_model | to_json }}
{% endif %}
{% if audita_llm_validation_api_key_env is not none %}
api_key_env: {{ audita_llm_validation_api_key_env | to_json }}
{% endif %}
{% if audita_llm_validation_timeout is not none %}
timeout: {{ audita_llm_validation_timeout | to_json }}
{% endif %}
{% if audita_llm_validation_max_retries is not none %}
max_retries: {{ audita_llm_validation_max_retries | to_json }}
{% endif %}
{% endif %}
{% endif %}
{% if audita_concurrency_total_llm is not none or audita_concurrency_proposal_llm is not none or audita_concurrency_validation_llm is not none %}
concurrency:
{% if audita_concurrency_total_llm is not none %}
total_llm: {{ audita_concurrency_total_llm | to_json }}
{% endif %}
{% if audita_concurrency_proposal_llm is not none %}
proposal_llm: {{ audita_concurrency_proposal_llm | to_json }}
{% endif %}
{% if audita_concurrency_validation_llm is not none %}
validation_llm: {{ audita_concurrency_validation_llm | to_json }}
{% endif %}
{% if audita_validation_max_prompt_tokens is not none %}
validation:
max_prompt_tokens: {{ audita_validation_max_prompt_tokens | to_json }}
{% endif %}
{% if audita_chunking_target_sections is not none or audita_chunking_max_section_tokens is not none or audita_chunking_min_section_tokens is not none %}
chunking:
@@ -73,13 +44,13 @@ chunking:
{% if audita_normalization_max_segment_gap is not none or audita_normalization_ellipsis_gap is not none or audita_normalization_max_segment_duration is not none or audita_normalization_max_segment_tokens is not none %}
normalization:
{% if audita_normalization_max_segment_gap is not none %}
max_segment_gap: {{ audita_normalization_max_segment_gap | to_json }}
max_segment_gap: {{ audita_normalization_max_segment_gap | float | to_json }}
{% endif %}
{% if audita_normalization_ellipsis_gap is not none %}
ellipsis_gap: {{ audita_normalization_ellipsis_gap | to_json }}
ellipsis_gap: {{ audita_normalization_ellipsis_gap | float | to_json }}
{% endif %}
{% if audita_normalization_max_segment_duration is not none %}
max_segment_duration: {{ audita_normalization_max_segment_duration | to_json }}
max_segment_duration: {{ audita_normalization_max_segment_duration | float | to_json }}
{% endif %}
{% if audita_normalization_max_segment_tokens is not none %}
max_segment_tokens: {{ audita_normalization_max_segment_tokens | to_json }}
@@ -104,12 +75,21 @@ thresholds:
context:
description: {{ audita_context_description | to_json }}
{% endif %}
{% if audita_diagnostics_work_dir is not none or audita_diagnostics_retention is not none %}
{% if audita_reporting_enabled is not none or audita_reporting_stdout_dir is not none %}
reporting:
{% if audita_reporting_enabled is not none %}
enabled: {{ audita_reporting_enabled | to_json }}
{% endif %}
{% if audita_reporting_stdout_dir is not none %}
stdout_dir: {{ audita_reporting_stdout_dir | to_json }}
{% endif %}
{% endif %}
{% if audita_diagnostics_debug is not none or audita_diagnostics_work_dir is not none %}
diagnostics:
{% if audita_diagnostics_debug is not none %}
debug: {{ audita_diagnostics_debug | to_json }}
{% endif %}
{% if audita_diagnostics_work_dir is not none %}
work_dir: {{ audita_diagnostics_work_dir | to_json }}
{% endif %}
{% if audita_diagnostics_retention is not none %}
retention: {{ audita_diagnostics_retention | to_json }}
{% endif %}
{% endif %}

29
tests/integration
View File

@@ -14,12 +14,13 @@ converge="$repository_root/tests/converge.yml"
verify_config="$repository_root/tests/verify-config.yml"
ansible_playbook="$workspace_venv/bin/ansible-playbook"
binary_path=/usr/local/bin/audita
config_path=/usr/local/etc/audita/config.yml
config_root="$test_tmp/config"
config_path="$config_root/config.yml"
profile_dir="$config_root/profiles"
cleanup() {
exit_status=$?
trap - EXIT
"$ansible_playbook" -i "$inventory" "$converge" >/dev/null 2>&1 || true
rm -rf -- "$test_tmp"
exit "$exit_status"
}
@@ -32,31 +33,47 @@ require_clean_recap() {
run_converge() {
output_file=$1
shift
"$ansible_playbook" -i "$inventory" "$@" "$converge" | tee "$output_file"
"$ansible_playbook" -i "$inventory" "${baseline_args[@]}" "$@" "$converge" | tee "$output_file"
}
validate_config() {
"$binary_path" config validate --config "$config_path"
}
mkdir -p "$profile_dir"
printf '%s\n' \
'id: fixture-proposal' \
'backend: fixture' \
'model: offline-fixture' \
'timeout_seconds: 30' > "$profile_dir/fixture-proposal.yaml"
baseline_args=(
-e "audita_config_path=$config_path"
-e "audita_config_owner=$(id -un)"
-e "audita_config_group=$(id -gn)"
-e '{"audita_backends": {"fixture": {"endpoint": "http://127.0.0.1:11434/v1", "credential": null}}, "audita_llm_proposal_profile": "fixture-proposal"}'
)
cd "$repository_root"
"$workspace_venv/bin/ansible-galaxy" collection install \
-r collections/requirements.yml \
-p "$ANSIBLE_COLLECTIONS_PATH"
"$ansible_playbook" -i "$inventory" --syntax-check "$converge"
"$ansible_playbook" -i "$inventory" "${baseline_args[@]}" --syntax-check "$converge"
"$workspace_venv/bin/ansible-lint" "$converge" "$verify_config"
baseline_log="$test_tmp/baseline.log"
run_converge "$baseline_log"
validate_config
"$binary_path" config print-effective --config "$config_path" --view profiles > "$test_tmp/baseline-profiles.yml"
baseline_repeat_log="$test_tmp/baseline-repeat.log"
run_converge "$baseline_repeat_log"
require_clean_recap "$baseline_repeat_log"
representative_config='{"audita_config_version": 1, "audita_pipeline_modules": ["glossary"], "audita_llm_proposal_base_url": "https://openrouter.ai/api/v1", "audita_llm_proposal_model": "openrouter/google/gemma-4-31b-it", "audita_llm_proposal_timeout": "10s", "audita_llm_proposal_max_retries": 0, "audita_context_description": "", "audita_diagnostics_retention": "never", "audita_llm_validation_model": null, "audita_output_schema": null, "audita_diagnostics_work_dir": null}'
representative_config='{"audita_pipeline_modules": ["glossary"], "audita_context_description": "", "audita_output_schema": null, "audita_llm_validation_profile": null}'
representative_log="$test_tmp/representative-config.log"
run_converge "$representative_log" -e "$representative_config"
"$ansible_playbook" -i "$inventory" "$verify_config"
validate_config
"$ansible_playbook" -i "$inventory" -e "audita_test_config_path=$config_path" "$verify_config"
representative_repeat_log="$test_tmp/representative-config-repeat.log"
run_converge "$representative_repeat_log" -e "$representative_config"
require_clean_recap "$representative_repeat_log"

27
tests/verify-config.yml
View File

@@ -4,34 +4,21 @@
gather_facts: false
tasks:
- name: Read rendered configuration
become: true
ansible.builtin.slurp:
src: /usr/local/etc/audita/config.yml
src: "{{ audita_test_config_path }}"
register: audita_rendered_config_file
- name: Check representative rendered configuration
ansible.builtin.assert:
that:
- audita_rendered_config.version == 1
- audita_rendered_config.version == 2
- audita_rendered_config.backends.fixture.endpoint == "http://127.0.0.1:11434/v1"
- audita_rendered_config.backends.fixture.credential is none
- audita_rendered_config.llm.proposal_profile == "fixture-proposal"
- audita_rendered_config.pipeline.modules == ["glossary"]
- audita_rendered_config.llm.proposal.base_url == "https://openrouter.ai/api/v1"
- audita_rendered_config.llm.proposal.model == "openrouter/google/gemma-4-31b-it"
- audita_rendered_config.llm.proposal.timeout == "10s"
- audita_rendered_config.llm.proposal.max_retries == 0
- audita_rendered_config.context.description == ""
- audita_rendered_config.diagnostics.retention == "never"
- audita_rendered_config.llm.validation is not defined
- audita_rendered_config.llm.validation_profile is not defined
- audita_rendered_config.output is not defined
- audita_rendered_config.diagnostics.work_dir is not defined
- audita_rendered_config.diagnostics is not defined
vars:
audita_rendered_config: "{{ audita_rendered_config_file.content | b64decode | from_yaml }}"
- name: Validate rendered configuration
ansible.builtin.command:
argv:
- /usr/local/bin/audita
- config
- validate
- --config
- /usr/local/etc/audita/config.yml
changed_when: false