Master Ansible Playbooks: From Basics to Large‑Scale Cluster Automation

Ansible Playbook Practical Guide: From Basics to Large‑Scale Cluster Automation

Why Choose Ansible?

In the cloud‑native era, manual operations become a bottleneck. Ansible enables agent‑less, SSH‑based automation, allowing efficient management of hundreds of servers.

Chapter 1: Core Concepts

1.1 Architecture: Control Node + Managed Nodes

# Typical Ansible architecture
ControlNode
├── ansible.cfg      # Global configuration
├── inventory/
│   ├── hosts.ini
│   └── group_vars/
├── playbooks/
└── roles/

Key Advantages

No agent required on target machines

SSH‑based, secure and reliable

Declarative syntax, easy to read and maintain

Idempotent execution ensures safe re‑runs

1.2 Core Components

Inventory (Host List)

[webservers]
web01 ansible_host=192.168.1.10
web02 ansible_host=192.168.1.11

[databases]
db01 ansible_host=192.168.1.20
db02 ansible_host=192.168.1.21

[all:vars]
ansible_user=deploy
ansible_ssh_private_key_file=~/.ssh/id_rsa

Playbook (Play)

---
- name: Deploy Web Application
  hosts: webservers
  become: yes
  vars:
    app_name: "myapp"
    app_version: "v1.2.0"
  tasks:
    - name: Install Nginx
      yum:
        name: nginx
        state: present
    - name: Start and enable Nginx
      systemd:
        name: nginx
        state: started
        enabled: yes

Chapter 2: Advanced Production‑Level Playbook Design

2.1 Variable Management Best Practices

Use layered variable files for clear separation.

# group_vars/webservers.yml
nginx_version: "1.20.2"
app_port: 8080
ssl_enabled: true

# host_vars/web01.yml
server_id: 1
local_storage_path: "/data/web01"

# Example task using variables
- name: Configure application port
  lineinfile:
    path: /etc/nginx/nginx.conf
    regexp: '^listen'
    line: "listen {{ app_port }};"

2.2 Role Architecture

Modularize complex deployments with roles.

roles/
├── common/          # Base environment configuration
│   ├── tasks/main.yml
│   ├── handlers/main.yml
│   └── vars/main.yml
├── nginx/           # Nginx‑specific role
└── mysql/           # MySQL‑specific role

Example common/tasks/main.yml:

---
- name: Update system packages
  yum:
    name: "*"
    state: latest
  when: ansible_os_family == "RedHat"

- name: Install basic tools
  package:
    name: "{{ item }}"
    state: present
  loop:
    - htop
    - vim
    - curl
    - wget

- name: Set timezone
  timezone:
    name: Asia/Shanghai

2.3 Error Handling and Rollback

- name: Main deployment flow
  block:
    - name: Backup current version
      archive:
        path: /opt/app
        dest: "/backup/app_{{ ansible_date_time.epoch }}.tar.gz"
    - name: Deploy new version
      git:
        repo: "{{ app_repo_url }}"
        dest: /opt/app
        version: "{{ app_version }}"
    - name: Restart application service
      systemd:
        name: "{{ app_service_name }}"
        state: restarted
  rescue:
    - name: Rollback to backup
      unarchive:
        src: "/backup/app_{{ ansible_date_time.epoch }}.tar.gz"
        dest: /opt/
        remote_src: yes
    - name: Restart service after rollback
      systemd:
        name: "{{ app_service_name }}"
        state: restarted

Chapter 3: Large‑Scale Cluster Deployment Case Study

3.1 Scenario: Deploying a 100+ Node Microservice Cluster

Challenges

Bulk server initialization

Multi‑environment configuration management

Batch rolling deployments

Service health checks

Solution Architecture

# site.yml – entry point
---
- import_playbook: playbooks/01-system-init.yml
- import_playbook: playbooks/02-docker-deploy.yml
- import_playbook: playbooks/03-app-deploy.yml
- import_playbook: playbooks/04-monitoring.yml

3.2 System Initialization Playbook

---
- name: Large‑scale cluster system initialization
  hosts: all
  serial: 20   # Process 20 hosts in parallel
  gather_facts: yes
  become: yes
  pre_tasks:
    - name: Check OS compatibility
      fail:
        msg: "Unsupported OS version"
      when:
        - ansible_distribution != "CentOS"
        - ansible_distribution_major_version|int < 7
  roles:
    - common
    - security
    - monitoring-agent
  post_tasks:
    - name: Verify critical services
      service_facts:
    - name: Ensure sshd is running
      assert:
        that:
          - ansible_facts.services["sshd.service"].state == "running"
          - ansible_facts.services["chronyd.service"].state == "running"

3.3 Docker Container Deployment

---
- name: Docker environment deployment
  hosts: app_servers
  serial: "30%"   # Parallel on 30% of nodes
  become: yes
  vars:
    docker_version: "20.10.17"
    docker_compose_version: "2.6.0"
  tasks:
    - name: Install Docker CE
      yum:
        name:
          - docker-ce-{{ docker_version }}
          - docker-ce-cli-{{ docker_version }}
          - containerd.io
        state: present
    - name: Configure Docker daemon
      template:
        src: docker-daemon.json.j2
        dest: /etc/docker/daemon.json
      notify: restart docker
    - name: Start Docker service
      systemd:
        name: docker
        state: started
        enabled: yes
  handlers:
    - name: restart docker
      systemd:
        name: docker
        state: restarted

3.4 Batch Rolling Deployment Strategy

