Playbooks, Idempotency, and Handlers

1. 1

   Write the Nginx site config

   A plain file for now; in the next mission it becomes a template with variables. It's the same reverse-proxy setup you built in the Networking course (Topic 5.2).

   server {
       listen 80 default_server;
       location /healthz { return 200 "ok\n"; }
       location / {
           proxy_pass http://127.0.0.1:8080;
           proxy_set_header Host $host;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
   }

2. 2

   Write the playbook

   become: true runs tasks with sudo (harmless in the root containers, required on real servers). Every task has a name. It appears in the output and is the task's documentation.

   The command task that validates config has changed_when: false: it only reads, so it must never report a change. Without that, every run would look like it changed something.

   - name: Configure ShopLite web servers
     hosts: web
     become: true
   
     tasks:
       - name: Install nginx
         ansible.builtin.apt:
           name: nginx
           state: present
           update_cache: true
           cache_valid_time: 3600
   
       - name: Deploy the ShopLite site
         ansible.builtin.copy:
           src: files/shoplite.conf
           dest: /etc/nginx/sites-available/default
           mode: "0644"
         notify: Reload nginx
   
       - name: Validate nginx config
         ansible.builtin.command: nginx -t
         changed_when: false
   
       - name: Ensure nginx is running
         ansible.builtin.service:
           name: nginx
           state: started
   
     handlers:
       - name: Reload nginx
         ansible.builtin.service:
           name: nginx
           state: reloaded

3. 3

   Check syntax and preview with --check --diff

   --check is a dry run: modules report what they WOULD change. --diff shows file content differences. Together they are Ansible's version of terraform plan. Not every module supports check mode perfectly (commands are skipped), so treat it as a strong preview, not a guarantee.

   terminalcopy cmd

   $ ansible-playbook site.yml --syntax-check

   ansible-playbook site.yml --check --diff

   ── expected output ──

   playbook: site.yml

   ...

   TASK [Deploy the ShopLite site] ***

   --- before: /etc/nginx/sites-available/default

   +++ after: files/shoplite.conf

   @@ ... @@

   changed: [web1]

   changed: [web2]

4. 4

   Apply it, then apply it again

   The first run changes things and fires the handler once per host. The second run should be all green: changed=0. A playbook that reports changes on every run is lying to you, because you can no longer tell a real change from noise.

   terminalcopy cmd

   $ ansible-playbook site.yml

   ansible-playbook site.yml | tail -4

   ── expected output ──

   RUNNING HANDLER [Reload nginx] ***

   changed: [web1]

   changed: [web2]

    

   PLAY RECAP ***

   web1 : ok=5 changed=3 unreachable=0 failed=0 skipped=0

   web2 : ok=5 changed=3 unreachable=0 failed=0 skipped=0

    

   PLAY RECAP ***

   web1 : ok=4 changed=0 unreachable=0 failed=0 skipped=0

   web2 : ok=4 changed=0 unreachable=0 failed=0 skipped=0

5. 5

   Target, limit, and tag

   --limit web1 runs on one host. That's how you canary a change on one server before the fleet. --start-at-task resumes a long run. serial: 1 in the play would roll changes out host by host, which is the configuration-management version of a rolling update (Kubernetes course).

   terminalcopy cmd

   $ ansible-playbook site.yml --limit web1 --diff

   ── expected output ──

   PLAY RECAP ***

   web1 : ok=4 changed=0 unreachable=0 failed=0 skipped=0

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.