DEV Community

Maksym
Maksym

Posted on

Complete Ansible Guide

#docker #containers #ansible

What is Ansible?

Ansible is an open-source automation platform that simplifies configuration management, application deployment, task automation, and orchestration. It uses a simple, human-readable language (YAML) and operates over SSH without requiring agents on target machines.

Key Benefits

  • Agentless: No need to install software on target machines
  • Simple: Uses YAML syntax that's easy to read and write
  • Powerful: Can manage complex multi-tier deployments
  • Idempotent: Safe to run multiple times without side effects
  • Secure: Uses SSH and doesn't leave software installed on targets

Core Concepts

Inventory

A list of managed nodes (servers, network devices, etc.) that Ansible controls. Can be static files or dynamic sources.

Playbooks

YAML files containing a series of tasks to execute on target hosts. Think of them as automation scripts.

Tasks

Individual units of work that Ansible executes, like installing packages or copying files.

Modules

Reusable units of code that Ansible executes. Examples: yum, copy, service, user.

Roles

Way to organize playbooks and reuse code. Roles group related tasks, variables, files, and templates.

Variables

Data that can change how playbooks behave. Can be defined in multiple places with different precedence levels.

Installation

On Control Node (where you run Ansible)

Using pip:

pip install ansible
Enter fullscreen mode Exit fullscreen mode

Using package managers:

# Ubuntu/Debian
sudo apt update
sudo apt install ansible

# CentOS/RHEL/Fedora
sudo dnf install ansible
# or
sudo yum install ansible

# macOS
brew install ansible
Enter fullscreen mode Exit fullscreen mode

Basic Configuration

Ansible Configuration File

Create /etc/ansible/ansible.cfg or ~/.ansible.cfg:

[defaults]
inventory = ./inventory
host_key_checking = False
retry_files_enabled = False
gathering = smart
fact_caching = memory

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
pipelining = True
Enter fullscreen mode Exit fullscreen mode

Inventory Management

Static Inventory

Basic inventory file (inventory or hosts):

# Individual hosts
web1.example.com
web2.example.com

# Groups
[webservers]
web1.example.com
web2.example.com

[databases]
db1.example.com
db2.example.com

# Groups of groups
[production:children]
webservers
databases

# Variables
[webservers:vars]
http_port=80
nginx_version=1.18
Enter fullscreen mode Exit fullscreen mode

YAML inventory format:

all:
  hosts:
    web1.example.com:
    web2.example.com:
  children:
    webservers:
      hosts:
        web1.example.com:
        web2.example.com:
      vars:
        http_port: 80
    databases:
      hosts:
        db1.example.com:
        db2.example.com:
Enter fullscreen mode Exit fullscreen mode

Dynamic Inventory

For cloud environments, you can use dynamic inventory scripts or plugins that query cloud APIs.

Ad-hoc Commands

Run single tasks without playbooks:

# Ping all hosts
ansible all -m ping

# Check uptime
ansible webservers -m command -a "uptime"

# Install package
ansible webservers -m yum -a "name=nginx state=present" --become

# Copy file
ansible webservers -m copy -a "src=/local/file dest=/remote/file"

# Start service
ansible webservers -m service -a "name=nginx state=started enabled=yes" --become
Enter fullscreen mode Exit fullscreen mode

Playbooks

Basic Playbook Structure 

---
- name: Web server setup
  hosts: webservers
  become: yes
  vars:
    http_port: 80

  tasks:
    - name: Install nginx
      yum:
        name: nginx
        state: present

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

    - name: Open firewall for HTTP
      firewalld:
        port: "{{ http_port }}/tcp"
        permanent: yes
        state: enabled
        immediate: yes
Enter fullscreen mode Exit fullscreen mode

Advanced Playbook Features

Handlers (run when notified):

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
Enter fullscreen mode Exit fullscreen mode

Conditionals:

tasks:
  - name: Install Apache (RedHat family)
    yum:
      name: httpd
      state: present
    when: ansible_os_family == "RedHat"

  - name: Install Apache (Debian family)
    apt:
      name: apache2
      state: present
    when: ansible_os_family == "Debian"
Enter fullscreen mode Exit fullscreen mode

Loops:

tasks:
  - name: Create users
    user:
      name: "{{ item.name }}"
      group: "{{ item.group }}"
      shell: "{{ item.shell | default('/bin/bash') }}"
    loop:
      - { name: alice, group: admin }
      - { name: bob, group: users }
      - { name: charlie, group: users, shell: /bin/zsh }
Enter fullscreen mode Exit fullscreen mode

Error handling:

tasks:
  - name: Attempt risky operation
    command: /bin/false
    ignore_errors: yes
    register: result

  - name: Handle failure
    debug:
      msg: "Previous task failed, but continuing"
    when: result is failed
Enter fullscreen mode Exit fullscreen mode

Variables and Templates

Variable Precedence (highest to lowest)

  1. Command line values (-e)
  2. Role defaults
  3. Inventory file variables
  4. Host facts
  5. Play variables
  6. Role variables
  7. Block variables
  8. Task variables

Using Templates (Jinja2)

Template file (templates/nginx.conf.j2):

server {
    listen {{ http_port }};
    server_name {{ ansible_hostname }};

    location / {
        root /var/www/html;
        index index.html;
    }
}
Enter fullscreen mode Exit fullscreen mode

Using the template:

- name: Deploy nginx config
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/conf.d/default.conf
  notify: restart nginx
Enter fullscreen mode Exit fullscreen mode

Roles

Role Directory Structure 

roles/
  webserver/
    tasks/
      main.yml
    handlers/
      main.yml
    templates/
      nginx.conf.j2
    files/
      index.html
    vars/
      main.yml
    defaults/
      main.yml
    meta/
      main.yml
