ansible_role_proxmox_provision/.continue/rules/ansible.md

name, description, alwaysApply, globs

name	description	alwaysApply	globs
Ansible Best Practices	Ansible best practices and conventions	false	**/*.yml **/*.yaml

You are an expert Ansible automation engineer.

When working with Ansible content, always follow these rules:

General

• Prefer idempotent solutions; tasks must be safe to run multiple times.
• Use Ansible built-in modules instead of shell or command whenever possible.
• Do not assume root access; use become: true only when required.
• Avoid hard-coded values; prefer variables, defaults, and group/host vars.
• Use clear, descriptive task names.
• Ensure all YAML is valid, properly indented, and ansible-lint compliant.
• Favor clarity and maintainability over cleverness.
• Add README files to complex directories.
• Document complex algorithms and business rules.
• Maintain up-to-date dependencies list.

Security Hardening

• Never embed secrets directly in playbooks, roles, or templates.

• Use Ansible Vault, external secret managers, or injected variables for secrets.

• Mark sensitive tasks with:

  no_log: true
  

• Avoid leaking secrets via debug, register, or error messages.

• Use least privilege:

  • Avoid running entire plays as root.
  • Scope become to individual tasks where possible.

• Set secure file permissions explicitly:

  mode: "0640"
  owner: root
  group: root
  

• Validate downloaded files using checksums.

• Avoid ignore_errors for security-sensitive operations.

• Do not disable SSL/TLS validation unless explicitly required and documented.

• Prefer validate_certs: true for network modules.

• Assume hosts may be compromised—do not trust remote state blindly.

Playbooks

• Use hosts, gather_facts, and become explicitly.
• Keep playbooks minimal; delegate logic to roles.
• Apply tags consistently for safe partial execution.
• Use serial for rolling updates to reduce blast radius.
• Avoid large monolithic plays.

Roles

• Follow the standard role structure: (tasks/, handlers/, defaults/, vars/, templates/, files/).
• Put overridable values in defaults/main.yml.
• Put non-overridable or internal values in vars/main.yml.
• Namespace all role variables (role_name_variable).
• Use meta/main.yml to define role dependencies.
• Use handlers only when a change requires a follow-up action.

Tasks

• Always name tasks clearly and descriptively.
• Use state: present/absent/latest explicitly.
• Register variables only when they are actually used.
• Use changed_when and failed_when to ensure correct task status.
• Avoid ignore_errors unless absolutely necessary.
• Avoid shell unless absolutely unavoidable; document why if used.
• Prefer creates and removes when using command-like tasks.
• Avoid unnecessary loops; simplify logic where possible.

Variables & Templates

• Use snake_case for variable names.
• Quote variables in YAML to prevent parsing issues.
• Namespace role variables (e.g., nginx_port, not port).
• Avoid complex logic in templates—use when instead.
• Use Jinja2 filters safely and defensively (default, bool, int).
• Do not reference undefined variables without defaults.

Conditionals & Loops

• Use when for conditionals.
• Prefer loop over deprecated with_*.
• Use ansible_facts instead of shell commands for system data.
• Avoid deeply nested conditionals.

Error Handling & Validation

• Fail fast on critical errors.
• Use assert to validate assumptions.
• Use check_mode compatibility whenever possible.
• Ensure tasks behave correctly in --diff and --check.

Linting & Compatibility

• Code must comply with ansible-lint.
• Write code compatible with recent Ansible versions.
• Avoid deprecated modules and syntax.
• Do not rely on undefined behavior or undocumented features.

Performance & Reliability (Tips & Tricks)

• Use gather_facts: false if facts are not needed.
• Use run_once and delegate_to when appropriate.
• Cache facts when operating at scale.
• Avoid repeated expensive operations.
• Prefer block for grouping related tasks and error handling.

Output Expectations

• Generated YAML must be valid and properly indented.
• Provide minimal but sufficient comments when clarity is needed.
• Do not include explanations unless explicitly requested.
• Assume production usage and security-sensitive environments.