Roles, Vault, and the Terraform Handoff

1. 1

   Scaffold the role

   ansible-galaxy role init creates the standard layout. Move the template into roles/shoplite_web/templates/ and the handler into handlers/main.yml. Anything a user of the role might want to change goes in defaults/main.yml.

   terminalcopy cmd

   $ ansible-galaxy role init roles/shoplite_web

   git mv templates/shoplite.conf.j2 roles/shoplite_web/templates/

   ── expected output ──

   - Role roles/shoplite_web was created successfully

2. 2

   Role defaults and tasks

   Defaults document every knob the role exposes. Move the Reload nginx handler into handlers/main.yml unchanged.

   listen_port: 80
   client_max_body_size: 10m
   upstreams: [127.0.0.1:8080]
   admin_users: []

3. 3

   Role tasks

   The tasks are the ones from site.yml, plus a new app.env.j2 template (one line: DB_PASSWORD={{ db_password | default('') }}) for the app's database settings. no_log: true keeps its contents out of the output.

   - name: Install nginx
     ansible.builtin.apt: { name: nginx, state: present, update_cache: true, cache_valid_time: 3600 }
   
   - name: Render the ShopLite site
     ansible.builtin.template:
       src: shoplite.conf.j2
       dest: /etc/nginx/sites-available/default
       mode: "0644"
     notify: Reload nginx
   
   - name: Create admin users
     ansible.builtin.user: { name: "{{ item }}", groups: sudo, append: true, shell: /bin/bash }
     loop: "{{ admin_users }}"
   
   - name: Create the app config directory
     ansible.builtin.file: { path: /etc/shoplite, state: directory, mode: "0750" }
   
   - name: Write the app's DB config
     ansible.builtin.template:
       src: app.env.j2
       dest: /etc/shoplite/app.env
       mode: "0600"
     when: db_password is defined
     no_log: true
   
   - name: Ensure nginx is running
     ansible.builtin.service: { name: nginx, state: started, enabled: true }

4. 4

   Shrink the playbook

   The playbook now reads like a table of contents. Adding a db group later means one more play with a shoplite_db role.

   - name: Configure ShopLite web servers
     hosts: web
     become: true
     roles:
       - shoplite_web

5. 5

   Pin external collections

   Install into the project so every teammate and CI runner uses the same versions.

   collections:
     - name: amazon.aws
       version: "10.1.0"
     - name: community.docker
       version: "4.7.0"

6. 6

   Encrypt the prod DB password

   Split group_vars/prod.yml into a directory: vars.yml (plain) and vault.yml (encrypted). The vault password file lives OUTSIDE the repo and is listed in .gitignore; in CI it comes from a secret.

   terminalcopy cmd

   $ mkdir -p group_vars/prod && git mv group_vars/prod.yml group_vars/prod/vars.yml

   echo 'vault_db_password: "s3cr3t-prod-pw"' > group_vars/prod/vault.yml

   ansible-vault encrypt group_vars/prod/vault.yml --vault-password-file ~/.shoplite-vault-pass

   head -2 group_vars/prod/vault.yml

   ── expected output ──

   Encryption successful

   $ANSIBLE_VAULT;1.1;AES256

   6231356462663934353738653662333762316335386430623961326134393432...

7. 7

   Reference the vaulted value from plain vars

   Add this line to group_vars/prod/vars.yml. The vault_ prefix makes it obvious where the real value lives. Run with --vault-password-file (or set vault_password_file in ansible.cfg).

   db_password: "{{ vault_db_password }}"

   terminalcopy cmd

   $ ansible-playbook site.yml --vault-password-file ~/.shoplite-vault-pass

   ansible-vault view group_vars/prod/vault.yml --vault-password-file ~/.shoplite-vault-pass

   ── expected output ──

   TASK [shoplite_web : Write the app's DB config] ***

   skipping: [web1]

   changed: [web2]

   ...

   vault_db_password: "s3cr3t-prod-pw"

8. 8

   Dynamic inventory from Terraform's tags

   In the Terraform course your instances got Role and Env tags. This inventory file asks EC2 for running instances with those tags and turns them into groups (role_web, env_prod). Connection uses SSM Session Manager or SSH to private IPs through a bastion. No public IPs needed (AWS course, Topic 2.2).

   plugin: amazon.aws.aws_ec2
   regions: [ap-south-1]
   filters:
     instance-state-name: running
     tag:Project: shoplite
   keyed_groups:
     - key: tags.Role
       prefix: role
     - key: tags.Env
       prefix: env
   hostnames: [tag:Name, private-ip-address]
   compose:
     ansible_host: private_ip_address

   terminalcopy cmd

   $ ansible-galaxy collection install -r requirements.yml

   ansible-inventory -i inventory.aws_ec2.yml --graph

   ── expected output ──

   @all:

   |--@aws_ec2:

   | |--shoplite-prod-web-0

   | |--shoplite-prod-web-1

   |--@role_web:

   | |--shoplite-prod-web-0

   | |--shoplite-prod-web-1

   |--@env_prod:

   | |--shoplite-prod-web-0

   | |--shoplite-prod-web-1

9. 9

   Test the role with Molecule

   Molecule spins up a throwaway container, applies the role, runs it again to prove idempotency (the run fails if anything reports changed), runs verification, and destroys everything. Put molecule test in CI and roles stay trustworthy, just like terraform test for modules.

   driver:
     name: docker
   platforms:
     - name: instance
       image: geerlingguy/docker-ubuntu2404-ansible
       pre_build_image: true
   provisioner:
     name: ansible
   verifier:
     name: ansible

   terminalcopy cmd

   $ cd roles/shoplite_web && molecule test

   ── expected output ──

   INFO default ➜ converge: Executed: Successful

   INFO default ➜ idempotence: Idempotence completed successfully.

   INFO default ➜ verify: Executed: Successful

   INFO default ➜ destroy: Executed: Successful

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.