🧭 Ansible Complete Reference Guide

Author’s Note:
This guide is built from a real automation setup using Ansible for managing Proxmox and Terraform-created environments.
It is written in a narrative, KB-style tone to serve as both a learning and reference resource.

⚙️ Introduction: Why Ansible

Ansible is an open-source configuration management and automation tool developed by Red Hat.
It automates software provisioning, configuration, and orchestration across servers — all using simple YAML playbooks.

Key benefits:

• Agentless — no software needed on the target systems.
• Uses SSH or WinRM for connectivity.
• Idempotent — only applies changes if required.
• Human-readable YAML syntax.

💡 Tip: Ansible is most powerful when combined with Terraform — Terraform provisions infrastructure, and Ansible configures it.

🧰 Installing Ansible

On Ubuntu / Debian

sudo apt update && sudo apt install ansible -y

Verify installation:

ansible --version
ansible-config list
ansible-doc -l

Recommended Directory Layout

/home/automation/ansible/
├── ansible.cfg
├── inventory.ini
├── playbooks/
│   └── site.yml
└── roles/

💡 Keep your playbooks, inventory, and roles neatly separated. This structure scales well.

🧱 Understanding Core Components

Example Inventory:

[web]
10.0.4.10
10.0.4.11

[db]
10.0.4.20

Example Task:

- name: Update system packages
  apt:
    update_cache: yes
    upgrade: dist

⚙️ Ansible Configuration File (ansible.cfg)

Example configuration:

[defaults]
inventory = /home/automation/ansible/inventory.ini
remote_user = automation
host_key_checking = False
retry_files_enabled = False
forks = 10
timeout = 30

[ssh_connection]
pipelining = True
control_path = ~/.ssh/ansible-%%r@%%h:%%p

Useful commands:

ansible-config view
ansible-config dump --only-changed

💾 Inventory Management

Static Inventory Example

[web]
10.0.4.10 ansible_user=automation ansible_ssh_private_key_file=~/.ssh/id_rsa

[db]
10.0.4.20

Commands for Inventory

ansible-inventory --list
ansible all --list-hosts
ansible-inventory --graph

💡 Tip: Terraform can dynamically generate inventory for Ansible using outputs.

🧰 Common Ad-Hoc Commands

🧾 Writing Playbooks

Example Playbook:

---
- name: Initialize new containers
  hosts: all
  become: yes

  tasks:
    - name: Update and upgrade system
      apt:
        update_cache: yes
        upgrade: dist

    - name: Install connectivity tools
      apt:
        name:
          - traceroute
          - curl
          - net-tools
        state: present

    - name: Create user
      user:
        name: sony
        password: "{{ 'password' | password_hash('sha512') }}"
        groups: sudo
        create_home: yes

Run the playbook:

ansible-playbook playbooks/site.yml

🧩 Roles and Reusability

Structure of a role:

roles/
└── webserver/
    ├── tasks/main.yml
    ├── handlers/main.yml
    ├── vars/main.yml
    ├── templates/index.html.j2
    └── meta/main.yml

Initialize a new role:

ansible-galaxy init roles/webserver

Install community roles:

ansible-galaxy install geerlingguy.nginx
ansible-galaxy list

⚙️ Variables and Templates

Define variables:

vars:
  app_port: 8080

Template example (nginx.conf.j2):

server {
    listen {{ app_port }};
}

Apply template:

ansible all -m template -a "src=nginx.conf.j2 dest=/etc/nginx/sites-available/default"

🧠 Tags, Loops, and Conditionals

Loops

- name: Install multiple packages
  apt:
    name: "{{ item }}"
    state: present
  loop:
    - curl
    - vim
    - net-tools

Tags

- name: Install NGINX
  apt:
    name: nginx
    state: present
  tags: [install, web]

Run specific tags:

ansible-playbook site.yml --tags "install"

Conditionals

- name: Restart service only if Ubuntu
  service:
    name: nginx
    state: restarted
  when: ansible_distribution == "Ubuntu"

🔧 Handlers and Notifications

tasks:
  - name: Update nginx config
    template:
      src: nginx.conf.j2
      dest: /etc/nginx/nginx.conf
    notify:
      - Restart nginx

handlers:
  - name: Restart nginx
    service:
      name: nginx
      state: restarted

🧾 Ansible Vault (Secrets Management)

Encrypt sensitive files:

ansible-vault create secrets.yml
ansible-vault encrypt playbook.yml
ansible-vault decrypt playbook.yml

Run with password prompt:

ansible-playbook play.yml --ask-vault-pass

💡 Use --vault-password-file ~/.vault_pass.txt for automation.

🧩 Facts and Filters

Collect system facts:

ansible all -m setup

Filter facts:

ansible all -m setup -a "filter=ansible_distribution"

Example Jinja2 filter:

{{ ansible_hostname | upper }}

⚙️ Debugging & Troubleshooting

💡 Add --diff to preview file changes before applying.

🧾 Ansible Command Cheat Sheet

✅ Best Practices

• Keep a single inventory per environment (e.g., dev, prod).
• Store configurations in Git.
• Separate secrets into Vaults.
• Validate YAML with ansible-lint.
• Avoid hardcoded paths — use variables.
• Test using --check mode before production.

🧠 Conclusion

“Ansible is the configuration engine that turns your servers into ready systems.”

Combined with Terraform and Proxmox, it completes your end-to-end automation cycle:
Terraform provisions → Ansible configures → Your environment runs seamlessly.

Use this as a reference, a command companion, and a foundation for scaling your automation environment.

End of Guide — Ansible Complete Reference