Ansible Roles — Empty defaults/main.yml Prevents Reuse

---
# Empty defaults/main.yml – no variables defined
# This prevents role reuse because other roles or playbooks
# cannot override any default values.
# Instead, always define at least one variable, even if empty:
# my_var: ""

#!/usr/bin/env bash
# io.thecodeforge: Initialize a new role with the full standard structure
# Always use ansible-galaxy role init — never create directories manually.
# The tool generates every required directory and file, including stubs
# for meta/main.yml with Galaxy metadata fields that must be present
# for publishing to Galaxy or an internal Automation Hub.

ansible-galaxy role init io.thecodeforge.webserver

# Generated structure:
# io.thecodeforge.webserver/
# ├── defaults/
# │   └── main.yml   <- LOWEST precedence. Everything here is overridable.
# │                     Use for: ports, paths, package versions, feature flags.
# │                     If a value might differ between teams or environments, it goes here.
# ├── files/
# │                  <- Static assets. No variable substitution.
# │                     Use for: scripts, static certs, binary configs, SSH keys.
# │                     Loaded by: ansible.builtin.copy with src: filename.ext
# ├── handlers/
# │   └── main.yml   <- Service lifecycle tasks. Only run when notified.
# │                     Use for: reload, restart, enable. Never unconditional tasks.
# ├── meta/
# │   └── main.yml   <- Role dependencies, Galaxy metadata, supported platforms.
# │                     Dependencies here run before this role, automatically.
# ├── tasks/
# │   └── main.yml   <- Primary execution logic. Loaded first automatically.
# │                     Should contain NO hardcoded values — only variable references.
# ├── templates/
# │                  <- Jinja2 templates. Rendered at runtime with variable substitution.
# │                     Use for: nginx.conf, postgresql.conf, systemd unit files.
# │                     Loaded by: ansible.builtin.template with src: filename.j2
# ├── vars/
# │   └── main.yml   <- HIGH precedence. Inventory and group_vars cannot override these.
# │                     Use for: internal package names, service names, OS-specific constants.
# │                     NOT for values users should change — use defaults/ for those.
# └── tests/
#     └── molecule/  <- Molecule test scenarios. Never leave this empty in production roles.
#         ├── default/    (tests with default variable values)
#         └── custom/     (tests with non-default values — catches hardcoding)

# After init, immediately set up Molecule:
cd io.thecodeforge.webserver
molecule init scenario default --driver-name docker
molecule init scenario custom --driver-name docker
# Write converge.yml and verify.yml for both scenarios before writing a single task.

---
# io.thecodeforge: Production orchestration playbook
# This file composes roles. It contains no task logic of its own.
# Each role does one thing. This playbook decides which things to do and in what order.
#
# Variable precedence at role call time (from the vars: block):
# Higher than: defaults/main.yml, group_vars, inventory vars
# Lower than: host_vars, extra vars (-e)
# Use the vars: block for environment-specific overrides you want visible in the playbook.
# Use group_vars for overrides that should apply to all plays targeting that group.

# ── Play 1: Load Balancer configuration ───────────────────────────────────────
- name: Configure Load Balancer Tier
  hosts: load_balancers
  become: true

  roles:
    # Common role runs first on every host — sets up SSH hardening, NTP, logging standards
    - role: io.thecodeforge.common
      vars:
        common_ntp_servers:
          - 169.254.169.123  # AWS time sync service — lower latency than pool.ntp.org
        common_ssh_allow_groups: ['deploy', 'sre']

    # HAProxy role — focused exclusively on load balancer configuration
    - role: io.thecodeforge.haproxy
      vars:
        haproxy_max_connections: 10000     # Overrides defaults/main.yml value of 2000
        haproxy_timeout_connect: '5s'
        haproxy_timeout_client: '30s'
        haproxy_timeout_server: '30s'
        haproxy_backend_servers:            # Dynamically populated from inventory
          - { name: 'web01', addr: '{{ hostvars["web-01"]["ansible_host"] }}', port: 8080 }
          - { name: 'web02', addr: '{{ hostvars["web-02"]["ansible_host"] }}', port: 8080 }

    # TLS termination role — manages certificates and nginx-based TLS offloading
    - role: io.thecodeforge.tls_termination
      vars:
        tls_domain: 'api.thecodeforge.io'
        tls_cert_source: 'acme'            # 'acme', 'vault', or 'file'
        tls_acme_email: 'ops@thecodeforge.io'

# ── Play 2: Application Server configuration ──────────────────────────────────
- name: Configure Application Server Tier
  hosts: web_servers
  become: true

  roles:
    - role: io.thecodeforge.common
      # Same role, same defaults — common runs identically on all tiers

    - role: io.thecodeforge.nginx
      vars:
        nginx_worker_processes: auto
        nginx_worker_connections: 4096
        nginx_vhosts:
          - server_name: 'api.thecodeforge.io'
            listen_port: 8080
            root: '/var/www/api'
            access_log: '/var/log/nginx/api_access.log'

    - role: io.thecodeforge.app_deploy
      vars:
        app_repo: 'https://github.com/thecodeforge/api.git'
        app_version: '{{ release_version | default("main") }}'
        app_user: 'www-data'
        app_env: 'production'

