Project 8: Custom Ansible Module + Quality Gates

Create a focused custom module and integrate it with CI quality checks.

Quick Reference

Attribute Value
Difficulty Level 4
Time Estimate 24-40 hours
Main Programming Language Python module interface + YAML caller
Coolness Level 4
Business Potential 2. Micro-SaaS / Pro Tool
Prerequisites P04, P07
Key Topics module contracts, changed semantics, lint/test gates

1. Learning Objectives

  1. Design a small custom module interface.
  2. Return deterministic JSON result schema.
  3. Implement correct changed/failed semantics.
  4. Enforce lint/syntax/idempotency checks in CI.

2. All Theory Needed (Per-Concept Breakdown)

2.1 Contract-First Extension

Fundamentals A custom module is an API contract: arguments in, deterministic result out, clear error behavior.

Deep Dive into the concept Unstructured shell logic is difficult to test and hard to reuse. A module formalizes behavior and integrates with Ansible’s change model. The core risk is incorrect semantics: if changed is wrong, handlers and run summaries become misleading.

Mental model diagram

task args -> module validation -> domain check -> structured result -> playbook decisions

Where you’ll apply it P08 and capstone.

3. Project Specification

3.1 What You Will Build

A custom module that performs one domain check (for example, endpoint readiness) and returns:

  • changed boolean
  • status field
  • explanatory message

3.2 Functional Requirements

  1. Module validates argument schema.
  2. Module supports check mode semantics.
  3. Module returns deterministic JSON keys.
  4. CI gates enforce quality checks.

3.4 Example Output

$ ansible-playbook -i localhost, custom_module_test.yml
ok: [localhost] => {
  "changed": false,
  "status": "reachable",
  "message": "readiness passed"
}

3.7 Real World Outcome

  • Module can be called like built-in modules.
  • Result contract is stable across runs.
  • CI rejects regressions in style or semantics.

4. Solution Architecture

module file + argument schema + result schema + caller playbook + CI gate pipeline

5. Implementation Guide

5.3 The Core Question You’re Answering

“How do I add custom capability without reducing operational trust in automation outputs?”

5.4 Concepts You Must Understand First

  1. Module return contract and semantics.
  2. Idempotency expectations for check-style modules.
  3. CI gate design for automation assets.

5.5 Questions to Guide Your Design

  1. What constitutes a state change in this module?
  2. Which result fields are required for downstream decisions?

5.6 Thinking Exercise

Write a one-page module contract containing inputs, invariants, output schema, and error model.

5.7 Interview Questions

  1. When should you write a custom module instead of a role wrapper?
  2. Why is changed correctness critical?
  3. What minimum CI gates should module repos have?

5.8 Hints in Layers

  • Hint 1: Keep scope to one responsibility.
  • Hint 2: Design schema before implementation.
  • Hint 3: Add negative tests first.
  • Hint 4: Verify second-run output stability.

6. Testing Strategy

  1. Argument validation failure path.
  2. Successful path deterministic output.
  3. Two-pass run proving stable semantics.
  4. CI lint + syntax + integration smoke.

7. Common Pitfalls & Debugging

Pitfall Symptom Solution
always changed=true noisy recaps and handlers tie changed to real mutation
inconsistent output keys caller parsing breaks freeze schema contract
CI too weak regressions slip enforce lint + integration checks

8. Extensions & Challenges

  • Package module in a collection.
  • Add schema docs and contract tests.
  • Add backward-compatibility policy for module versions.

9. Real-World Connections

Platform teams routinely build custom modules for internal APIs and compliance checks; quality gates determine whether those modules remain trustworthy over time.

10. Resources

  • Ansible module development docs
  • ansible-lint profile docs
  • CI best-practice references

11. Self-Assessment Checklist

  • I can explain module input/output contract clearly.
  • I can justify changed semantics.
  • I can show CI evidence for lint and idempotency checks.

12. Submission / Completion Criteria

  • Minimum: working module + deterministic output.
  • Full: includes failure-path tests + CI gates.
  • Excellence: collection packaging + compatibility strategy.