--- name: ansible-automation-and-playbooks description: Master enterprise Ansible automation, idempotent playbook execution, reusable role design, Ansible Vault security, and Molecule automated testing. --- # Ansible Automation & Playbooks Skill Guide This skill provides production standards, directory layouts, security practices, and code patterns for writing enterprise-grade, idempotent Ansible playbooks and roles. --- ## 1. Directory Layout & Architecture Standards Always follow the official **Ansible Collection / Multi-Role Repository** directory structure. ```text ansible-infrastructure/ ├── inventory/ │ ├── production/ │ │ ├── hosts.yml # Production inventory definition │ │ └── group_vars/ │ │ ├── all.yml # Global variables across production │ │ ├── webservers.yml # Webserver group overrides │ │ └── vault.yml # Encrypted secrets via Ansible Vault │ └── staging/ │ ├── hosts.yml │ └── group_vars/ ├── roles/ │ └── web_server/ │ ├── defaults/ │ │ └── main.yml # Low-precedence default variables │ ├── vars/ │ │ └── main.yml # High-precedence explicit role variables │ ├── tasks/ │ │ └── main.yml # Entry point for tasks │ ├── handlers/ │ │ └── main.yml # Event-driven service notifications │ ├── templates/ │ │ └── nginx.conf.j2 # Jinja2 template files │ ├── meta/ │ │ └── main.yml # Role dependencies & metadata │ └── molecule/ │ └── default/ │ ├── molecule.yml # Molecule test harness config │ └── converge.yml # Test execution playbook ├── site.yml # Master orchestration playbook ├── ansible.cfg # Ansible configuration file ├── requirements.yml # External galaxy role & collection dependencies └── .ansible-lint # Static analysis configuration ``` --- ## 2. Standard Configuration (`ansible.cfg`) ```ini [defaults] inventory = ./inventory/production/hosts.yml roles_path = ./roles remote_user = devops host_key_checking = True stdout_callback = yaml bin_ansible_callbacks = True forks = 25 retry_files_enabled = False interpreter_python = auto_silent [privilege_escalation] become = True become_method = sudo become_user = root become_ask_pass = False ``` --- ## 3. Idempotent Ansible Playbook & Role Implementation ### A. Master Playbook Orchestration (`site.yml`) ```yaml --- - name: Configure Webservers and Edge Reverse Proxies hosts: webservers gather_facts: true become: true pre_tasks: - name: Ensure OS dependencies are up to date ansible.builtin.apt: update_cache: true cache_valid_time: 3600 when: ansible_os_family == "Debian" roles: - role: web_server post_tasks: - name: Verify Web Service Health ansible.builtin.uri: url: "http://localhost:80/health" status_code: 200 register: result until: result.status == 200 retries: 5 delay: 3 ``` ### B. Role Task Definitions (`roles/web_server/tasks/main.yml`) Always enforce idempotency, use explicit module names (`ansible.builtin.*`), and name every task clearly. ```yaml --- - name: Install NGINX web server package ansible.builtin.package: name: "{{ web_server_package_name }}" state: present - name: Render NGINX configuration template ansible.builtin.template: src: nginx.conf.j2 dest: /etc/nginx/nginx.conf owner: root group: root mode: '0644' notify: Restart Nginx Service - name: Ensure NGINX document root exists ansible.builtin.file: path: "{{ web_server_doc_root }}" state: directory owner: www-data group: www-data mode: '0755' - name: Deploy application index file ansible.builtin.copy: content: "

Deployed by Ansible

\n" dest: "{{ web_server_doc_root }}/index.html" owner: www-data group: www-data mode: '0644' - name: Ensure NGINX service is enabled and running ansible.builtin.systemd: name: nginx state: started enabled: true ``` ### C. Handlers (`roles/web_server/handlers/main.yml`) Handlers execute once at the end of a play if notified by a state change. ```yaml --- - name: Restart Nginx Service ansible.builtin.systemd: name: nginx state: restarted ``` --- ## 4. Secrets Management with Ansible Vault Never commit plaintext passwords, API keys, or certificates to source control. ### Encrypting Variables File ```bash # Encrypt an existing file ansible-vault encrypt inventory/production/group_vars/vault.yml # Edit encrypted file ansible-vault edit inventory/production/group_vars/vault.yml # Execute playbook using vault password file ansible-playbook -i inventory/production/hosts.yml site.yml --vault-password-file .vault_pass ``` ### Vault Encrypted Data Structure (`group_vars/vault.yml`) ```yaml vault_db_password: !vault | $ANSIBLE_VAULT;1.1;AES256 36303037363630346162383563373539316538353364373138353138383335343431353736323630 63333433393931343730306338303866383637383765383100103734633730336531313735353535 35623035346536373832383437316533316631623337613530343363383439366661333334326532 ``` --- ## 5. Automated Role Testing with Molecule & Docker Molecule tests roles isolated inside ephemeral containers or virtual machines. ### `molecule/default/molecule.yml` ```yaml --- dependency: name: galaxy driver: name: docker platforms: - name: instance-ubuntu-2204 image: geerlingguy/docker-ubuntu2204-ansible:latest command: "" volumes: - /sys/fs/cgroup:/sys/fs/cgroup:rw cgroupns_mode: host privileged: true pre_build_image: true provisioner: name: ansible verifier: name: ansible ``` --- ## 6. Anti-Patterns & Best Practices | Anti-Pattern | Operational Failure | Production Best Practice | | :--- | :--- | :--- | | **Using `shell` or `command` modules for package/file management** | Bypasses idempotency checks; executes on every run even if no state change is needed. | Use native declarative modules (`ansible.builtin.apt`, `ansible.builtin.file`, `ansible.builtin.systemd`). | | **Hardcoding Hostnames or IPs in Playbooks** | Prevents playbook reuse across staging, QA, and production environments. | Parameterize hosts via inventory files (`hosts.yml`) and `group_vars`. | | **Storing Plaintext Passwords in Git** | Exposes production credentials in version control history. | Encrypt sensitive variables with `ansible-vault` or retrieve dynamically from HashiCorp Vault. | | **Ignoring `ansible-lint` Violations** | Results in deprecated module usage, unhandled errors, non-standard code styles. | Add `ansible-lint` checks into CI/CD pipelines as a required gate before merging. |