Ansible Documentation - Complete Guide

Overview

This directory contains comprehensive Ansible documentation covering fundamentals, authentication, playbooks, roles, and advanced topics. Each file includes detailed explanations, workflow diagrams, and practical examples.

Documentation Structure

Core Topics

1. Ansible Fundamentals
2. What is Ansible and why use it
3. Ansible vs Shell Scripts vs Python
4. Architecture and core components
5. Installation on multiple platforms
6. VS Code IDE setup and configuration

7. Project structure and best practices

8. SSH Authentication and Inventory

9. SSH key-based authentication
10. Passwordless authentication setup
11. SSH agent configuration
12. Troubleshooting SSH issues
13. Ansible inventory (INI and YAML)
14. Dynamic inventory (AWS, Azure, GCP)

15. Inventory best practices

16. Ansible Playbooks (Already created)

17. Basic playbook examples
18. Web server setup (Nginx)
19. Application deployment (Node.js)
20. Database configuration (PostgreSQL)
21. Security hardening
22. Monitoring setup

23. Best practices

24. Ad-hoc Commands (To be created)

25. Understanding ad-hoc commands
26. Common use cases
27. Module examples

28. When to use vs playbooks

29. Ansible Roles (To be created)

30. What are roles and why use them
31. Role structure and organization
32. Creating custom roles
33. Ansible Galaxy
34. Role dependencies

35. Best practices

36. Variables and Precedence (To be created)

37. Variable types and scope
38. Variable precedence order
39. Jinja2 templating
40. Facts and magic variables

41. Registered variables

42. Conditionals and Loops (To be created)

43. When statements
44. Loop types (with_items, loop, etc.)
45. Conditional loops

46. Failed_when and changed_when

47. Error Handling (To be created)

48. Handling failures
49. Blocks and rescue
50. Ignore errors
51. Retry logic

52. Debugging techniques

53. Ansible Vault (To be created)

54. Encrypting sensitive data
55. Vault commands
56. Best practices for secrets

57. Integration with CI/CD

58. Advanced Topics (To be created)

    • Collections
    • Custom modules
    • Plugins
    • Ansible Tower/AWX
    • Network automation

Quick Start

Installation

# Ubuntu/Debian
sudo apt update
sudo apt install ansible

# CentOS/RHEL
sudo yum install epel-release
sudo yum install ansible

# macOS
brew install ansible

# Using pip
pip install ansible

Basic Usage

# Test connection
ansible all -m ping

# Run ad-hoc command
ansible all -m shell -a "uptime"

# Run playbook
ansible-playbook playbook.yml

# Check syntax
ansible-playbook playbook.yml --syntax-check

# Dry run
ansible-playbook playbook.yml --check

Learning Path

Beginner (Week 1-2)

1. Start with Fundamentals
2. Understand Ansible architecture
3. Install and configure Ansible
4. Set up SSH authentication

5. Learn inventory basics

6. Practice Ad-hoc Commands

7. Run simple commands
8. Explore common modules

9. Understand module documentation

10. Write First Playbook

11. Learn YAML syntax
12. Create simple playbooks
13. Understand tasks and modules

Intermediate (Week 3-4)

1. Master Playbooks
2. Complex playbook structures
3. Use handlers and notifications

4. Implement error handling

5. Learn Roles

6. Create custom roles
7. Use Ansible Galaxy

8. Organize code with roles

9. Work with Variables

10. Understand variable precedence
11. Use Jinja2 templates
12. Implement conditionals and loops

Advanced (Week 5-6)

1. Security and Vault
2. Encrypt sensitive data
3. Manage secrets properly

4. Implement security best practices

5. Advanced Features

6. Dynamic inventory
7. Custom modules

8. Collections and plugins

9. Production Deployment

10. CI/CD integration
11. Ansible Tower/AWX
12. Monitoring and logging

Common Use Cases

1. Server Configuration

---
- name: Configure web servers
  hosts: webservers
  become: yes
  tasks:
    - name: Install packages
      apt:
        name:
          - nginx
          - python3
          - git
        state: present

    - name: Start nginx
      service:
        name: nginx
        state: started
        enabled: yes

2. Application Deployment

---
- name: Deploy application
  hosts: appservers
  tasks:
    - name: Clone repository
      git:
        repo: https://github.com/user/app.git
        dest: /opt/app
        version: main

    - name: Install dependencies
      pip:
        requirements: /opt/app/requirements.txt

    - name: Restart application
      systemd:
        name: myapp
        state: restarted

3. Database Setup

---
- name: Setup PostgreSQL
  hosts: databases
  become: yes
  tasks:
    - name: Install PostgreSQL
      apt:
        name: postgresql
        state: present

    - name: Create database
      postgresql_db:
        name: myapp
        state: present
      become_user: postgres

Ansible Modules Reference

System Modules

Module	Purpose	Example
apt	Package management (Debian)	apt: name=nginx state=present
yum	Package management (RedHat)	yum: name=httpd state=latest
service	Service management	service: name=nginx state=started
systemd	Systemd service management	systemd: name=nginx enabled=yes
user	User management	user: name=john state=present
group	Group management	group: name=developers state=present
file	File/directory management	file: path=/tmp/test state=directory
copy	Copy files	copy: src=file.txt dest=/tmp/
template	Jinja2 templates	template: src=config.j2 dest=/etc/app/config

