Introduction to Ansible — Automate Infrastructure Without an Agent

Before configuration management tools, sysadmins maintained hundreds of servers by hand — logging in, running commands, hoping nothing went wrong. I lived this. In 2015, I managed a fleet of 80 web servers at a mid-size SaaS company, and every deploy night was a three-hour marathon of SSH sessions, copy-pasted commands, and prayer. One night, someone restarted the wrong database server. We lost four hours of customer data. That was the last straw.

Ansible was created by Michael DeHaan in 2012 and acquired by Red Hat in 2015 (now part of IBM). Today it runs infrastructure at NASA JPL, Capital One, and thousands of companies from Series A startups to Fortune 50 enterprises. Not because it's the most powerful automation tool, but because it's the simplest one that actually gets used.

What makes Ansible different from competitors like Chef and Puppet is that it is agentless. There is no daemon running on your managed servers, no SSL certificates to exchange, and no extra ports to open beyond standard SSH (or WinRM for Windows). Ansible runs from your control node, pushes small programs called 'Ansible Modules' to the remote nodes, executes them, and then cleans up after itself.

One important nuance: Ansible and Terraform are not competitors — they're complementary. Terraform creates infrastructure (provisions the server). Ansible configures that server (installs software, deploys code, manages services). In practice, most teams use Terraform to build the house and Ansible to furnish it.

In this guide, we'll break down Ansible's core architecture — inventories, playbooks, modules, and roles — cover ad-hoc commands for quick fleet operations, and build production-grade automation with real error handling, secret management, and reusable patterns.

Inventory, Playbooks, and Modules — The Three Core Concepts

Ansible's architecture relies on three primary building blocks.

1. The Inventory: A simple file (INI or YAML) that lists the servers you want to manage. You can organize these into groups like [webservers] or [databases] to target specific logic to specific hardware. In production, you'll often use dynamic inventory — pulling host lists directly from AWS, GCP, or Azure APIs so your inventory stays accurate as servers are created and destroyed. Static inventories are fine for learning and small setups, but once you're past 20 servers with autoscaling, dynamic inventory isn't optional — it's survival.
2. The Playbook: This is your automation blueprint. Written in YAML, it maps a group of hosts to a series of tasks. Playbooks describe desired state, not step-by-step instructions. This distinction matters: if Nginx is already installed and running, Ansible doesn't reinstall it. It checks, confirms, and moves on.
3. Modules: These are the 'tools' in the toolbox. Instead of writing complex bash scripts, you use modules like apt, yum, service, or copy. These modules are idempotent, meaning they check the current state of the server and only make changes if the server doesn't already match your desired state. The shell and command modules are the notable exceptions — they run blindly every time, which is why experienced Ansible users avoid them unless there's no dedicated module alternative.

# io.thecodeforge: Inventory for Project Forge

[webservers]
web-01.thecodeforge.io ansible_host=192.168.1.10 ansible_user=ubuntu
web-02.thecodeforge.io ansible_host=192.168.1.11 ansible_user=ubuntu

[databases]
db-01.thecodeforge.io  ansible_host=192.168.1.20 ansible_user=ubuntu

[production:children]
webservers
databases

[production:vars]
ansible_ssh_private_key_file=~/.ssh/forge_deploy_key

Your First Production Playbook

A playbook is a collection of 'plays'. Each play targets a specific group from your inventory and executes a sequence of tasks.

Ansible processes tasks in order, from top to bottom. If a task fails on a specific host, Ansible will stop executing the rest of the playbook for that host but continue for others. To handle configuration changes — like restarting a web server only when a config file is updated — Ansible uses Handlers. Handlers are special tasks that only run when 'notified' by another task that actually changed something.

Here's a production playbook we actually use. Notice the structure: update the package cache, install the binary, deploy a templated config, ensure the service is running. Every task is idempotent. Every task uses a dedicated module. No shell commands anywhere.

One thing the Ansible docs don't emphasize enough: variable precedence will bite you if you don't understand it. Ansible has a 22-level precedence ladder. Variables defined with -e on the command line override everything. Role defaults are the weakest. Variables in group_vars override role defaults but get overridden by host_vars. When a playbook behaves 'randomly' — applying different values on different runs — it's almost always a precedence conflict. Learn the hierarchy early. It will save you hours of debugging.

---
# io.thecodeforge: Standard Nginx Deployment Playbook
- name: Deploy and Configure Nginx
  hosts: webservers
  become: true

  vars:
    nginx_port: 80
    server_name: "thecodeforge.io"

  tasks:
    - name: Ensure apt cache is updated
      ansible.builtin.apt:
        update_cache: yes
        cache_valid_time: 3600

    - name: Install Nginx production package
      ansible.builtin.apt:
        name: nginx
        state: present

    - name: Deploy custom Nginx configuration
      ansible.builtin.template:
        src: templates/nginx.conf.j2
        dest: /etc/nginx/sites-available/default
        owner: root
        group: root
        mode: '0644'
      notify: Reload Nginx service

    - name: Ensure Nginx service is enabled and running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: yes

  handlers:
    - name: Reload Nginx service
      ansible.builtin.service:
        name: nginx
        state: reloaded

Ad-hoc Commands — Quick Fleet Operations Without a Playbook

Not everything needs a playbook. Sometimes you need to run a single command across your fleet right now — check disk space, restart a hung service, verify a patch applied. That's what ad-hoc commands are for.

Ad-hoc commands are Ansible's secret weapon for day-two operations. They're the reason senior SREs reach for Ansible over SSH loops. An SSH for-loop runs the command on every server sequentially and gives you raw output. Ansible ad-hoc runs in parallel, returns structured JSON, and handles failures gracefully.

Syntax: ansible <host-pattern> -i <inventory> -m <module> -a '<arguments>'