---
- name: Microservice batch deployment
  hosts: app_servers
  serial: 5   # Deploy 5 hosts at a time
  max_fail_percentage: 10
  vars:
    deployment_strategy: "rolling"
    health_check_retries: 3
    health_check_delay: 10
  tasks:
    - name: Remove node from load balancer
      uri:
        url: "http://{{ load_balancer_host }}/api/remove/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost
    - name: Wait for connections to drain
      wait_for:
        timeout: 30
    - name: Stop old version
      docker_compose:
        project_src: /opt/app
        state: absent
    - name: Deploy new version
      docker_compose:
        project_src: /opt/app
        files:
          - docker-compose.yml
          - docker-compose.prod.yml
        state: present
        pull: yes
    - name: Health check
      uri:
        url: "http://{{ inventory_hostname }}:8080/health"
        status_code: 200
        retries: "{{ health_check_retries }}"
        delay: "{{ health_check_delay }}"
    - name: Re‑add node to load balancer
      uri:
        url: "http://{{ load_balancer_host }}/api/add/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost

Chapter 4: Performance Tuning & Troubleshooting

4.1 Ansible Performance Optimizations

Concurrency Control

# ansible.cfg
[defaults]
host_key_checking = False
forks = 50
callback_whitelist = timer, profile_tasks

[ssh_connection]
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
pipelining = True
control_path_dir = /tmp/.ansible-cp

Facts Collection Optimization

- name: Optimized task execution
  hosts: all
  gather_facts: no
  tasks:
    - name: Collect only necessary facts
      setup:
        gather_subset:
          - "!all"
          - "!min"
          - network
          - virtual

4.2 Common Issue Diagnosis

Connection Timeout

- name: Diagnose network connection
  wait_for:
    host: "{{ inventory_hostname }}"
    port: 22
    timeout: 5
  delegate_to: localhost
  ignore_errors: yes
  register: connection_test

- name: Report connection status
  debug:
    msg: "{{ inventory_hostname }} connection status: {{ 'SUCCESS' if connection_test.failed == false else 'FAILED' }}"

Chapter 5: Enterprise Practices & Security Hardening

5.1 Sensitive Data Management – Ansible Vault

# Create encrypted file
ansible-vault create secrets.yml

# Encrypt existing file
ansible-vault encrypt vars/database.yml

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

Example secrets.yml snippet:

database_password: !vault |
    $ANSIBLE_VAULT;1.1;AES256
    66386439653138363739653730636365396464333661643138656234323837653462613431613938
    3730623234643863666466303435346138666330363834660a653864373765623965383535633166

5.2 RBAC Permission Control

---
- name: System security hardening
  hosts: all
  become: yes
  tasks:
    - name: Create ops user group
      group:
        name: ops
        state: present
    - name: Configure sudo permissions for ops
      lineinfile:
        path: /etc/sudoers.d/ops
        line: "%ops ALL=(ALL) NOPASSWD: /usr/bin/systemctl, /usr/bin/docker"
        create: yes
        mode: '0440'
    - name: Disable root SSH login
      lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^PermitRootLogin'
        line: 'PermitRootLogin no'
      notify: restart sshd
  handlers:
    - name: restart sshd
      service:
        name: sshd
        state: restarted

5.3 CI/CD Integration – GitLab CI Example

# .gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - ansible-playbook -i inventory/prod site.yml --vault-password-file .vault_pass
  only:
    - main
  when: manual
  environment:
    name: production

Chapter 6: Monitoring & Reporting

6.1 Deploy Monitoring Stack (Prometheus + Grafana)

- name: Deploy Prometheus + Grafana monitoring
  hosts: monitoring
  become: yes
  tasks:
    - name: Create monitoring directory
      file:
        path: /opt/monitoring
        state: directory
    - name: Deploy monitoring services
      docker_compose:
        project_src: /opt/monitoring
        definition:
          version: '3.8'
          services:
            prometheus:
              image: prom/prometheus:latest
              ports:
                - "9090:9090"
              volumes:
                - ./prometheus.yml:/etc/prometheus/prometheus.yml
            grafana:
              image: grafana/grafana:latest
              ports:
                - "3000:3000"
              environment:
                - GF_SECURITY_ADMIN_PASSWORD=admin123

6.2 Automated Operations Report

- name: Generate deployment report
  hosts: localhost
  gather_facts: no
  tasks:
    - name: Collect deployment statistics
      set_fact:
        deployment_stats:
          total_hosts: "{{ groups['all'] | length }}"
          successful_hosts: "{{ groups['all'] | length - ansible_failed_hosts | default([]) | length }}"
          failed_hosts: "{{ ansible_failed_hosts | default([]) | length }}"
          deployment_time: "{{ ansible_date_time.iso8601 }}"
    - name: Send deployment notification
      uri:
        url: "{{ slack_webhook_url }}"
        method: POST
        body_format: json
        body:
          text: |
            🚀 Deployment Report
            ✅ Success: {{ deployment_stats.successful_hosts }}/{{ deployment_stats.total_hosts }}
            ❌ Failure: {{ deployment_stats.failed_hosts }}
            🕐 Time: {{ deployment_stats.deployment_time }}

Conclusion: Core Value of Ansible Automation

Through this hands‑on tutorial you have mastered Ansible’s architecture, production‑grade playbook patterns, large‑scale deployment strategies, error handling, security hardening, CI/CD integration, and monitoring, enabling you to deliver reliable, repeatable, and efficient infrastructure automation.

Next Learning Path

Deep Dive into Container Orchestration : Combine Kubernetes for cloud‑native deployments.

Monitoring System Construction : Build end‑to‑end observability and alerting.

Secure Operations Practices : Implement zero‑trust networking and automated security scans.

Multi‑Cloud Management : Unified operations across multiple cloud providers.

Useful Resources

Official Documentation : docs.ansible.com

Best Practices : ansible‑best‑practices

Community Modules : galaxy.ansible.com