Command Modules

Module	Purpose	Example
command	Execute commands	command: /usr/bin/uptime
shell	Execute shell commands	shell: echo $HOME
script	Run local script on remote	script: /tmp/script.sh
raw	Execute raw commands	raw: apt-get update

Cloud Modules

Module	Purpose	Example
ec2	AWS EC2 instances	ec2: instance_type=t2.micro
s3_bucket	AWS S3 buckets	s3_bucket: name=mybucket state=present
azure_rm_virtualmachine	Azure VMs	azure_rm_virtualmachine: name=myvm
gcp_compute_instance	GCP instances	gcp_compute_instance: name=myinstance

Best Practices

1. Project Structure

ansible-project/
├── ansible.cfg
├── inventory/
│   ├── production/
│   │   ├── hosts.ini
│   │   └── group_vars/
│   └── staging/
│       ├── hosts.ini
│       └── group_vars/
├── playbooks/
│   ├── site.yml
│   ├── webservers.yml
│   └── databases.yml
├── roles/
│   ├── common/
│   ├── webserver/
│   └── database/
├── group_vars/
│   └── all.yml
├── host_vars/
└── files/

2. Naming Conventions

• Playbooks: Use descriptive names (deploy-webapp.yml)
• Roles: Use lowercase with hyphens (web-server)
• Variables: Use snake_case (http_port)
• Tasks: Start with verb (Install nginx, Copy configuration)

3. Idempotency

# Good - Idempotent
- name: Ensure nginx is installed
  apt:
    name: nginx
    state: present

# Bad - Not idempotent
- name: Install nginx
  shell: apt-get install nginx

4. Use Roles for Reusability

# Instead of repeating tasks
- hosts: webservers
  roles:
    - common
    - webserver
    - monitoring

5. Encrypt Sensitive Data

# Encrypt file
ansible-vault encrypt secrets.yml

# Use in playbook
ansible-playbook playbook.yml --ask-vault-pass

6. Test Before Production

# Syntax check
ansible-playbook playbook.yml --syntax-check

# Dry run
ansible-playbook playbook.yml --check

# Run on staging first
ansible-playbook -i inventory/staging playbook.yml

Troubleshooting

Common Issues

1. SSH Connection Failed

# Check SSH connectivity
ssh user@host

# Verify inventory
ansible-inventory --list

# Test with verbose output
ansible all -m ping -vvv

2. Module Not Found

# Install required collection
ansible-galaxy collection install community.general

# Verify module exists
ansible-doc module_name

3. Permission Denied

# Use become for privilege escalation
ansible-playbook playbook.yml --become --ask-become-pass

# Or in playbook
become: yes
become_user: root

4. Variable Not Defined

# Check variable precedence
ansible-playbook playbook.yml -e "var_name=value"

# Debug variables
- debug:
    var: variable_name

Useful Commands

Inventory

# List all hosts
ansible all --list-hosts

# List hosts in group
ansible webservers --list-hosts

# Show inventory graph
ansible-inventory --graph

# Show host variables
ansible-inventory --host hostname

Playbooks

# Run playbook
ansible-playbook playbook.yml

# Limit to specific hosts
ansible-playbook playbook.yml --limit webservers

# Start at specific task
ansible-playbook playbook.yml --start-at-task="Install nginx"

# Use tags
ansible-playbook playbook.yml --tags "configuration"

# Skip tags
ansible-playbook playbook.yml --skip-tags "testing"

Ad-hoc Commands

# Run command on all hosts
ansible all -m command -a "uptime"

# Copy file
ansible all -m copy -a "src=/tmp/file dest=/tmp/file"

# Install package
ansible all -m apt -a "name=nginx state=present" --become

# Restart service
ansible all -m service -a "name=nginx state=restarted" --become

Vault

# Create encrypted file
ansible-vault create secrets.yml

# Edit encrypted file
ansible-vault edit secrets.yml

# Encrypt existing file
ansible-vault encrypt file.yml

# Decrypt file
ansible-vault decrypt file.yml

# View encrypted file
ansible-vault view secrets.yml

# Change password
ansible-vault rekey secrets.yml

Resources

Official Documentation

• Ansible Documentation
• Ansible Galaxy
• Ansible Module Index

Community

• Ansible GitHub
• Ansible Forum
• Reddit r/ansible

Learning Resources

• Ansible for DevOps
• Ansible Best Practices
• Ansible Examples

Contributing

When adding new Ansible documentation: 1. Follow the established format 2. Include workflow diagrams 3. Provide practical examples 4. Add troubleshooting sections 5. Include best practices 6. Update this README

Summary

This Ansible documentation provides: - Comprehensive coverage from basics to advanced topics - Visual diagrams for better understanding - Practical examples for real-world scenarios - Best practices for production use - Troubleshooting guides for common issues - Quick references for commands and modules

Perfect for DevOps engineers, system administrators, and anyone automating infrastructure with Ansible.

---

Last Updated: January 6, 2026
Status: ✅ Core topics documented with diagrams
Next: Complete remaining topics (Ad-hoc, Roles, Variables, Vault, Advanced)