Project 4: Reusable Role and Galaxy Packaging

Refactor monolithic playbooks into a role with a clear contract and predictable behavior.

Quick Reference

Attribute Value
Difficulty Level 2
Time Estimate 12-18 hours
Main Programming Language YAML (roles)
Coolness Level 3
Business Potential 3. Service & Support
Prerequisites P02, P03
Key Topics Role architecture, variable contract, packaging

1. Learning Objectives

  1. Build a role from existing web tier tasks.
  2. Define role input/output contract clearly.
  3. Preserve behavior while improving maintainability.
  4. Prepare role for shared reuse and versioning.

2. All Theory Needed (Per-Concept Breakdown)

2.1 Reuse Through Contracts

Fundamentals Reusable roles succeed when interfaces are explicit: what variables they accept, which defaults exist, and what state they guarantee.

Deep Dive into the concept Without role contracts, reuse becomes guesswork. Callers override internal values, side effects become unpredictable, and upgrades become breaking changes. Contract-first role design keeps platform ownership clear and helps teams evolve safely.

Mental model diagram

caller vars -> role defaults/inputs -> tasks/templates/handlers -> guaranteed host state

Where you’ll apply it P04 directly; reused in P07 and capstone.

3. Project Specification

3.1 What You Will Build

A web_base role containing:

  • package/service tasks
  • template deployment
  • reload handler
  • documented defaults and required vars

3.2 Functional Requirements

  1. Role runs from a minimal site.yml caller.
  2. Defaults produce working baseline with no override.
  3. Explicit overrides are supported for selected inputs.
  4. Role behavior matches pre-refactor outputs.

3.4 Example Output

$ ansible-playbook -i inventory.ini site.yml
PLAY RECAP
node-a : ok=6 changed=1 failed=0
node-b : ok=6 changed=1 failed=0

3.7 Real World Outcome

  • Role directory follows standard structure.
  • One-page role contract exists.
  • site.yml stays short and readable.

4. Solution Architecture

site.yml -> role(web_base)
         -> tasks/main.yml
         -> templates/
         -> handlers/
         -> defaults/

5. Implementation Guide

5.3 The Core Question You’re Answering

“How do I package working automation so other teams can use it safely?”

5.4 Concepts You Must Understand First

  1. Role directory conventions.
  2. Variable precedence and default ownership.
  3. Backward-compatible refactoring.

5.5 Questions to Guide Your Design

  1. Which variables are public API and which are internal?
  2. How do you prevent accidental breaking changes?

5.6 Thinking Exercise

Write a change log entry for a hypothetical role update and decide if it is major/minor/patch.

5.7 Interview Questions

  1. What makes role APIs stable?
  2. Where should defaults live and why?
  3. How do you test role compatibility across callers?

5.8 Hints in Layers

  • Hint 1: Refactor structure before behavior.
  • Hint 2: Namespace role variables.
  • Hint 3: Add assertions for required inputs.
  • Hint 4: Compare old/new run recaps.

6. Testing Strategy

  1. Role run with defaults.
  2. Role run with selected overrides.
  3. Two-pass idempotency check.

7. Common Pitfalls & Debugging

Pitfall Symptom Solution
generic var names conflicts across roles prefix role vars
hidden assumptions works only in one repo follow standard role paths
undocumented API misuse by callers publish contract table

8. Extensions & Challenges

  • Publish role metadata and semantic versioning policy.
  • Add Molecule scenario for role validation.
  • Add cross-distro test matrix.

9. Real-World Connections

Shared roles are the basis for platform teams that support many app teams without copy/paste automation.

10. Resources

  • Ansible roles docs
  • Ansible Galaxy docs
  • Clean Architecture (contract design mindset)

11. Self-Assessment Checklist

  • I can explain role inputs/outputs without reading tasks.
  • I can run the role from a minimal caller playbook.
  • I can show no regression from pre-refactor behavior.

12. Submission / Completion Criteria

  • Minimum: role structure + successful run.
  • Full: contract documentation + override tests.
  • Excellence: semantic versioning + compatibility test matrix.