# ── Play 3: Database configuration ────────────────────────────────────────────
- name: Configure Database Tier
  hosts: database_servers
  become: true
  serial: 1               # One database server at a time — never parallel for Postgres
  max_fail_percentage: 0  # Any database failure stops the entire play

  roles:
    - role: io.thecodeforge.common

    - role: io.thecodeforge.postgresql
      vars:
        postgres_version: 16
        postgres_data_dir: '/data/pg_production'  # Overrides default /var/lib/postgresql
        postgres_max_connections: 200
        postgres_shared_buffers: '4GB'
        postgres_effective_cache_size: '12GB'
        # Passwords come from Vault — never hardcoded here
        postgres_app_password: '{{ vault_postgres_app_password }}'

    - role: io.thecodeforge.prometheus_node_exporter
      # No vars override — defaults work for all servers
      # Port 9100, /metrics endpoint, standard collectors

---
# io.thecodeforge: Molecule converge playbook — default scenario
# This runs the role with default variable values.
# Molecule automatically runs this twice and fails if second run shows 'changed'.

- name: Converge — test nginx role with default variables
  hosts: all
  become: true

  roles:
    - role: io.thecodeforge.nginx
      # No vars: block here — testing that defaults/main.yml values work correctly

---
# io.thecodeforge: Molecule verify playbook — Testinfra assertions
# File: molecule/default/verify.yml
# These assertions run after converge and confirm the role achieved its intended state.

- name: Verify — confirm nginx role achieved correct state
  hosts: all
  gather_facts: false

  tasks:
    - name: Confirm Nginx package is installed
      ansible.builtin.package_facts:
        manager: apt

    - name: Assert Nginx is installed at the pinned version
      ansible.builtin.assert:
        that:
          - "'nginx' in ansible_facts.packages"
        fail_msg: "Nginx is not installed — role task failed silently"

    - name: Confirm Nginx service is running and enabled
      ansible.builtin.service_facts:

    - name: Assert Nginx service state
      ansible.builtin.assert:
        that:
          - "ansible_facts.services['nginx.service'].state == 'running'"
          - "ansible_facts.services['nginx.service'].status == 'enabled'"
        fail_msg: "Nginx is not running or not enabled — handler or service task failed"

    - name: Confirm Nginx is listening on the default port
      ansible.builtin.wait_for:
        port: "{{ nginx_port | default(80) }}"
        timeout: 5
        msg: "Nginx is not listening on port {{ nginx_port | default(80) }}"

    - name: Verify Nginx config is valid
      ansible.builtin.command: nginx -t
      register: nginx_test
      changed_when: false
      failed_when: nginx_test.rc != 0

---
# io.thecodeforge: Molecule converge playbook — custom_paths scenario
# File: molecule/custom_paths/converge.yml
# This scenario runs the role with NON-DEFAULT variable values.
# It catches hardcoded paths and values in tasks/main.yml.
# If this scenario fails where default/ passes, a path is hardcoded.

- name: Converge — test nginx role with non-default variable values
  hosts: all
  become: true

  roles:
    - role: io.thecodeforge.nginx
      vars:
        nginx_port: 8080                         # Non-default: catches port hardcoding
        nginx_worker_processes: 2                 # Non-default: catches proc count hardcoding
        nginx_log_dir: /var/log/nginx_custom      # Non-default: catches path hardcoding
        nginx_config_dir: /etc/nginx_custom       # Non-default: catches config path hardcoding
        # Every variable in defaults/main.yml should appear here with a non-default value.
        # If the role fails this scenario, find the hardcoded value and move it to defaults/.

---
# io.thecodeforge: CI pipeline configuration for Molecule testing
# File: .gitlab-ci.yml excerpt
# This runs both Molecule scenarios on every merge request.

# molecule_test:
#   stage: test
#   image: quay.io/ansible/community-ansible-dev-tools:latest
#   before_script:
#     - pip install molecule molecule-plugins[docker] ansible-lint
#   script:
#     - cd roles/io.thecodeforge.nginx
#     - ansible-lint .                              # Lint first — fast failure
#     - molecule test --scenario-name default       # Default values + idempotency check
#     - molecule test --scenario-name custom_paths  # Non-default values + hardcoding check
#   rules:
#     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
#   artifacts:
#     when: on_failure
#     paths:
#       - roles/io.thecodeforge.nginx/.molecule/
#     expire_in: 3 days

// io.thecodeforge — devops tutorial
// Minimal production role structure
// roles/nginx/
//   defaults/
//     main.yml
//   tasks/
//     main.yml
//   handlers/
//     main.yml
//   templates/
//     nginx.conf.j2
//   vars/
//     main.yml
//   meta/
//     main.yml
//
// Example: roles/nginx/tasks/main.yml
---
- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present
  become: true

- name: Configure nginx
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  notify: Restart nginx

- name: Ensure nginx is running
  ansible.builtin.systemd:
    name: nginx
    state: started
    enabled: true
  become: true

// io.thecodeforge — devops tutorial
// roles/postgresql/meta/main.yml
---
dependencies:
  - role: geerlingguy.postgresql
    version: 3.5.0
  - role: nginx
  - role: monitoring

// roles/requirements.yml (project-level)
---
roles:
  - name: geerlingguy.postgresql
    src: https://github.com/geerlingguy/ansible-role-postgresql.git
    version: 3.5.0

  - name: nginx
    src: git+https://git.internal.company.io/ansible-roles/nginx.git
    version: v2.1.0

// Install command:
// ansible-galaxy install -r roles/requirements.yml -p roles/