In production, I use ad-hoc commands daily. Checking if all nodes in a 200-server fleet have enough disk space before a deploy? That's a one-liner. Killing a run-away process across 50 app servers? One-liner. Gathering system facts to verify a kernel patch applied? One-liner. These replace what used to be 20-minute SSH marathons.

# io.thecodeforge: Ad-hoc Command Reference

# Ping all production hosts to verify SSH connectivity
ansible production -i inventory.ini -m ping

# Check disk space across all web servers
ansible webservers -i inventory.ini -m command -a "df -h"

# Restart Nginx on all web servers immediately
ansible webservers -i inventory.ini -m service -a "name=nginx state=restarted" --become

# Gather system facts (CPU, memory, OS) from one host
ansible db-01.thecodeforge.io -i inventory.ini -m setup

# Install a security patch across the fleet
ansible production -i inventory.ini -m apt -a "name=openssl state=latest update_cache=yes" --become

Roles — Reusable Automation at Scale

Once your playbooks grow beyond 50 lines, you'll start copying tasks between files. That's when you need roles. A role is a self-contained unit of automation — tasks, handlers, templates, default variables, and files — packaged in a standardized directory structure. Roles are how Ansible scales from 'one playbook' to 'an entire infrastructure codebase.'

The directory structure isn't optional decoration. It's Ansible's loading convention. When you reference a role, Ansible automatically loads tasks/main.yml, handlers/main.yml, defaults/main.yml, and so on. Skip the convention and things silently don't load.

Roles come from two sources: you write your own, or you pull community roles from Ansible Galaxy (ansible-galaxy install geerlingguy.nginx). Galaxy has thousands of pre-built roles. For common software — Nginx, Docker, PostgreSQL, certbot — a community role saves hours. For your application-specific logic — deploying your Java app, configuring your monitoring — you write your own.

In our production codebase at io.thecodeforge, every server role follows the same pattern: a defaults/main.yml with sane defaults, a tasks/main.yml with the core logic, and a templates/ directory with Jinja2 config files. When a new engineer joins, they can read any role and understand it immediately because the structure is predictable.

---
# io.thecodeforge: Reusable Nginx Role
# Directory structure:
# roles/nginx/
#   ├── defaults/main.yml    (default variables)
#   ├── handlers/main.yml    (service reload/restart)
#   ├── tasks/main.yml       (this file)
#   └── templates/
#       └── vhost.conf.j2

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

- name: Deploy virtual host configuration
  ansible.builtin.template:
    src: vhost.conf.j2
    dest: "/etc/nginx/sites-available/{{ server_name }}.conf"
    owner: root
    group: root
    mode: '0644'
  notify: Reload Nginx

- name: Enable virtual host
  ansible.builtin.file:
    src: "/etc/nginx/sites-available/{{ server_name }}.conf"
    dest: "/etc/nginx/sites-enabled/{{ server_name }}.conf"
    state: link
  notify: Reload Nginx

- name: Ensure Nginx is running
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: yes

Production Patterns — Error Handling, Vault, and Rolling Deploys

The playbook we built above works great for a single server. But production is messier. Databases fail mid-migration. Network blips cause intermittent SSH timeouts. You need to deploy to 50 servers without taking all 50 offline simultaneously. And you absolutely cannot store database passwords in plain text YAML committed to Git.

Error Handling with block/rescue/always: Ansible has a try/catch equivalent. Wrap risky tasks in a block. If anything inside fails, the rescue section runs — rollback, alert, log. The always section runs regardless — cleanup, notifications. Without this, a failed database migration leaves your server in a half-configured state with no automatic recovery.

Rolling Deploys with serial: The serial keyword controls how many hosts Ansible processes at once. serial: 3 means 'update 3 servers, verify they're healthy, then move to the next 3.' Without serial, Ansible hits all hosts simultaneously — which is fine for config management but catastrophic for application deploys where you need zero-downtime.

Ansible Vault for Secrets: Never commit plain-text passwords to version control. Vault encrypts individual variables or entire files. In CI/CD, you pass the vault password via environment variable or a password file. This keeps secrets out of your playbooks, out of your logs, and out of your Git history.

---
# io.thecodeforge: Production Deploy with Error Handling
- name: Deploy Application with Safety Rails
  hosts: webservers
  become: true
  serial: 3              # Rolling deploy: 3 servers at a time
  max_fail_percentage: 0 # Stop everything if any server fails

  vars_files:
    - vault/secrets.yml  # Encrypted with ansible-vault

  tasks:
    - name: Deploy application release
      block:
        - name: Pull latest code
          ansible.builtin.git:
            repo: "https://github.com/thecodeforge/app.git"
            dest: /opt/app
            version: "{{ release_version }}"

        - name: Run database migrations
          ansible.builtin.command:
            cmd: /opt/app/bin/migrate --env production
          args:
            chdir: /opt/app

        - name: Verify application health endpoint
          ansible.builtin.uri:
            url: "http://localhost:8080/health"
            status_code: 200
          retries: 5
          delay: 3

      rescue:
        - name: Log deployment failure
          ansible.builtin.debug:
            msg: "Deploy FAILED on {{ inventory_hostname }} — rolling back to {{ previous_release }}"

        - name: Rollback to previous release
          ansible.builtin.git:
            repo: "https://github.com/thecodeforge/app.git"
            dest: /opt/app
            version: "{{ previous_release }}"

      always:
        - name: Notify deployment status
          ansible.builtin.uri:
            url: "{{ webhook_url }}"
            method: POST
            body_format: json
            body:
              host: "{{ inventory_hostname }}"
              status: "{{ 'success' if ansible_failed_task is not defined else 'failed' }}"

Frequently Asked Questions