Ansible Idempotent Automation & Vault Credential Hardening

--- description: Ansible Idempotent Automation & Vault Credential Hardening - Production configuration management standard for Ansible. Mandates strict task idempotency, native declarative modules over raw shell commands, Ansible Vault credential encryption, and yamllint schema hygiene. globs: **/*playbook*.yml, **/*playbook*.yaml, roles/**/*.yml alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ansible-idempotent-playbooks" --- # Ansible Idempotent Automation & Vault Credential Hardening > **Severity**: HIGH | **Category**: devops > **Anti-Pattern Warning**: AI writes imperative ansible.builtin.shell scripts without creates or changed_when, causing dirty state mutations on every run. ## System Constraints You are an infrastructure automation and configuration management engineer. When writing Ansible playbooks, NEVER use raw shell or command modules when a native declarative module exists (e.g. use ansible.builtin.copy, systemd, apt, git). If command/shell is unavoidable, you MUST supply 'creates', 'removes', or explicit 'changed_when' clauses. ## Strict Guidelines - Prefer declarative modules (ansible.builtin.template, package, service, user) over command/shell execution. - Always declare 'changed_when: false' or 'changed_when: result.rc == 0' on shell commands to preserve idempotency reporting. - Encrypt all sensitive tokens, passwords, and private keys using Ansible Vault (!vault); never commit plaintext secrets. - Use handlers with 'notify' to trigger service restarts only when configuration files actually change. ## Bad vs Good Implementations ### Idempotent Service Deployment with Handlers vs Imperative Shell Scripts #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Causes service downtime on every playbook execution regardless of whether configuration actually changed. ```yaml # ANTI-PATTERN: Imperative shell commands restart services on EVERY execution! - name: Deploy Nginx Config hosts: webservers tasks: - name: Copy config ansible.builtin.shell: cp /tmp/nginx.conf /etc/nginx/nginx.conf # Always reports changed! - name: Restart Nginx ansible.builtin.shell: systemctl restart nginx # Disastrous: Drops user traffic on every run! ``` #### Production Standard (Correct) > **Standard**: Validates syntax before copying, reports 'ok' without changes when files match, and triggers graceful zero-downtime reloads only when updated. ```yaml # PRODUCTION STANDARD: Declarative Template with Idempotent Notification Handler - name: Deploy Hardened Webserver Configuration hosts: webservers become: true tasks: - name: Deploy Nginx configuration from template ansible.builtin.template: src: templates/nginx.conf.j2 dest: /etc/nginx/nginx.conf owner: root group: root mode: '0644' validate: nginx -t -c %s notify: Reload Nginx handlers: - name: Reload Nginx ansible.builtin.systemd: name: nginx state: reloaded ``` ### Guarded Command with creates Clause #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Overwrites certificates repeatedly, invalidating existing clients. ```yaml # ANTI-PATTERN: Running certificate generation on every run - name: Generate SSL key ansible.builtin.command: openssl req -new -x509 ... ``` #### Production Standard (Correct) > **Standard**: Skips task cleanly if the destination file already exists on the target host. ```yaml # PRODUCTION STANDARD: creates check prevents duplicate execution - name: Generate SSL private key ansible.builtin.command: openssl req -new -x509 ... args: creates: /etc/ssl/certs/server.crt ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Ansible Idempotent Automation & Vault Credential Hardening

Ansible Idempotent Automation & Vault Credential Hardening defines an industrial-grade behavioral standard for devops engineering. Production configuration management standard for Ansible. Mandates strict task idempotency, native declarative modules over raw shell commands, Ansible Vault credential encryption, and yamllint schema hygiene. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI writes imperative ansible.builtin.shell scripts without creates or changed_when, causing dirty state mutations on every run. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI writes imperative ansible.builtin.shell scripts without creates or changed_when, causing dirty state mutations on every run.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Prefer declarative modules (ansible.builtin.template, package, service, user) over command/shell execution.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Always declare 'changed_when

Always declare 'changed_when: false' or 'changed_when: result.rc == 0' on shell commands to preserve idempotency reporting.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Encrypt all sensitive tokens, passwords, and private keys using Ansible Vault (!vault)

Encrypt all sensitive tokens, passwords, and private keys using Ansible Vault (!vault); never commit plaintext secrets.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Use handlers with 'notify' to trigger service restarts only when configuration files actually change.

Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.

Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Ansible Idempotent Automation & Vault Credential Hardening critical for AI coding assistants?

Production configuration management standard for Ansible. Mandates strict task idempotency, native declarative modules over raw shell commands, Ansible Vault credential encryption, and yamllint schema hygiene. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI writes imperative ansible.builtin.shell scripts without creates or changed_when, causing dirty state mutations on every run.) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.