Project 3: Template + Handler Config Rollout

Deploy host-specific configuration and trigger service reload only when content actually changes.

Quick Reference

Attribute Value
Difficulty Level 2
Time Estimate 10-14 hours
Main Programming Language YAML + Jinja2
Coolness Level 3
Business Potential 3. Service & Support
Prerequisites P01, P02
Key Topics Templating, handlers, config validation

1. Learning Objectives

  1. Render host-specific config from a shared template.
  2. Use handler notifications for change-dependent reload.
  3. Prevent invalid config rollout through pre-reload validation.
  4. Demonstrate stable second run with no unnecessary handler execution.

2. All Theory Needed (Per-Concept Breakdown)

2.1 Event-Driven Service Management

Fundamentals Handlers run only when notified by changed tasks. This decouples configuration mutation from service side effects.

Deep Dive into the concept Without handlers, teams often restart services every run “just in case,” causing avoidable risk and uptime impact. Handlers provide explicit change signaling and natural batching. A task that renders identical config should not notify anything.

Mental model diagram

template task changed? -> yes -> notify handler -> reload service
                      -> no  -> no handler run

Minimal concrete example

# pseudocode
- render template -> notify reload_handler
- handler reload_handler -> service reload

Where you’ll apply it P03 and P07.

3. Project Specification

3.1 What You Will Build

A config rollout playbook that:

  • renders web config from template
  • validates syntax
  • reloads service via handler only if rendered output changed

3.2 Functional Requirements

  1. Template includes at least two host-specific values.
  2. Validation step runs before reload.
  3. Handler runs only on config drift.

3.4 Example Output

$ ansible-playbook -i inventory.ini web_config.yml
TASK [Render config] ..... changed
RUNNING HANDLER [Reload] . changed

$ ansible-playbook -i inventory.ini web_config.yml
TASK [Render config] ..... ok
# no handler

3.7 Real World Outcome

  • Host-specific rendered configs exist in expected paths.
  • Service is reloaded only when template content changes.
  • Failed validation blocks reload and reports clear error.

4. Solution Architecture

vars + facts -> render template -> validate -> notify handler -> reload

5. Implementation Guide

5.3 The Core Question You’re Answering

“How can I ship config safely without restart storms or silent bad configs?”

5.4 Concepts You Must Understand First

  1. Jinja variable rendering.
  2. Handler notification semantics.
  3. Validation before side effects.

5.5 Questions to Guide Your Design

  1. Which values belong in template vs vars?
  2. What is your validation command and failure behavior?

5.6 Thinking Exercise

Sketch what should happen for: no change, valid change, invalid change.

5.7 Interview Questions

  1. Why handlers over direct restarts?
  2. How do you gate reload on valid config?
  3. What causes handler flapping?

5.8 Hints in Layers

  • Hint 1: Keep template logic simple.
  • Hint 2: Assert required vars before render.
  • Hint 3: Validate config before notifying reload.
  • Hint 4: Compare first/second run behavior.

6. Testing Strategy

  1. First render from default state.
  2. Second run no-change path.
  3. Introduce invalid template value; confirm safe failure.

7. Common Pitfalls & Debugging

Pitfall Symptom Solution
notify mismatch handler never runs align names exactly
overcomplex template unstable output move logic to vars
missing validation bad reload add explicit syntax check

8. Extensions & Challenges

  • Add per-environment template variants.
  • Add rollback to previous known-good config artifact.
  • Add checksum evidence to change report.

9. Real-World Connections

This mirrors production web/proxy config workflows where unnecessary restarts are incident drivers.

10. Resources

  • Ansible handlers docs
  • Ansible templating docs
  • Service config validation docs for your web server

11. Self-Assessment Checklist

  • Handler runs only on real drift.
  • Invalid config cannot reach reload step.
  • Template output is predictable across hosts.

12. Submission / Completion Criteria

  • Minimum: template + handler behavior proven.
  • Full: includes validation failure demo.
  • Excellence: includes rollback and structured change evidence.