Ansible Basics for Cloud Automation — Playbooks, Inventory and Roles Explained

# cloud_inventory.ini
# Static inventory for a three-tier cloud application
# In production you'd replace this with a dynamic inventory plugin
# (e.g. amazon.aws.aws_ec2) that queries the AWS API directly

[load_balancers]
# Format: alias ansible_host=<IP> ansible_user=<SSH user>
nginx-lb-01 ansible_host=54.210.100.11 ansible_user=ubuntu

[web_servers]
# Three app servers behind the load balancer
app-server-01 ansible_host=10.0.1.10 ansible_user=ubuntu
app-server-02 ansible_host=10.0.1.11 ansible_user=ubuntu
app-server-03 ansible_host=10.0.1.12 ansible_user=ubuntu

[database_servers]
# Primary and replica — we'll target them separately in playbooks
db-primary-01 ansible_host=10.0.2.10 ansible_user=ubuntu
db-replica-01 ansible_host=10.0.2.11 ansible_user=ubuntu

# Group of groups — 'production' contains all three tiers
[production:children]
load_balancers
web_servers
database_servers

# Group-level variables applied to every host in web_servers
[web_servers:vars]
# These become available as variables inside any play targeting web_servers
app_port=8080
deploy_user=apprunner
max_connections=1000

# Host-level variable overrides group-level variables
# app-server-03 is a canary so it runs on a different port
[web_servers]
app-server-03 ansible_host=10.0.1.12 ansible_user=ubuntu app_port=8090

---
# deploy_web_app.yml
# Deploys and configures our Node.js app behind Nginx on all web_servers
# Run with: ansible-playbook -i cloud_inventory.ini deploy_web_app.yml

- name: Configure Nginx reverse proxy and deploy application
  hosts: web_servers          # Matches the group name from our inventory file
  become: true                # Escalate to sudo — most package installs require it
  gather_facts: true          # Collect OS info (distro, arch) — used in conditionals below

  # Variables defined here override group vars but lose to host vars
  vars:
    node_version: "20"        # LTS version of Node.js to install
    app_directory: "/opt/webapp"
    nginx_config_path: "/etc/nginx/sites-available/webapp.conf"

  # Handlers only execute when notified AND only once per play, even if notified 10 times
  handlers:
    - name: Restart Nginx
      ansible.builtin.service:
        name: nginx
        state: restarted      # 'restarted' always restarts; use 'reloaded' for config-only changes

    - name: Restart application service
      ansible.builtin.service:
        name: webapp
        state: restarted

  tasks:
    # TASK 1: Ensure Nginx is installed — idempotent, does nothing if already present
    - name: Install Nginx web server
      ansible.builtin.apt:
        name: nginx
        state: present         # 'present' = install if missing; 'latest' = always upgrade
        update_cache: true     # Equivalent to running apt-get update first

    # TASK 2: Deploy our Nginx config using a Jinja2 template
    # If the rendered template differs from what's on disk, this reports 'changed'
    - name: Deploy Nginx reverse proxy configuration
      ansible.builtin.template:
        src: templates/nginx_webapp.conf.j2   # Local template file on your Ansible control node
        dest: "{{ nginx_config_path }}"
        owner: root
        group: root
        mode: '0644'
      notify: Restart Nginx    # Only restarts Nginx if this task actually changed the file

    # TASK 3: Create app directory — 'state: directory' is idempotent
    - name: Ensure application directory exists
      ansible.builtin.file:
        path: "{{ app_directory }}"
        state: directory
        owner: "{{ deploy_user }}"    # 'deploy_user' comes from inventory group vars
        mode: '0755'

    # TASK 4: Conditional — only run on Debian/Ubuntu hosts
    # ansible_facts['os_family'] is populated by gather_facts: true above
    - name: Install Node.js on Debian-based hosts
      ansible.builtin.shell: |
        curl -fsSL https://deb.nodesource.com/setup_{{ node_version }}.x | bash -
        apt-get install -y nodejs
      when: ansible_facts['os_family'] == 'Debian'
      args:
        creates: /usr/bin/node   # Skip this task entirely if /usr/bin/node already exists

    # TASK 5: Ensure the webapp systemd service is enabled and running
    - name: Enable and start webapp service
      ansible.builtin.service:
        name: webapp
        state: started
        enabled: true           # Ensures it survives a server reboot
      notify: Restart application service

# Directory structure of the nginx_proxy role:
# roles/
# └── nginx_proxy/
#     ├── tasks/
#     │   └── main.yml        <- you are here
#     ├── handlers/
#     │   └── main.yml        <- handlers scoped to this role
#     ├── templates/
#     │   └── nginx.conf.j2   <- Jinja2 config template
#     ├── defaults/
#     │   └── main.yml        <- lowest-priority variables (safe to override)
#     ├── vars/
#     │   └── main.yml        <- higher-priority vars (internal role constants)
#     └── meta/
#         └── main.yml        <- role metadata and dependencies

# roles/nginx_proxy/defaults/main.yml — overridable defaults
# nginx_worker_processes: auto
# nginx_client_max_body_size: "10m"
# backend_port: "{{ app_port }}"   <- inherits from inventory group vars

---
# roles/nginx_proxy/tasks/main.yml

- name: Install Nginx
  ansible.builtin.apt:
    name: "nginx"
    state: present
    update_cache: true

- name: Remove default Nginx site to avoid port conflicts
  ansible.builtin.file:
    path: /etc/nginx/sites-enabled/default
    state: absent             # Deletes the file if it exists — idempotent
  notify: Reload Nginx        # Reload is gentler than restart — no dropped connections

- name: Deploy reverse proxy config from template
  ansible.builtin.template:
    src: nginx.conf.j2        # Ansible looks in roles/nginx_proxy/templates/ automatically
    dest: /etc/nginx/sites-available/webapp
    validate: 'nginx -t -c %s'  # Runs nginx syntax check BEFORE writing the file to disk
  notify: Reload Nginx

- name: Enable webapp site by symlinking into sites-enabled
  ansible.builtin.file:
    src: /etc/nginx/sites-available/webapp
    dest: /etc/nginx/sites-enabled/webapp
    state: link               # Creates a symlink — Nginx's standard activation mechanism
  notify: Reload Nginx

- name: Ensure Nginx is started and enabled on boot
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

---
# roles/nginx_proxy/handlers/main.yml

- name: Reload Nginx
  ansible.builtin.service:
    name: nginx
    state: reloaded           # Graceful config reload — no dropped connections

---
# site_playbook.yml — the top-level playbook that consumes roles
# This is now just 12 lines instead of 150

- name: Deploy full application stack to production web servers
  hosts: web_servers
  become: true

  roles:
    - role: nginx_proxy
      vars:
        nginx_client_max_body_size: "25m"   # Override the default for this specific play
    - role: nodejs_app                       # A second role installed from requirements.yml