Enter fullscreen mode Exit fullscreen mode

Using Roles in Playbooks 

---
- name: Configure web servers
  hosts: webservers
  roles:
    - common
    - webserver
    - { role: monitoring, when: monitoring_enabled }
Enter fullscreen mode Exit fullscreen mode

Creating Roles with Ansible Galaxy 

# Create role structure
ansible-galaxy init webserver

# Install role from Galaxy
ansible-galaxy install geerlingguy.nginx

# Install from requirements file
ansible-galaxy install -r requirements.yml
Enter fullscreen mode Exit fullscreen mode

Common Modules

System Modules

  • yum/apt - Package management
  • service/systemd - Service management
  • user/group - User management
  • cron - Crontab management
  • mount - Filesystem mounting

File Modules

  • copy - Copy files to remote hosts
  • template - Process Jinja2 templates
  • file - Set file attributes
  • lineinfile - Ensure line in file
  • replace - Replace text in files

Command Modules

  • command - Run commands
  • shell - Run shell commands
  • script - Run local script on remote hosts
  • raw - Run raw SSH commands

Cloud Modules

  • ec2 - AWS EC2 management
  • azure_rm_* - Azure resource management
  • gcp_* - Google Cloud Platform

Best Practices

Playbook Organization

  • Use descriptive names for plays and tasks
  • Keep playbooks focused and modular
  • Use roles for reusable code
  • Group related functionality together

Variable Management

  • Use group_vars and host_vars directories
  • Keep sensitive data in Ansible Vault
  • Use meaningful variable names
  • Document variable purposes

Security

  • Use Ansible Vault for sensitive data
  • Limit sudo usage with become_user
  • Use SSH key authentication
  • Regularly update Ansible

Testing

  • Use --check mode for dry runs
  • Test on non-production first
  • Use ansible-lint for syntax checking
  • Version control your playbooks

Ansible Vault

Encrypting Files 

# Create encrypted file
ansible-vault create secret.yml

# Encrypt existing file
ansible-vault encrypt secret.yml

# Edit encrypted file
ansible-vault edit secret.yml

# View encrypted file
ansible-vault view secret.yml

# Decrypt file
ansible-vault decrypt secret.yml
Enter fullscreen mode Exit fullscreen mode

Using Vaulted Variables 

# Run playbook with vault password
ansible-playbook site.yml --ask-vault-pass

# Use password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass
Enter fullscreen mode Exit fullscreen mode

Running Playbooks

Basic Execution 

# Run playbook
ansible-playbook site.yml

# Dry run (check mode)
ansible-playbook site.yml --check

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

# Use different inventory
ansible-playbook site.yml -i production

# Override variables
ansible-playbook site.yml -e "http_port=8080"

# Increase verbosity
ansible-playbook site.yml -vvv
Enter fullscreen mode Exit fullscreen mode

Tags 

tasks:
  - name: Install packages
    yum:
      name: "{{ item }}"
      state: present
    loop: "{{ packages }}"
    tags: packages

  - name: Configure service
    template:
      src: config.j2
      dest: /etc/service/config
    tags: config
Enter fullscreen mode Exit fullscreen mode 
# Run only tagged tasks
ansible-playbook site.yml --tags packages

# Skip tagged tasks
ansible-playbook site.yml --skip-tags config
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Common Issues

  • SSH connectivity problems
  • Permission errors (use --become)
  • Python interpreter issues
  • Module not found errors
  • YAML syntax errors

Debugging Commands 

# Verbose output
ansible-playbook site.yml -vvv

# Debug specific host
ansible hostname -m setup

# Check inventory
ansible-inventory --list

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

# List tasks
ansible-playbook site.yml --list-tasks
Enter fullscreen mode Exit fullscreen mode

Example: Complete Web Server Deployment 

---
- name: Deploy web application
  hosts: webservers
  become: yes
  vars:
    app_name: myapp
    app_port: 8080

  tasks:
    - name: Update system packages
      yum:
        name: "*"
        state: latest
      tags: system

    - name: Install required packages
      yum:
        name:
          - nginx
          - python3
          - git
        state: present
      tags: packages

    - name: Create application user
      user:
        name: "{{ app_name }}"
        system: yes
        shell: /bin/false
        home: "/opt/{{ app_name }}"
        create_home: yes
      tags: users

    - name: Clone application repository
      git:
        repo: https://github.com/company/myapp.git
        dest: "/opt/{{ app_name }}/app"
        version: main
      become_user: "{{ app_name }}"
      tags: deploy

    - name: Install application dependencies
      pip:
        requirements: "/opt/{{ app_name }}/app/requirements.txt"
        virtualenv: "/opt/{{ app_name }}/venv"
      become_user: "{{ app_name }}"
      tags: deploy

    - name: Configure nginx
      template:
        src: nginx-app.conf.j2
        dest: "/etc/nginx/conf.d/{{ app_name }}.conf"
      notify: restart nginx
      tags: config

    - name: Configure systemd service
      template:
        src: app.service.j2
        dest: "/etc/systemd/system/{{ app_name }}.service"
      notify:
        - reload systemd
        - restart app
      tags: config

    - name: Start and enable services
      service:
        name: "{{ item }}"
        state: started
        enabled: yes
      loop:
        - nginx
        - "{{ app_name }}"
      tags: services

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

    - name: reload systemd
      systemd:
        daemon_reload: yes

    - name: restart app
      service:
        name: "{{ app_name }}"
        state: restarted
Enter fullscreen mode Exit fullscreen mode

This guide covers the fundamentals of Ansible. Start with simple playbooks and gradually incorporate more advanced features as you become comfortable with the basics.

Top comments (0)