Managing Configuration

Configuration Management

Purpose

This skill provides guidance for automating server and application configuration using Ansible and related tools. It covers playbook creation, role structure, inventory management (static and dynamic), secret management, testing patterns, and idempotency best practices to ensure safe, repeatable configuration deployments.

When to Use This Skill

Invoke this skill when:

• Creating Ansible playbooks to configure servers or deploy applications
• Structuring reusable Ansible roles with proper directory layout
• Managing inventories (static files or dynamic cloud-based)
• Securing secrets with ansible-vault or HashiCorp Vault integration
• Testing roles with Molecule before production deployment
• Ensuring idempotent playbooks that safely run multiple times
• Migrating from Chef or Puppet to Ansible
• Implementing GitOps workflows for configuration as code
• Debugging playbook failures or handler issues

Quick Start

Basic Playbook Example

---
# site.yml
- name: Configure web servers
  hosts: webservers
  become: yes

  tasks:
    - name: Ensure nginx is installed
      apt:
        name: nginx
        state: present
      notify: Restart nginx

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

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

Run with:

ansible-playbook -i inventory/production site.yml

Core Concepts

1. Idempotency

Run playbooks multiple times without unintended side effects. Use state-based modules (present, started, latest) instead of imperative commands.

Idempotent (good):

- name: Ensure package installed
  apt:
    name: nginx
    state: present

Not idempotent (avoid):

- name: Install package
  command: apt-get install -y nginx

See references/idempotency-guide.md for detailed patterns.

2. Inventory Management

Static Inventory: INI or YAML files for stable environments. Dynamic Inventory: Scripts or plugins for cloud environments (AWS, Azure, GCP).

Example static inventory (INI):

[webservers]
web1.example.com ansible_host=10.0.1.10
web2.example.com ansible_host=10.0.1.11

[webservers:vars]
nginx_worker_processes=4

See references/inventory-management.md for dynamic inventory setup.

3. Roles vs Playbooks

Playbooks: Orchestrate multiple tasks and roles for specific deployments. Roles: Reusable, self-contained configuration units with standardized directory structure.

Standard role structure:

roles/nginx/
├── defaults/     # Default variables
├── tasks/        # Task files
├── handlers/     # Change handlers
├── templates/    # Jinja2 templates
├── files/        # Static files
└── meta/         # Dependencies

See references/role-structure.md for complete role patterns.

4. Secret Management

ansible-vault: Built-in encryption for sensitive data. HashiCorp Vault: Enterprise-grade secrets management with dynamic credentials.

Encrypt secrets:

ansible-vault create group_vars/all/vault.yml
ansible-playbook site.yml --ask-vault-pass

See references/secrets-management.md for Vault integration.

Common Workflows

Workflow 1: Create New Playbook

Step 1: Define inventory

# inventory/production
[webservers]
web1.example.com
web2.example.com

Step 2: Create playbook structure

---
- name: Configure application
  hosts: webservers
  become: yes

  pre_tasks:
    - name: Update package cache
      apt:
        update_cache: yes

  roles:
    - common
    - application

  post_tasks:
    - name: Verify service
      uri:
        url: http://localhost:8080/health
        status_code: 200

Step 3: Test with check mode

ansible-playbook -i inventory/production site.yml --check --diff

Step 4: Execute playbook

ansible-playbook -i inventory/production site.yml

See references/playbook-patterns.md for advanced patterns.

Workflow 2: Create and Test Role

Step 1: Initialize role structure

ansible-galaxy init roles/myapp

Step 2: Define tasks

# roles/myapp/tasks/main.yml
---
- name: Install application dependencies
  apt:
    name: "{{ item }}"
    state: present
  loop: "{{ myapp_dependencies }}"

- name: Deploy application
  template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
  notify: Restart myapp

Step 3: Add handler

# roles/myapp/handlers/main.yml
---
- name: Restart myapp
  service:
    name: myapp
    state: restarted

Step 4: Initialize Molecule testing

cd roles/myapp
molecule init scenario default --driver-name docker

Step 5: Run tests

molecule test

See references/testing-guide.md for comprehensive testing patterns.

Workflow 3: Set Up Dynamic Inventory (AWS)

Step 1: Install AWS collection

ansible-galaxy collection install amazon.aws

Step 2: Configure dynamic inventory

# inventory/aws_ec2.yml
plugin: aws_ec2
regions:
  - us-east-1
filters:
  tag:Environment: production
  instance-state-name: running
keyed_groups:
  - key: tags.Role
    prefix: role
hostnames:
  - tag:Name
compose:
  ansible_host: private_ip_address

Step 3: Verify inventory

ansible-inventory -i inventory/aws_ec2.yml --list

Step 4: Run playbook

ansible-playbook -i inventory/aws_ec2.yml site.yml

See references/inventory-management.md for multi-cloud patterns.

Workflow 4: Secure Secrets with ansible-vault

Step 1: Create encrypted vault file

ansible-vault create group_vars/all/vault.yml

Step 2: Add secrets

# group_vars/all/vault.yml (encrypted)
vault_db_password: "SuperSecretPassword"
vault_api_key: "sk-1234567890"

Step 3: Reference in variables

# group_vars/all/vars.yml (unencrypted)
db_password: "{{ vault_db_password }}"
api_key: "{{ vault_api_key }}"

Step 4: Use in playbook

- name: Configure database
  template:
    src: db.conf.j2
    dest: /etc/app/db.conf
  vars:
    database_password: "{{ db_password }}"

Step 5: Run with vault password

ansible-playbook site.yml --vault-password-file ~/.vault_pass

See references/secrets-management.md for HashiCorp Vault integration.

Tool Selection

When to Use Ansible

• Configuring servers/VMs after provisioning
• Deploying applications to existing infrastructure
• Managing OS-level settings (users, packages, services)
• Orchestrating multi-step workflows across hosts
• Cloud-native environments (agentless SSH/WinRM)
• Teams new to configuration management (easiest learning curve)

When to Use Alternatives

Infrastructure-as-Code (Terraform): Creating cloud infrastructure resources. Kubernetes: Container orchestration and configuration. Chef/Puppet: Existing deployments with high migration costs.

Ansible vs IaC Integration

Best practice: Terraform provisions, Ansible configures.

Workflow: 1. Terraform creates AWS EC2 instances, security groups, load balancers 2. Terraform outputs instance IPs to Ansible inventory 3. Ansible configures OS, installs packages, deploys applications 4. Ansible sets up monitoring, backups, operational tasks

See references/decision-framework.md for detailed decision trees.

Testing and Quality

Pre-Deployment Validation

Step 1: Lint playbooks

ansible-lint playbooks/

Step 2: Check mode (dry run)

ansible-playbook site.yml --check --diff

Step 3: Test roles with Molecule

cd roles/myapp
molecule test

Step 4: Verify idempotence

molecule idempotence

Configuration Files

.ansible-lint:

---
exclude_paths:
  - molecule/
  - venv/
skip_list:
  - name[casing]
warn_list:
  - experimental

molecule.yml:

---
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
    pre_build_image: true
provisioner:
  name: ansible
verifier:
  name: ansible

See references/testing-guide.md for complete testing strategies.

Troubleshooting

Common Issues

Connection failures:

• Verify SSH access: ansible all -i inventory -m ping
• Check SSH keys: ssh -vvv user@host
• Test with password: ansible-playbook site.yml --ask-pass

Handler not firing:

• Handlers only run on change (check task changed status)
• Handlers run at end of playbook (use meta: flush_handlers to force earlier)
• Handler names must match exactly

Variable not defined:

• Check variable precedence (command-line > playbook > inventory > defaults)
• Use debug module: - debug: var=myvar
• Verify variable files are loaded: ansible-playbook site.yml -v

Idempotency violations:

• Run playbook twice, compare output
• Check for changed on every run
• Use state-based modules instead of command/shell

See references/troubleshooting.md for comprehensive debugging guide.

Integration with Other Skills

infrastructure-as-code:

• Terraform provisions infrastructure
• Ansible configures post-provisioning
• Terraform outputs feed Ansible inventory

kubernetes-operations:

• Ansible deploys K8s clusters (kubespray)
• Kubernetes handles container orchestration
• Ansible manages node-level configuration

building-ci-pipelines:

• CI/CD runs ansible-lint for quality checks
• Molecule tests execute in pipeline
• Deployment stage runs playbooks

secret-management:

• ansible-vault for simple use cases
• HashiCorp Vault for enterprise secrets
• Dynamic credentials via Vault lookups

security-hardening:

• Ansible applies CIS benchmarks
• Security roles enforce compliance
• Molecule verifies hardening effectiveness

testing-strategies:

• Molecule for role testing
• Testinfra for verification
• Integration test suites

Reference Documentation

• references/playbook-patterns.md - Playbook structure, handlers, tags, variables
• references/role-structure.md - Role directory layout, best practices, collections
• references/inventory-management.md - Static, dynamic, and hybrid inventory patterns
• references/secrets-management.md - ansible-vault and HashiCorp Vault integration
• references/testing-guide.md - Molecule, ansible-lint, check mode, verification
• references/idempotency-guide.md - Ensuring safe, repeatable executions
• references/decision-framework.md - Tool selection and workflow design
• references/chef-puppet-migration.md - Migrating from legacy tools to Ansible
• references/troubleshooting.md - Common issues and debugging techniques

Example Code

• examples/playbooks/ - Complete playbook examples
• examples/roles/ - Production-ready role templates
• examples/inventory/ - Static and dynamic inventory configurations
• examples/molecule/ - Molecule test scenarios

Utility Scripts

• scripts/validate-playbook.py - Validate playbook syntax and structure
• scripts/generate-inventory.py - Generate inventory from cloud providers
• scripts/ansible-vault-helper.sh - Vault management utilities
• scripts/molecule-runner.sh - Automated Molecule test execution

Chef and Puppet Migration Guide

Table of Contents

1. Chef to Ansible Migration 2. Puppet to Ansible Migration 3. Migration Strategy 4. Migration Tools 5. Common Pitfalls 6. Best Practices 7. Resources

---

Chef to Ansible Migration

Conceptual Mapping

Recipe to Playbook Translation

Chef Recipe (install_nginx.rb):

package 'nginx' do
  action :install
end

template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  owner 'root'
  group 'root'
  mode '0644'
  notifies :reload, 'service[nginx]'
end

service 'nginx' do
  action [:enable, :start]
end

Ansible Playbook:

---
- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present

- name: Configure nginx
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  notify: Reload nginx

- name: Start nginx
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: yes

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

Common Chef Patterns in Ansible

1. Package Installation:

Chef:

package ['nginx', 'postgresql', 'redis'] do
  action :install
end

Ansible:

- name: Install packages
  ansible.builtin.apt:
    name:
      - nginx
      - postgresql
      - redis
    state: present

2. File Management:

Chef:

file '/etc/app/config.yml' do
  content 'key: value'
  owner 'app'
  group 'app'
  mode '0600'
end

Ansible:

- name: Create config file
  ansible.builtin.copy:
    content: 'key: value'
    dest: /etc/app/config.yml
    owner: app
    group: app
    mode: '0600'

3. Conditionals:

Chef:

package 'nginx' do
  action :install
  only_if { node['platform_family'] == 'debian' }
end

Ansible:

- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"

---

Puppet to Ansible Migration

Conceptual Mapping

Manifest to Playbook Translation

Puppet Manifest (nginx.pp):

package { 'nginx':
  ensure => installed,
}

file { '/etc/nginx/nginx.conf':
  ensure  => file,
  owner   => 'root',
  group   => 'root',
  mode    => '0644',
  source  => 'puppet:///modules/nginx/nginx.conf',
  notify  => Service['nginx'],
}

service { 'nginx':
  ensure => running,
  enable => true,
}

Ansible Playbook:

---
- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present

- name: Configure nginx
  ansible.builtin.copy:
    src: nginx.conf
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  notify: Restart nginx

- name: Start nginx
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: yes

handlers:
  - name: Restart nginx
    ansible.builtin.service:
      name: nginx
      state: restarted

Common Puppet Patterns in Ansible

1. Resource Ensure:

Puppet:

package { 'nginx':
  ensure => installed,
}

service { 'nginx':
  ensure => running,
}

Ansible:

- name: Ensure nginx installed
  ansible.builtin.apt:
    name: nginx
    state: present

- name: Ensure nginx running
  ansible.builtin.service:
    name: nginx
    state: started

2. File Resources:

Puppet:

file { '/opt/app':
  ensure => directory,
  owner  => 'app',
  mode   => '0755',
}

Ansible:

- name: Ensure directory exists
  ansible.builtin.file:
    path: /opt/app
    state: directory
    owner: app
    mode: '0755'

3. User Management:

Puppet:

user { 'appuser':
  ensure => present,
  uid    => 1001,
  gid    => 'appgroup',
  home   => '/home/appuser',
  shell  => '/bin/bash',
}

Ansible:

- name: Create user
  ansible.builtin.user:
    name: appuser
    uid: 1001
    group: appgroup
    home: /home/appuser
    shell: /bin/bash
    state: present

---

Migration Strategy

Phase 1: Assessment (Week 1)

Tasks: 1. Inventory existing Chef/Puppet code 2. Identify critical cookbooks/modules 3. Document dependencies 4. Assess complexity 5. Choose pilot project

Deliverables:

• Migration scope document
• Priority list
• Resource requirements

Phase 2: Parallel Implementation (Weeks 2-4)

Tasks: 1. Install Ansible on control node 2. Convert pilot cookbook/module 3. Test in non-production 4. Run Chef/Puppet and Ansible in parallel 5. Validate equivalence

Approach:

• Start with simplest cookbook/module
• Convert 1-2 cookbooks/modules per week
• Maintain existing system during migration

Phase 3: Validation (Week 5)

Tasks: 1. Compare Chef/Puppet output vs Ansible output 2. Run compliance checks 3. Performance testing 4. Security audit 5. Documentation review

Phase 4: Cutover (Week 6)

Tasks: 1. Disable Chef/Puppet 2. Full Ansible deployment 3. Monitor for issues 4. Address any gaps 5. Document new workflows

Phase 5: Cleanup (Week 7)

Tasks: 1. Remove Chef/Puppet infrastructure 2. Archive old code 3. Train team on Ansible 4. Update runbooks 5. Celebrate!

---

Migration Tools

chefspec to Molecule

Convert Chef cookbook tests to Molecule tests.

puppet-lint to ansible-lint

Run ansible-lint for quality checks.

Custom Conversion Scripts

Simple script to help translate:

#!/usr/bin/env python3
"""Simple Chef recipe to Ansible playbook converter."""

import re
import sys

def convert_package(line):
    match = re.search(r"package ['\"]([^'\"]+)['\"]", line)
    if match:
        return f"""
- name: Install {match.group(1)}
  ansible.builtin.apt:
    name: {match.group(1)}
    state: present
"""
    return None

def convert_service(line):
    match = re.search(r"service ['\"]([^'\"]+)['\"]", line)
    if match:
        return f"""
- name: Start {match.group(1)}
  ansible.builtin.service:
    name: {match.group(1)}
    state: started
    enabled: yes
"""
    return None

def main():
    if len(sys.argv) < 2:
        print("Usage: convert.py recipe.rb")
        sys.exit(1)

    print("---")
    with open(sys.argv[1]) as f:
        for line in f:
            result = convert_package(line) or convert_service(line)
            if result:
                print(result)

if __name__ == '__main__':
    main()

---

Common Pitfalls

1. Agent Dependency

Chef/Puppet: Requires agent on managed nodes. Ansible: Agentless (SSH only).

Solution: Ensure SSH access configured before migration.

2. Pull vs Push Model

Chef/Puppet: Nodes pull configuration. Ansible: Control node pushes configuration.

Solution: Use ansible-pull if pull model required.

3. State Files

Chef/Puppet: Maintain state on nodes. Ansible: Stateless by default.

Solution: Use dynamic inventory for state tracking if needed.

4. Custom Resources

Chef/Puppet: Custom resources in Ruby/Puppet DSL. Ansible: Custom modules in Python.

Solution: Rewrite custom resources as Ansible modules or use command/shell temporarily.

---

Best Practices

1. Incremental Migration

Don't try to migrate everything at once. Start with simple, low-risk cookbooks/modules.

2. Maintain Parity

Run both systems in parallel during migration to ensure equivalence.

3. Test Thoroughly

Use Molecule to test converted roles before deploying.

4. Document Changes

Keep detailed notes on translation decisions for future reference.

5. Train Team

Ensure team is comfortable with Ansible before full cutover.

6. Leverage Ansible Galaxy

Check if equivalent roles already exist on Ansible Galaxy before rewriting.

---

Resources

Ansible Documentation:

• https://docs.ansible.com/ansible/latest/porting_guides/

Community Examples:

• https://github.com/geerlingguy/ansible-for-devops
• https://github.com/ansible/ansible-examples

Consulting:

• Red Hat Consulting Services
• Ansible Professional Services

Decision Framework

Table of Contents

1. When to Use Configuration Management 2. Tool Selection: Ansible vs Chef vs Puppet 3. Ansible vs Infrastructure-as-Code 4. Static vs Dynamic Inventory 5. Playbooks vs Roles 6. Secret Management Selection 7. Testing Strategy Selection 8. Environment Strategy 9. Push vs Pull Model 10. When to Consider Alternatives

---

When to Use Configuration Management

Use Configuration Management When:

✅ Managing server/VM configurations (OS settings, packages, users) ✅ Ensuring compliance (CIS benchmarks, PCI-DSS, SOC2) ✅ Deploying applications to servers/VMs ✅ Standardizing environments (dev, staging, production) ✅ Automating operational tasks (backups, updates, monitoring) ✅ Managing cloud resources post-provisioning

Don't Use Configuration Management For:

❌ Creating cloud infrastructure (use Terraform, CloudFormation) ❌ Container orchestration (use Kubernetes, Docker Swarm) ❌ CI/CD pipelines (use Jenkins, GitHub Actions, GitLab CI) ❌ Immutable infrastructure (use Packer for image baking)

---

Tool Selection: Ansible vs Chef vs Puppet

Decision Tree

Start
│
├─ New project / greenfield?
│  └─ YES → Ansible (easiest, modern, agentless)
│
├─ Existing Chef/Puppet?
│  ├─ Working well? → Keep it (don't migrate unnecessarily)
│  └─ Pain points? → Migrate to Ansible (assess effort)
│
├─ Windows-heavy environment?
│  ├─ Mostly Windows → Puppet (best Windows support) OR Ansible (WinRM)
│  └─ Mixed → Ansible (handles both)
│
├─ Compliance-critical enterprise?
│  ├─ Need compliance tools → Puppet (Remediate) OR Ansible (custom)
│  └─ Standard compliance → Ansible (sufficient)
│
├─ Large team, complex organization?
│  ├─ Need enterprise support → Red Hat Ansible Automation Platform
│  └─ Open source sufficient → Ansible (community)
│
└─ Cloud-native / containers?
   └─ YES → Ansible (best cloud integration, agentless)

Quick Comparison

---

Ansible vs Infrastructure-as-Code

Use Ansible When:

• Configuring resources AFTER provisioning
• Deploying applications to existing infrastructure
• Managing OS-level settings (users, packages, services)
• Orchestrating multi-step workflows across hosts
• Operational tasks (backups, updates, maintenance)

Use Terraform/IaC When:

• Creating cloud infrastructure (VPCs, instances, databases)
• Managing resource lifecycle (create, update, destroy)
• Defining infrastructure state declaratively
• Multi-cloud resource orchestration
• Infrastructure dependencies and ordering

Best Practice: Use Both Together

Workflow: 1. Terraform creates AWS EC2 instances, security groups, load balancers 2. Terraform outputs instance IPs to Ansible inventory 3. Ansible configures OS, installs packages, deploys application 4. Ansible sets up monitoring, backups, cron jobs

Example Terraform output:

output "web_servers" {
  value = {
    for instance in aws_instance.web :
    instance.tags.Name => instance.private_ip
  }
}

resource "local_file" "ansible_inventory" {
  content = templatefile("inventory.tpl", {
    web_servers = aws_instance.web
  })
  filename = "../ansible/inventory/terraform.yml"
}

---

Static vs Dynamic Inventory

Decision Matrix

Use Static Inventory When:

• Small environment (< 50 hosts)
• Stable infrastructure (rarely changes)
• On-premises servers with fixed IPs
• Simple host grouping requirements
• No cloud integration needed

Example:

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

[databases]
db1.example.com

Use Dynamic Inventory When:

• Large environment (> 50 hosts)
• Cloud-based infrastructure (AWS, Azure, GCP)
• Frequent scaling (auto-scaling groups)
• Multi-cloud or hybrid environments
• Source of truth in external system (NetBox, CMDB)

Example:

# inventory/aws_ec2.yml
plugin: aws_ec2
regions:
  - us-east-1
filters:
  tag:Environment: production
  instance-state-name: running

Use Hybrid Inventory When:

• Some static hosts (on-premises)
• Some dynamic hosts (cloud)
• Unified management across environments

inventory/
├── static/
│   └── onprem-hosts
└── aws_ec2.yml

---

Playbooks vs Roles

Use Playbooks When:

• One-time deployment tasks
• Environment-specific orchestration
• Combining multiple roles
• Custom workflow for specific application

Example:

# deploy-production.yml
- hosts: webservers
  roles:
    - common
    - nginx
    - myapp

Use Roles When:

• Reusable configuration units
• Shareable across projects
• Testing in isolation
• Publishing to Ansible Galaxy

Example:

roles/nginx/
├── tasks/
├── handlers/
├── templates/
└── defaults/

---

Secret Management Selection

Use ansible-vault When:

• Small teams (< 10 people)
• Simple secret management needs
• No compliance requirements
• Secrets change infrequently
• No need for audit trails
• Budget constraints

Pros:

• Built-in, no additional setup
• Simple to use
• Free
• Integrates seamlessly with Ansible

Cons:

• No dynamic secrets
• No audit logging
• Manual secret rotation
• Password-based access control

Use HashiCorp Vault When:

• Large teams or enterprises
• Dynamic secret generation needed (database credentials)
• Compliance requirements (SOC2, PCI-DSS, HIPAA)
• Frequent secret rotation required
• Detailed audit logging needed
• Integration with multiple tools (not just Ansible)
• Cloud-native architectures

Pros:

• Dynamic secrets (time-limited credentials)
• Comprehensive audit logging
• Fine-grained access control (policies, roles)
• Automated secret rotation
• Multi-tool integration

Cons:

• Additional infrastructure to manage
• More complex setup
• Requires operational expertise
• Cost (enterprise features)

Hybrid Approach

Use both for different security tiers:

# Low-sensitivity: ansible-vault
app_config_param: "{{ vault_app_config }}"

# High-sensitivity: HashiCorp Vault
db_password: "{{ lookup('hashi_vault', 'secret/data/myapp:password') }}"

---

Testing Strategy Selection

Use ansible-lint When:

• Pre-commit checks
• CI/CD quality gates
• Catching common mistakes
• Enforcing best practices

Run: Before every commit

Use Check Mode When:

• Manual verification before deployment
• Dry-run testing in production
• Validating changes without applying

Run: Before production deployments

Use Molecule When:

• Developing reusable roles
• Testing against multiple OS distributions
• Validating idempotence
• Pre-production verification
• Publishing roles to Ansible Galaxy

Run: During role development

Use Testinfra When:

• Infrastructure state verification
• Compliance testing
• Post-deployment validation
• Integration testing

Run: After deployments

---

Environment Strategy

Single Environment Inventory

When:

• Small deployments
• Single environment (prod only)
• Simple infrastructure

inventory/
└── hosts

Multi-Environment Inventory

When:

• Development, staging, production environments
• Different configurations per environment
• Separate teams/access controls

inventory/
├── production/
│   ├── hosts
│   └── group_vars/
├── staging/
│   ├── hosts
│   └── group_vars/
└── development/
    ├── hosts
    └── group_vars/

---

Push vs Pull Model

Push (Default Ansible)

When:

• Small-to-medium environments
• Centralized control preferred
• On-demand deployments
• Cloud-based (SSH always available)

Command:

ansible-playbook site.yml

Pull (ansible-pull)

When:

• Large-scale deployments (1000+ nodes)
• Autonomous node configuration
• Periodic updates (cron-based)
• Nodes behind firewalls

Setup:

# On managed node
ansible-pull -U https://github.com/org/ansible-repo.git site.yml

---

When to Consider Alternatives

Switch to Kubernetes when:

• Running containerized applications
• Need container orchestration
• Require service mesh features
• Horizontal scaling requirements

Use Packer instead when:

• Building immutable images
• Image-based deployments
• Golden image creation
• No post-boot configuration needed

Consider SaltStack when:

• Real-time remote execution needed
• Event-driven automation
• Already using Salt infrastructure

Stick with manual when:

• One-time setup (< 5 servers)
• Exploratory/learning phase
• No repeatability requirements
• Cost of automation > cost of manual work

Idempotency Guide

Table of Contents

1. What is Idempotency? 2. Patterns for Idempotency 3. Common Idempotency Issues 4. Testing Idempotency 5. Module Reference 6. Best Practices 7. Debugging Idempotency Issues

---

What is Idempotency?

Idempotency means running a playbook multiple times produces the same result as running it once. Tasks should converge to a desired state without side effects on repeated execution.

Benefits:

• Safe to re-run - No unintended changes
• Predictable - Same input = same output
• Efficient - Only applies necessary changes
• Production-ready - Can safely run on live systems

---

Patterns for Idempotency

1. Use State-Based Modules

Good (idempotent):

- name: Ensure nginx is installed
  ansible.builtin.apt:
    name: nginx
    state: present

Bad (not idempotent):

- name: Install nginx
  ansible.builtin.command: apt-get install -y nginx

2. Check Before Action

- name: Check if config exists
  ansible.builtin.stat:
    path: /etc/app/app.conf
  register: config_file

- name: Create config only if missing
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/app/app.conf
  when: not config_file.stat.exists

3. Use Handlers for Side Effects

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

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

4. Set changed_when Appropriately

# Command that doesn't change system
- name: Check nginx config syntax
  ansible.builtin.command: nginx -t
  changed_when: false

# Command with conditional change detection
- name: Update cache
  ansible.builtin.command: apt-get update
  register: apt_update
  changed_when: "'Reading package lists' in apt_update.stdout"

5. Use Desired State Parameters

# Service management
- name: Ensure nginx is running
  ansible.builtin.service:
    name: nginx
    state: started      # started, stopped, restarted, reloaded
    enabled: yes        # Boot persistence

# Package management
- name: Ensure package version
  ansible.builtin.apt:
    name: nginx=1.24.0-1
    state: present      # present, absent, latest

# File management
- name: Ensure file exists
  ansible.builtin.copy:
    src: file.txt
    dest: /tmp/file.txt
    force: no           # Don't overwrite if exists

---

Common Idempotency Issues

Issue 1: Command/Shell Modules

Problem:

# Always reports "changed"
- name: Create directory
  ansible.builtin.command: mkdir /opt/app

Solution 1: Use appropriate module

- name: Ensure directory exists
  ansible.builtin.file:
    path: /opt/app
    state: directory

Solution 2: Add changed_when

- name: Create directory
  ansible.builtin.command: mkdir /opt/app
  args:
    creates: /opt/app  # Only run if /opt/app doesn't exist

Issue 2: Database Operations

Problem:

# Fails on second run
- name: Create database
  ansible.builtin.command: createdb myapp

Solution:

- name: Ensure database exists
  community.postgresql.postgresql_db:
    name: myapp
    state: present

Issue 3: User/Group Creation

Problem:

# Not idempotent
- name: Add user
  ansible.builtin.command: useradd appuser

Solution:

- name: Ensure user exists
  ansible.builtin.user:
    name: appuser
    system: yes
    state: present

Issue 4: Package Downloads

Problem:

# Downloads every time
- name: Download application
  ansible.builtin.get_url:
    url: https://example.com/app.tar.gz
    dest: /tmp/app.tar.gz

Solution:

- name: Download application (cached)
  ansible.builtin.get_url:
    url: https://example.com/app.tar.gz
    dest: /tmp/app.tar.gz
    checksum: sha256:abc123...  # Only downloads if checksum differs

Issue 5: Configuration Appends

Problem:

# Appends every run
- name: Add config line
  ansible.builtin.lineinfile:
    path: /etc/hosts
    line: "10.0.0.1 server1"
    state: present
    # Missing unique identifier

Solution:

- name: Ensure host entry exists
  ansible.builtin.lineinfile:
    path: /etc/hosts
    regexp: '^.* server1$'  # Unique match pattern
    line: "10.0.0.1 server1"
    state: present

---

Testing Idempotency

Manual Test

# Run playbook twice
ansible-playbook site.yml
ansible-playbook site.yml

# Second run should report:
# ok=N changed=0 unreachable=0 failed=0

Molecule Idempotence Test

# Automatic idempotence check
molecule idempotence

Passes if: Second run has zero changes. Fails if: Second run reports any changed tasks.

Idempotence Verification Task

- name: Verify idempotence
  block:
    - name: Run role first time
      ansible.builtin.include_role:
        name: myapp

    - name: Run role second time
      ansible.builtin.include_role:
        name: myapp
      register: second_run

    - name: Assert no changes on second run
      ansible.builtin.assert:
        that:
          - not second_run.changed
        fail_msg: "Role is not idempotent"

---

Module Reference

Idempotent Modules (Safe to Use)

Non-Idempotent Modules (Use Carefully)

---

Best Practices

1. Always Use State Parameters

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

# Bad
- name: Start service
  ansible.builtin.command: systemctl start nginx

2. Add changed_when to Commands

# Read-only commands
- name: Check version
  ansible.builtin.command: app --version
  changed_when: false
  register: version

# Conditional changes
- name: Run migration
  ansible.builtin.command: /opt/app/migrate.sh
  register: migration
  changed_when: "'Applied' in migration.stdout"

3. Use creates/removes Arguments

# Only run if file doesn't exist
- name: Extract archive
  ansible.builtin.command: tar -xzf /tmp/app.tar.gz
  args:
    chdir: /opt/app
    creates: /opt/app/bin/app

# Only run if file exists
- name: Clean up
  ansible.builtin.command: rm -rf /tmp/build
  args:
    removes: /tmp/build

4. Check State Before Changing

- name: Check if service exists
  ansible.builtin.stat:
    path: /etc/systemd/system/myapp.service
  register: service_file

- name: Install service
  ansible.builtin.template:
    src: myapp.service.j2
    dest: /etc/systemd/system/myapp.service
  when: not service_file.stat.exists or force_reinstall | default(false)
  notify: Reload systemd

5. Use Handlers for Restarts

# Don't restart directly
tasks:
  - name: Update config
    ansible.builtin.template:
      src: app.conf.j2
      dest: /etc/app/app.conf
    notify: Restart app

# Use handler (only restarts if config changed)
handlers:
  - name: Restart app
    ansible.builtin.service:
      name: myapp
      state: restarted

6. Avoid Destructive Operations

# Bad: Destroys data every run
- name: Reset database
  ansible.builtin.command: dropdb myapp && createdb myapp

# Good: Only create if missing
- name: Ensure database exists
  community.postgresql.postgresql_db:
    name: myapp
    state: present

7. Use force Parameter Carefully

# Bad: Always overwrites
- name: Deploy config
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app/app.conf
    force: yes  # Always copies

# Good: Only copies if different
- name: Deploy config
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app/app.conf
    force: no   # Preserves existing if present
    # Or omit force (default behavior checks content)

8. Document Non-Idempotent Tasks

- name: Run database migration (NOT IDEMPOTENT)
  ansible.builtin.command: /opt/app/migrate.sh
  # NOTE: This will apply all pending migrations each run
  # Future enhancement: track applied migrations

9. Test Repeatedly

# Run playbook 3 times
for i in 1 2 3; do
  echo "Run $i"
  ansible-playbook site.yml
done

# All runs after first should show: changed=0

10. Use Molecule for Automated Testing

# molecule.yml includes idempotence test
scenario:
  test_sequence:
    - converge      # First run
    - idempotence   # Second run (verifies no changes)
    - verify        # Verification

---

Debugging Idempotency Issues

Find Non-Idempotent Tasks

# Run twice, compare output
ansible-playbook site.yml -v > run1.log
ansible-playbook site.yml -v > run2.log
diff run1.log run2.log

Check Task Results

- name: Run task
  ansible.builtin.command: some-command
  register: result

- name: Show result
  ansible.builtin.debug:
    var: result
  # Check: result.changed, result.rc, result.stdout

Use Check Mode

# Dry run shows what would change
ansible-playbook site.yml --check --diff

Enable Verbose Output

# Show detailed task execution
ansible-playbook site.yml -vvv

Inventory Management

Table of Contents

1. Static Inventory 2. Dynamic Inventory 3. Hybrid Inventory 4. Inventory Variables 5. Best Practices

---

Static Inventory

INI Format

Basic inventory:

# inventory/production

[webservers]
web1.example.com
web2.example.com
web3.example.com

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

[loadbalancers]
lb1.example.com

With host variables:

[webservers]
web1.example.com ansible_host=10.0.1.10 nginx_worker_processes=4
web2.example.com ansible_host=10.0.1.11 nginx_worker_processes=8
web3.example.com ansible_host=10.0.1.12 nginx_worker_processes=4

With group variables:

[webservers]
web1.example.com
web2.example.com
web3.example.com

[webservers:vars]
nginx_worker_processes=4
app_env=production
ansible_user=deploy

Parent groups:

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

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

[production:children]
webservers
databases

[production:vars]
ansible_user=deploy
ansible_become=yes

YAML Format

# inventory/production.yml
all:
  children:
    production:
      children:
        webservers:
          hosts:
            web1.example.com:
              ansible_host: 10.0.1.10
              nginx_worker_processes: 4
            web2.example.com:
              ansible_host: 10.0.1.11
              nginx_worker_processes: 8
          vars:
            app_env: production

        databases:
          hosts:
            db1.example.com:
              ansible_host: 10.0.2.10
            db2.example.com:
              ansible_host: 10.0.2.11
          vars:
            postgres_version: 15

      vars:
        ansible_user: deploy
        ansible_become: yes

Multiple Inventory Files

inventory/
├── production/
│   ├── hosts            # Main inventory
│   ├── webservers       # Web tier hosts
│   └── databases        # Database tier hosts
└── staging/
    ├── hosts
    ├── webservers
    └── databases

Run with directory:

ansible-playbook -i inventory/production site.yml

---

Dynamic Inventory

AWS EC2 Plugin

Installation:

ansible-galaxy collection install amazon.aws

inventory/aws_ec2.yml:

plugin: aws_ec2

regions:
  - us-east-1
  - us-west-2

filters:
  tag:Environment: production
  instance-state-name: running

keyed_groups:
  # Group by tag
  - key: tags.Role
    prefix: role
    separator: "_"
  # Group by instance type
  - key: instance_type
    prefix: type
  # Group by availability zone
  - key: placement.availability_zone
    prefix: az

hostnames:
  - tag:Name
  - private-ip-address

compose:
  ansible_host: private_ip_address
  ansible_user: "'ubuntu'"

Test inventory:

# List all hosts
ansible-inventory -i inventory/aws_ec2.yml --list

# Graph view
ansible-inventory -i inventory/aws_ec2.yml --graph

# Run playbook
ansible-playbook -i inventory/aws_ec2.yml site.yml

Azure Resource Manager Plugin

Installation:

ansible-galaxy collection install azure.azcollection

inventory/azure_rm.yml:

plugin: azure_rm

auth_source: auto

include_vm_resource_groups:
  - production-rg

keyed_groups:
  - prefix: tag
    key: tags
  - prefix: location
    key: location

hostnames:
  - name
  - default

compose:
  ansible_host: public_ipv4_addresses[0]
  ansible_user: "'azureuser'"

GCP Compute Plugin

Installation:

ansible-galaxy collection install google.cloud

inventory/gcp_compute.yml:

plugin: gcp_compute

projects:
  - my-project-id

zones:
  - us-central1-a
  - us-central1-b

filters:
  - labels.environment = production
  - status = RUNNING

keyed_groups:
  - key: labels.role
    prefix: role
  - key: zone
    prefix: zone

hostnames:
  - name

compose:
  ansible_host: networkInterfaces[0].accessConfigs[0].natIP
  ansible_user: "'ubuntu'"

Custom Dynamic Inventory Script

inventory/custom.py:

#!/usr/bin/env python3
import json
import sys

def get_inventory():
    """Return inventory data structure."""
    inventory = {
        "webservers": {
            "hosts": ["web1.example.com", "web2.example.com"],
            "vars": {
                "nginx_worker_processes": 4,
                "app_env": "production"
            }
        },
        "databases": {
            "hosts": ["db1.example.com", "db2.example.com"],
            "vars": {
                "postgres_version": 15
            }
        },
        "_meta": {
            "hostvars": {
                "web1.example.com": {
                    "ansible_host": "10.0.1.10"
                },
                "web2.example.com": {
                    "ansible_host": "10.0.1.11"
                }
            }
        }
    }
    return inventory

def main():
    if len(sys.argv) == 2 and sys.argv[1] == '--list':
        print(json.dumps(get_inventory(), indent=2))
    elif len(sys.argv) == 3 and sys.argv[1] == '--host':
        # Return empty dict for host-specific vars (use _meta above)
        print(json.dumps({}))
    else:
        print("Usage: {} --list | --host <hostname>".format(sys.argv[0]))
        sys.exit(1)

if __name__ == '__main__':
    main()

Make executable:

chmod +x inventory/custom.py

Use script:

ansible-playbook -i inventory/custom.py site.yml

---

Hybrid Inventory

Combine static and dynamic inventories.

inventory/
├── static/
│   └── hosts              # Static on-prem servers
├── aws_ec2.yml            # Dynamic AWS instances
└── azure_rm.yml           # Dynamic Azure instances

Run with multiple inventories:

ansible-playbook -i inventory/ site.yml

All inventory sources merged automatically.

---

Inventory Variables

Group Variables

group_vars/
├── all/
│   ├── common.yml         # Variables for ALL hosts
│   └── vault.yml          # Encrypted secrets for ALL
├── webservers/
│   ├── nginx.yml          # Webserver-specific vars
│   └── vault.yml          # Webserver secrets
└── databases/
    ├── postgres.yml       # Database-specific vars
    └── vault.yml          # Database secrets

group_vars/all/common.yml:

---
# Common variables for all hosts
ntp_servers:
  - 0.pool.ntp.org
  - 1.pool.ntp.org

dns_servers:
  - 8.8.8.8
  - 8.8.4.4

ansible_user: deploy
ansible_become: yes

group_vars/webservers/nginx.yml:

---
# Webserver-specific variables
nginx_worker_processes: "{{ ansible_processor_vcpus }}"
nginx_worker_connections: 1024
nginx_client_max_body_size: "10m"

Host Variables

host_vars/
├── web1.example.com/
│   └── custom.yml         # Host-specific overrides
└── db1.example.com/
    └── custom.yml

host_vars/web1.example.com/custom.yml:

---
# Host-specific overrides
nginx_worker_processes: 8
custom_config_option: "special_value"

Variable Precedence

From lowest to highest: 1. Role defaults 2. Inventory file vars 3. Inventory group_vars/all 4. Inventory group_vars/* 5. Inventory host_vars/* 6. Playbook vars 7. Command-line extra vars (-e)

---

Best Practices

1. Organize by Environment

inventory/
├── production/
│   ├── hosts
│   ├── group_vars/
│   └── host_vars/
└── staging/
    ├── hosts
    ├── group_vars/
    └── host_vars/

2. Use Consistent Naming

# Good: Clear patterns
[webservers]
web-prod-01.example.com
web-prod-02.example.com

[databases]
db-prod-01.example.com
db-prod-02.example.com

# Bad: Inconsistent
[webservers]
server1
production-web-2

3. Group by Function

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

[appservers]
app1.example.com
app2.example.com

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

# Parent groups
[frontend:children]
webservers
appservers

[backend:children]
databases

4. Version Control Inventory

.gitignore:
*vault.yml           # Encrypted secrets
*.pem                # SSH keys
inventory/production # Production inventory (separate repo)

5. Document Inventory Structure

# Inventory Structure

## Environments
- production/ - Production servers
- staging/ - Staging servers
- development/ - Development servers

## Groups
- webservers - NGINX web tier
- appservers - Application tier
- databases - PostgreSQL databases
- loadbalancers - HAProxy load balancers

## Variables
- group_vars/all/ - Global variables
- group_vars/{group}/ - Group-specific variables
- host_vars/{host}/ - Host-specific overrides

6. Limit Playbook Scope

# Run on specific group
ansible-playbook -i inventory site.yml --limit webservers

# Run on specific host
ansible-playbook -i inventory site.yml --limit web1.example.com

# Run on multiple hosts
ansible-playbook -i inventory site.yml --limit "web1,web2,db1"

# Exclude hosts
ansible-playbook -i inventory site.yml --limit "all:!databases"

7. Test Inventory

# List all hosts
ansible-inventory -i inventory --list

# Show graph
ansible-inventory -i inventory --graph

# Show host variables
ansible-inventory -i inventory --host web1.example.com

# Ping all hosts
ansible all -i inventory -m ping

8. Use Dynamic Inventory for Cloud

Static inventory becomes stale quickly in cloud environments. Use dynamic inventory plugins.

Bad (manual updates):

[webservers]
web1.example.com ansible_host=10.0.1.10  # IP changes frequently
web2.example.com ansible_host=10.0.1.11

Good (auto-discovery):

# inventory/aws_ec2.yml
plugin: aws_ec2
filters:
  tag:Role: webserver
  instance-state-name: running

9. Separate Secrets

Don't put secrets in inventory files.

Bad:

[databases:vars]
db_password=SuperSecret123

Good:

# group_vars/databases/vault.yml (encrypted)
vault_db_password: SuperSecret123

# group_vars/databases/vars.yml (unencrypted)
db_password: "{{ vault_db_password }}"

10. Use Inventory Plugins

Prefer inventory plugins over custom scripts.

Supported plugins:

• aws_ec2 - AWS EC2
• azure_rm - Azure Resource Manager
• gcp_compute - Google Cloud Platform
• openstack - OpenStack
• vmware_vm_inventory - VMware
• docker_containers - Docker
• kubernetes - Kubernetes pods

List available plugins:

ansible-doc -t inventory -l

Ansible Playbook Patterns

Table of Contents

1. Playbook Structure 2. Task Organization 3. Handlers 4. Variables 5. Templates 6. Tags 7. Conditional Execution 8. Loops 9. Error Handling 10. Best Practices

---

Playbook Structure

Complete Playbook Anatomy

---
# site.yml - Main playbook
- name: Configure web servers
  hosts: webservers
  become: yes
  gather_facts: yes

  vars:
    nginx_version: "1.24"
    app_port: 8080

  vars_files:
    - vars/common.yml
    - vars/webservers.yml

  pre_tasks:
    - name: Update package cache
      apt:
        update_cache: yes
        cache_valid_time: 3600
      when: ansible_os_family == "Debian"

  roles:
    - common
    - nginx
    - application

  tasks:
    - name: Ensure application is running
      service:
        name: myapp
        state: started
        enabled: yes
      tags: [service, application]

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

  post_tasks:
    - name: Verify application responds
      uri:
        url: "http://localhost:{{ app_port }}/health"
        status_code: 200
      retries: 3
      delay: 5

Execution Order

1. gather_facts - Collect system information 2. pre_tasks - Preparation tasks (package cache updates, prerequisite checks) 3. roles - Execute role tasks in order 4. tasks - Playbook-specific tasks 5. post_tasks - Verification and cleanup 6. handlers - Triggered handlers (if notified)

---

Task Organization

Simple Task

- name: Install nginx
  apt:
    name: nginx
    state: present

Task with Multiple Parameters

- name: Configure nginx
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
    backup: yes
  notify: Reload nginx

Include External Task Files

# tasks/main.yml
- name: Include installation tasks
  include_tasks: install.yml

- name: Include configuration tasks
  include_tasks: configure.yml
  when: configure_app | default(true)

Import Task Files (Static)

# Evaluated at playbook parse time
- name: Import common tasks
  import_tasks: common.yml

Block Tasks for Grouping

- name: Configure application
  block:
    - name: Install dependencies
      apt:
        name: "{{ item }}"
        state: present
      loop: "{{ app_dependencies }}"

    - name: Deploy application
      copy:
        src: app.tar.gz
        dest: /opt/app/

  rescue:
    - name: Rollback deployment
      file:
        path: /opt/app
        state: absent

  always:
    - name: Log deployment attempt
      lineinfile:
        path: /var/log/deployments.log
        line: "Deployment attempted at {{ ansible_date_time.iso8601 }}"

---

Handlers

Basic Handler

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

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

Multiple Handlers

- name: Update application config
  template:
    src: app.conf.j2
    dest: /etc/app/app.conf
  notify:
    - Validate config
    - Restart application
    - Clear cache

handlers:
  - name: Validate config
    command: app validate-config /etc/app/app.conf
    changed_when: false

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

  - name: Clear cache
    command: app clear-cache

Listen Handlers (Multiple Triggers)

# tasks
- name: Update web config
  template:
    src: web.conf.j2
    dest: /etc/web/web.conf
  notify: Reload web services

- name: Update API config
  template:
    src: api.conf.j2
    dest: /etc/api/api.conf
  notify: Reload web services

# handlers
handlers:
  - name: Reload nginx
    service:
      name: nginx
      state: reloaded
    listen: Reload web services

  - name: Reload haproxy
    service:
      name: haproxy
      state: reloaded
    listen: Reload web services

Force Handler Execution

- name: Update critical config
  template:
    src: critical.conf.j2
    dest: /etc/app/critical.conf
  notify: Restart app

- name: Flush handlers now
  meta: flush_handlers

- name: Verify app started
  uri:
    url: http://localhost:8080/health
    status_code: 200

---

Variables

Variable Definition Locations

Playbook vars:

- name: Configure app
  hosts: all
  vars:
    app_version: "2.1.0"
    app_port: 8080

Vars files:

- name: Configure app
  hosts: all
  vars_files:
    - vars/common.yml
    - vars/{{ env }}.yml

Inventory variables:

# inventory/production
[webservers]
web1.example.com app_port=8080
web2.example.com app_port=8081

[webservers:vars]
app_version=2.1.0

Group/Host vars:

group_vars/
├── all/
│   └── common.yml
├── webservers/
│   └── nginx.yml
host_vars/
└── web1.example.com/
    └── custom.yml

Variable Precedence (Lowest to Highest)

1. Role defaults 2. Inventory file vars 3. Inventory group_vars/all 4. Inventory group_vars/ 5. Inventory host_vars/ 6. Playbook vars 7. Playbook vars_files 8. Role vars 9. Block vars 10. Task vars 11. Command-line extra vars (-e)

Register Variables

- name: Check if config exists
  stat:
    path: /etc/app/app.conf
  register: config_file

- name: Create config if missing
  template:
    src: app.conf.j2
    dest: /etc/app/app.conf
  when: not config_file.stat.exists

Set Facts

- name: Set deployment timestamp
  set_fact:
    deployment_time: "{{ ansible_date_time.iso8601 }}"

- name: Use fact in later task
  lineinfile:
    path: /etc/app/version.txt
    line: "Deployed: {{ deployment_time }}"

---

Templates

Basic Jinja2 Template

{# templates/app.conf.j2 #}
# Application Configuration
app_version: {{ app_version }}
app_port: {{ app_port }}
log_level: {{ log_level | default('info') }}

{% if enable_debug %}
debug: true
{% endif %}

Using Template

- name: Deploy application config
  template:
    src: app.conf.j2
    dest: /etc/app/app.conf
    owner: app
    group: app
    mode: '0640'
  notify: Restart app

Advanced Template (Loops)

{# templates/nginx.conf.j2 #}
http {
    {% for site in nginx_sites %}
    server {
        listen {{ site.port | default(80) }};
        server_name {{ site.server_name }};
        root {{ site.root }};

        {% if site.ssl | default(false) %}
        ssl_certificate {{ site.ssl_cert }};
        ssl_certificate_key {{ site.ssl_key }};
        {% endif %}

        location / {
            try_files $uri $uri/ =404;
        }
    }
    {% endfor %}
}

Template with Filters

{# Common Jinja2 filters #}
{{ app_name | upper }}
{{ app_version | lower }}
{{ app_port | int }}
{{ config_value | default('fallback') }}
{{ sensitive_data | b64encode }}
{{ json_data | from_json }}
{{ list_data | join(',') }}

---

Tags

Define Tags

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

- name: Configure services
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  tags: [config, nginx]

- name: Start services
  service:
    name: nginx
    state: started
  tags: [service, nginx]

Run Specific Tags

# Run only install tasks
ansible-playbook site.yml --tags install

# Run multiple tags
ansible-playbook site.yml --tags "install,config"

# Skip tags
ansible-playbook site.yml --skip-tags service

Special Tags

# Always runs (unless explicitly skipped)
- name: Log execution
  debug:
    msg: "Playbook started"
  tags: [always]

# Never runs (unless explicitly included)
- name: Debug task
  debug:
    var: ansible_facts
  tags: [never, debug]

---

Conditional Execution

When Condition

# OS family check
- name: Install package on Debian
  apt:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"

# Multiple conditions (AND)
- name: Install on Ubuntu 22.04
  apt:
    name: nginx
    state: present
  when:
    - ansible_distribution == "Ubuntu"
    - ansible_distribution_version == "22.04"

# OR conditions
- name: Install on RedHat or CentOS
  yum:
    name: nginx
    state: present
  when: ansible_distribution in ["RedHat", "CentOS"]

# Variable defined check
- name: Configure SSL
  template:
    src: ssl.conf.j2
    dest: /etc/nginx/ssl.conf
  when: ssl_enabled is defined and ssl_enabled

Register and Condition

- name: Check service status
  command: systemctl is-active nginx
  register: nginx_status
  failed_when: false
  changed_when: false

- name: Start nginx if not running
  service:
    name: nginx
    state: started
  when: nginx_status.rc != 0

Failed When

- name: Run application tests
  command: npm test
  register: test_result
  failed_when:
    - test_result.rc != 0
    - "'error' in test_result.stderr"

Changed When

- name: Check config syntax
  command: nginx -t
  register: config_check
  changed_when: false  # Never report as changed

- name: Deploy script
  copy:
    src: deploy.sh
    dest: /usr/local/bin/deploy.sh
  register: script_deployed
  changed_when: script_deployed.checksum != previous_checksum

---

Loops

Simple Loop

- name: Install multiple packages
  apt:
    name: "{{ item }}"
    state: present
  loop:
    - nginx
    - postgresql
    - redis

Loop with Dictionary

- name: Create users
  user:
    name: "{{ item.name }}"
    uid: "{{ item.uid }}"
    groups: "{{ item.groups }}"
  loop:
    - { name: 'alice', uid: 1001, groups: 'admin,developers' }
    - { name: 'bob', uid: 1002, groups: 'developers' }
    - { name: 'charlie', uid: 1003, groups: 'operators' }

Loop from Variable

vars:
  packages:
    - name: nginx
      state: present
    - name: postgresql
      state: present

tasks:
  - name: Manage packages
    apt:
      name: "{{ item.name }}"
      state: "{{ item.state }}"
    loop: "{{ packages }}"

Loop with Index

- name: Create numbered directories
  file:
    path: "/data/shard{{ item.0 }}"
    state: directory
  loop: "{{ range(1, 6) | list }}"

Nested Loops

- name: Configure firewall rules
  ufw:
    rule: allow
    port: "{{ item.1 }}"
    from_ip: "{{ item.0 }}"
  loop: "{{ trusted_ips | product(allowed_ports) | list }}"
  vars:
    trusted_ips: ['10.0.1.0/24', '10.0.2.0/24']
    allowed_ports: [80, 443]

Loop Until

- name: Wait for service to be ready
  uri:
    url: http://localhost:8080/health
    status_code: 200
  register: health_check
  until: health_check.status == 200
  retries: 10
  delay: 5

---

Error Handling

Ignore Errors

- name: Attempt to stop service
  service:
    name: oldapp
    state: stopped
  ignore_errors: yes

Block Rescue Always

- name: Deploy application
  block:
    - name: Stop application
      service:
        name: myapp
        state: stopped

    - name: Deploy new version
      copy:
        src: app-v2.0.tar.gz
        dest: /opt/app/

    - name: Start application
      service:
        name: myapp
        state: started

  rescue:
    - name: Rollback to previous version
      copy:
        src: app-v1.9-backup.tar.gz
        dest: /opt/app/

    - name: Start previous version
      service:
        name: myapp
        state: started

    - name: Send alert
      mail:
        to: ops@example.com
        subject: "Deployment failed"

  always:
    - name: Clear deployment lock
      file:
        path: /var/lock/deployment.lock
        state: absent

Any Errors Fatal

- name: Critical deployment
  hosts: all
  any_errors_fatal: yes

  tasks:
    - name: Update database schema
      command: /opt/app/migrate.sh

---

Best Practices

1. Use Pre-Tasks for Preparation

pre_tasks:
  - name: Update package cache
    apt:
      update_cache: yes
      cache_valid_time: 3600

  - name: Ensure prerequisites installed
    apt:
      name:
        - python3
        - python3-pip
      state: present

2. Use Post-Tasks for Verification

post_tasks:
  - name: Verify web service responds
    uri:
      url: http://localhost:80
      status_code: 200
    retries: 5
    delay: 3

  - name: Check log for errors
    command: grep -i error /var/log/app/app.log
    register: log_check
    failed_when:
      - log_check.rc == 0
      - "'CRITICAL' in log_check.stdout"

3. Separate Concerns with Roles

# Don't put everything in one playbook
# Instead, organize by responsibility:
roles:
  - common          # OS configuration
  - security        # Firewall, users
  - monitoring      # Metrics, logging
  - application     # App-specific config

4. Use Check Mode for Safety

# Always test with --check first
ansible-playbook site.yml --check --diff

# Some tasks need check mode disabled
- name: Validate config
  command: nginx -t
  check_mode: no

5. Document with Clear Names

# Good: Clear, descriptive names
- name: Install nginx web server
- name: Configure nginx virtual hosts
- name: Ensure nginx service is running

# Bad: Vague names
- name: Install package
- name: Configure stuff
- name: Run command

6. Keep Playbooks Focused

# Good: Single responsibility
# webservers.yml - Configure web tier
# databases.yml - Configure database tier
# monitoring.yml - Configure monitoring

# Bad: One massive playbook
# everything.yml - Does everything

7. Use Variable Validation

- name: Validate required variables
  assert:
    that:
      - app_version is defined
      - app_port is defined
      - app_port | int > 1024
    fail_msg: "Required variables not properly defined"

8. Leverage Ansible Facts

- name: Configure based on system facts
  template:
    src: app.conf.j2
    dest: /etc/app/app.conf
  vars:
    memory_limit: "{{ (ansible_memtotal_mb * 0.8) | int }}"
    cpu_workers: "{{ ansible_processor_vcpus }}"

9. Use Handlers for Restarts

# Don't restart services directly in tasks
# Use handlers triggered by changes

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

handlers:
  - name: Restart app
    service:
      name: myapp
      state: restarted

10. Test Idempotency

# Run playbook twice
ansible-playbook site.yml
ansible-playbook site.yml

# Second run should have zero changes
# If tasks show "changed" on second run, fix idempotency

Ansible Role Structure

Table of Contents

1. Role Directory Layout 2. Creating Roles 3. Role Components 4. Best Practices 5. Role Dependencies 6. Collections 7. Testing Roles

---

Role Directory Layout

Standard Role Structure

roles/myapp/
├── defaults/
│   └── main.yml          # Default variables (lowest precedence)
├── vars/
│   └── main.yml          # Override variables (higher precedence)
├── tasks/
│   ├── main.yml          # Main task entry point
│   ├── install.yml       # Installation tasks
│   ├── configure.yml     # Configuration tasks
│   └── security.yml      # Security hardening
├── handlers/
│   └── main.yml          # Change handlers
├── templates/
│   ├── app.conf.j2       # Jinja2 templates
│   └── systemd.service.j2
├── files/
│   ├── app.tar.gz        # Static files
│   └── ssl/
│       └── ca.crt
├── meta/
│   └── main.yml          # Role metadata and dependencies
├── library/
│   └── custom_module.py  # Custom modules (optional)
├── module_utils/
│   └── helpers.py        # Shared module utilities (optional)
├── tests/
│   ├── test.yml          # Test playbook
│   └── inventory         # Test inventory
└── README.md             # Role documentation

File Loading Order

1. meta/main.yml - Dependencies loaded first 2. defaults/main.yml - Default variables 3. vars/main.yml - Role variables 4. tasks/main.yml - Task execution begins 5. handlers/main.yml - Handlers registered 6. Templates and files loaded on demand

---

Creating Roles

Initialize Role with ansible-galaxy

# Create new role
ansible-galaxy init roles/myapp

# Create role with specific author
ansible-galaxy init roles/myapp --init-path roles/

# View role structure
tree roles/myapp

Minimal Role Example

roles/nginx/
├── defaults/
│   └── main.yml
├── tasks/
│   └── main.yml
├── handlers/
│   └── main.yml
└── templates/
    └── nginx.conf.j2

defaults/main.yml:

---
# Default variables
nginx_version: "1.24"
nginx_user: www-data
nginx_worker_processes: auto
nginx_worker_connections: 1024
nginx_enable_ssl: false

tasks/main.yml:

---
- name: Install nginx
  apt:
    name: nginx
    state: present
  notify: Restart nginx

- name: Configure nginx
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: Reload nginx

- name: Ensure nginx is running
  service:
    name: nginx
    state: started
    enabled: yes

handlers/main.yml:

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

- name: Reload nginx
  service:
    name: nginx
    state: reloaded

Using Roles in Playbooks

Method 1: Roles section (recommended)

---
- name: Configure web servers
  hosts: webservers
  become: yes

  roles:
    - common
    - nginx
    - application

Method 2: Include role task

---
- name: Configure web servers
  hosts: webservers
  become: yes

  tasks:
    - name: Apply nginx role
      include_role:
        name: nginx

Method 3: Import role (static)

---
- name: Configure web servers
  hosts: webservers
  become: yes

  tasks:
    - name: Import nginx role
      import_role:
        name: nginx

With variables:

---
- name: Configure web servers
  hosts: webservers
  become: yes

  roles:
    - role: nginx
      vars:
        nginx_worker_processes: 4
        nginx_enable_ssl: true

---

Role Components

defaults/main.yml

Define default variable values (can be overridden).

---
# Application settings
app_name: myapp
app_version: "1.0.0"
app_port: 8080
app_user: appuser
app_group: appuser

# Installation settings
app_install_dir: /opt/{{ app_name }}
app_config_dir: /etc/{{ app_name }}
app_log_dir: /var/log/{{ app_name }}

# Feature flags
enable_monitoring: true
enable_backup: false

# Dependencies
app_dependencies:
  - python3
  - python3-pip
  - libpq-dev

vars/main.yml

Define role variables (higher precedence than defaults).

---
# OS-specific package names
_app_packages:
  Debian:
    - nginx
    - postgresql-client
  RedHat:
    - nginx
    - postgresql

app_packages: "{{ _app_packages[ansible_os_family] }}"

# Computed values
app_memory_limit: "{{ (ansible_memtotal_mb * 0.7) | int }}m"
app_workers: "{{ ansible_processor_vcpus }}"

tasks/main.yml

Main task file - orchestrate task execution.

Pattern 1: Single file (simple roles)

---
- name: Install application
  apt:
    name: myapp
    state: present

- name: Configure application
  template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
  notify: Restart myapp

- name: Start application
  service:
    name: myapp
    state: started
    enabled: yes

Pattern 2: Include subtasks (complex roles)

---
- name: Include OS-specific variables
  include_vars: "{{ ansible_os_family }}.yml"

- name: Include pre-flight checks
  include_tasks: preflight.yml

- name: Include installation tasks
  include_tasks: install.yml

- name: Include configuration tasks
  include_tasks: configure.yml

- name: Include security hardening
  include_tasks: security.yml
  when: enable_security_hardening | default(true)

tasks/install.yml:

---
- name: Create application user
  user:
    name: "{{ app_user }}"
    system: yes
    shell: /bin/false

- name: Install application packages
  apt:
    name: "{{ app_packages }}"
    state: present

- name: Create application directories
  file:
    path: "{{ item }}"
    state: directory
    owner: "{{ app_user }}"
    group: "{{ app_group }}"
    mode: '0755'
  loop:
    - "{{ app_install_dir }}"
    - "{{ app_config_dir }}"
    - "{{ app_log_dir }}"

handlers/main.yml

Define handlers triggered by task changes.

---
- name: Restart myapp
  service:
    name: myapp
    state: restarted

- name: Reload myapp
  service:
    name: myapp
    state: reloaded

- name: Validate config
  command: myapp validate-config /etc/myapp/app.conf
  changed_when: false

- name: Clear cache
  command: myapp clear-cache

# Listen pattern (multiple triggers)
- name: Update systemd
  systemd:
    daemon_reload: yes
  listen: Reload systemd

templates/

Jinja2 templates for dynamic configuration files.

templates/app.conf.j2:

# {{ ansible_managed }}
# Application Configuration

[server]
port = {{ app_port }}
workers = {{ app_workers | default(4) }}
timeout = {{ app_timeout | default(30) }}

[logging]
level = {{ log_level | default('info') }}
path = {{ app_log_dir }}/app.log

{% if enable_monitoring %}
[monitoring]
enabled = true
metrics_port = {{ monitoring_port | default(9090) }}
{% endif %}

[database]
host = {{ db_host }}
port = {{ db_port }}
name = {{ db_name }}
user = {{ db_user }}
# Password stored in vault

templates/systemd.service.j2:

[Unit]
Description={{ app_name }} application
After=network.target

[Service]
Type=simple
User={{ app_user }}
Group={{ app_group }}
WorkingDirectory={{ app_install_dir }}
ExecStart={{ app_install_dir }}/bin/{{ app_name }} --config {{ app_config_dir }}/app.conf
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

files/

Static files copied without modification.

files/
├── ssl/
│   ├── ca.crt
│   └── dhparam.pem
├── scripts/
│   ├── backup.sh
│   └── healthcheck.sh
└── config/
    └── static.conf

Usage:

- name: Copy SSL certificate
  copy:
    src: ssl/ca.crt
    dest: /etc/ssl/certs/ca.crt
    owner: root
    group: root
    mode: '0644'

- name: Deploy backup script
  copy:
    src: scripts/backup.sh
    dest: /usr/local/bin/backup.sh
    owner: root
    group: root
    mode: '0755'

meta/main.yml

Role metadata and dependencies.

---
galaxy_info:
  role_name: myapp
  author: Your Name
  description: Deploy and configure myapp application
  company: Example Corp

  license: MIT

  min_ansible_version: "2.12"

  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: Debian
      versions:
        - bullseye

  galaxy_tags:
    - application
    - web
    - deployment

dependencies:
  - role: common
  - role: postgresql
    vars:
      postgresql_version: "15"
  - role: nginx
    when: install_nginx | default(true)

---

Best Practices

1. Single Responsibility

Each role should have one clear purpose.

Good:

roles/
├── nginx/         # Web server configuration
├── postgresql/    # Database configuration
├── redis/         # Cache configuration
└── myapp/         # Application deployment

Bad:

roles/
└── everything/    # Configures web, database, cache, app

2. Parameterize with Defaults

Provide sensible defaults, allow overrides.

# defaults/main.yml
nginx_worker_processes: auto  # Sensible default
nginx_worker_connections: 1024
nginx_enable_ssl: false       # Safe default

# Allow override in playbook
- role: nginx
  vars:
    nginx_worker_processes: 8
    nginx_enable_ssl: true

3. Use Descriptive Variable Names

# Good: Clear, scoped naming
nginx_worker_processes: 4
nginx_client_max_body_size: "10m"
nginx_ssl_protocols: "TLSv1.2 TLSv1.3"

# Bad: Vague, generic names
workers: 4
max_size: "10m"
protocols: "TLSv1.2 TLSv1.3"

4. Prefix Role Variables

Prevent variable collisions between roles.

# Good: Role prefix
myapp_version: "1.0.0"
myapp_port: 8080
myapp_enable_ssl: true

# Bad: No prefix (conflicts possible)
version: "1.0.0"
port: 8080
enable_ssl: true

5. Organize Complex Tasks

Split large task files into logical units.

# tasks/main.yml
- include_tasks: preflight.yml
- include_tasks: install.yml
- include_tasks: configure.yml
- include_tasks: security.yml

6. Document Role Usage

Create comprehensive README.md.

# myapp Role

Deploy and configure myapp application.

## Requirements

- Ansible >= 2.12
- Ubuntu 20.04 or 22.04

## Role Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `app_version` | `1.0.0` | Application version |
| `app_port` | `8080` | Application port |
| `enable_ssl` | `false` | Enable SSL |

## Dependencies

- `common`
- `postgresql`

## Example Playbook

• hosts: appservers

roles:

• role: myapp

vars: app_version: "2.0.0" app_port: 9000

## License

MIT

7. Version Control

.gitignore:
*.retry
.vault_pass
.molecule/

8. Test Roles with Molecule

Use Molecule for automated role testing.

cd roles/myapp
molecule test

---

Role Dependencies

Define Dependencies in meta/main.yml

---
dependencies:
  - role: common
  - role: postgresql
    vars:
      postgresql_version: "15"
      postgresql_databases:
        - name: myapp
          owner: myapp
  - role: nginx
    when: use_nginx_proxy | default(true)

Dependency Resolution

Dependencies execute before the role itself.

Execution order: 1. common role (dependency) 2. postgresql role (dependency) 3. nginx role (dependency, if condition met) 4. myapp role (main role)

Circular Dependencies

Avoid circular dependencies:

# BAD: Circular dependency
# Role A depends on B
# Role B depends on A

# GOOD: Extract shared logic to separate role
roles/
├── base/        # Shared dependencies
├── roleA/       # Depends on base
└── roleB/       # Depends on base

---

Collections

Collection Structure

Collections bundle roles, modules, and plugins.

ansible_collections/
└── mycompany/
    └── myapp/
        ├── roles/
        │   ├── webserver/
        │   ├── database/
        │   └── monitoring/
        ├── plugins/
        │   ├── modules/
        │   └── inventory/
        ├── playbooks/
        └── galaxy.yml

Create Collection

# Initialize collection
ansible-galaxy collection init mycompany.myapp

# Build collection
ansible-galaxy collection build

# Install collection
ansible-galaxy collection install mycompany-myapp-1.0.0.tar.gz

galaxy.yml

---
namespace: mycompany
name: myapp
version: 1.0.0
readme: README.md
authors:
  - Your Name <you@example.com>
description: MyApp deployment collection
license:
  - MIT
tags:
  - application
  - web
dependencies:
  community.general: ">=5.0.0"
  ansible.posix: ">=1.4.0"

Use Collection in Playbook

---
- name: Deploy application
  hosts: appservers
  collections:
    - mycompany.myapp

  roles:
    - webserver
    - database
    - monitoring

---

Testing Roles

Directory Structure

roles/myapp/
├── molecule/
│   └── default/
│       ├── molecule.yml
│       ├── converge.yml
│       └── verify.yml
└── tests/
    ├── test.yml
    └── inventory

Simple Test Playbook

tests/test.yml:

---
- name: Test myapp role
  hosts: localhost
  become: yes

  roles:
    - myapp

  post_tasks:
    - name: Verify service is running
      service:
        name: myapp
        state: started
      check_mode: yes
      register: service_check
      failed_when: service_check is changed

Run Test

# Run test playbook
ansible-playbook tests/test.yml -i tests/inventory

# With Molecule
molecule test

Run automated tests to verify role functionality before production deployment.

Secrets Management

Table of Contents

1. ansible-vault (Built-in) 2. HashiCorp Vault Integration 3. Best Practices 4. Comparison

---

ansible-vault (Built-in)

Basic Operations

Create encrypted file:

ansible-vault create group_vars/all/vault.yml
# Enter password when prompted

Edit encrypted file:

ansible-vault edit group_vars/all/vault.yml

View encrypted file:

ansible-vault view group_vars/all/vault.yml

Encrypt existing file:

ansible-vault encrypt secrets.yml

Decrypt file:

ansible-vault decrypt secrets.yml

Change password:

ansible-vault rekey group_vars/all/vault.yml

Vault File Content

group_vars/all/vault.yml (encrypted):

---
vault_db_password: "SuperSecretPassword123"
vault_api_key: "sk-abcdef123456"
vault_smtp_password: "email_password"
vault_ssl_private_key: |
  -----BEGIN PRIVATE KEY-----
  MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
  -----END PRIVATE KEY-----

Reference in unencrypted file:

group_vars/all/vars.yml (unencrypted):

---
db_host: "db.example.com"
db_user: "appuser"
db_password: "{{ vault_db_password }}"

api_endpoint: "https://api.example.com"
api_key: "{{ vault_api_key }}"

Run Playbooks with Vault

Method 1: Interactive password:

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

Method 2: Password file:

# Create password file
echo "MyVaultPassword" > ~/.vault_pass
chmod 600 ~/.vault_pass

# Run playbook
ansible-playbook site.yml --vault-password-file ~/.vault_pass

Method 3: Executable script:

# Create password script
cat > ~/.vault_pass.sh << 'EOF'
#!/bin/bash
# Fetch password from secret manager
aws secretsmanager get-secret-value \
  --secret-id ansible-vault-password \
  --query SecretString \
  --output text
EOF

chmod +x ~/.vault_pass.sh

# Run playbook
ansible-playbook site.yml --vault-password-file ~/.vault_pass.sh

Multiple Vault IDs

Use different passwords for different environments.

Create vaults with IDs:

# Production vault
ansible-vault create group_vars/production/vault.yml --vault-id prod@prompt

# Staging vault
ansible-vault create group_vars/staging/vault.yml --vault-id staging@prompt

Password files:

# Store passwords
echo "ProductionPassword" > ~/.vault_pass_prod
echo "StagingPassword" > ~/.vault_pass_staging
chmod 600 ~/.vault_pass_*

Run with specific vault ID:

ansible-playbook site.yml \
  --vault-id prod@~/.vault_pass_prod \
  --vault-id staging@~/.vault_pass_staging

Encrypt Strings

Encrypt individual strings instead of entire files.

# Encrypt string
ansible-vault encrypt_string 'SuperSecret123' --name 'db_password'

Output:

db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66386439653033653834303138656337353833656362393137313633633732306362333...

Use in playbook:

---
- name: Configure database
  hosts: databases
  vars:
    db_user: appuser
    db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66386439653033653834303138656337353833656362393137313633633732306362333...

  tasks:
    - name: Create database user
      postgresql_user:
        name: "{{ db_user }}"
        password: "{{ db_password }}"

ansible.cfg Configuration

[defaults]
vault_password_file = ~/.vault_pass

# Or multiple vault IDs
vault_identity_list = prod@~/.vault_pass_prod, staging@~/.vault_pass_staging

---

HashiCorp Vault Integration

Prerequisites

Install collection:

ansible-galaxy collection install community.hashi_vault

Vault server setup:

# Start Vault (dev mode for testing)
vault server -dev

# Set environment
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='dev-token'

# Create secrets
vault kv put secret/myapp/database \
  host=db.example.com \
  username=appuser \
  password=SuperSecret123

vault kv put secret/myapp/api \
  endpoint=https://api.example.com \
  key=sk-abcdef123456

Lookup Secrets in Playbooks

Method 1: KV v2 secrets (default):

---
- name: Configure application
  hosts: appservers
  vars:
    vault_addr: "http://127.0.0.1:8200"
    vault_token: "{{ lookup('env', 'VAULT_TOKEN') }}"

  tasks:
    - name: Fetch database password from Vault
      set_fact:
        db_config: "{{ lookup('community.hashi_vault.vault_kv2_get', 'secret/data/myapp/database', url=vault_addr, token=vault_token) }}"

    - name: Configure database connection
      template:
        src: database.conf.j2
        dest: /etc/myapp/database.conf
      vars:
        db_host: "{{ db_config.secret.host }}"
        db_user: "{{ db_config.secret.username }}"
        db_password: "{{ db_config.secret.password }}"

Method 2: Direct lookup:

- name: Read secret value
  debug:
    msg: "{{ lookup('community.hashi_vault.vault_read', 'secret/data/myapp/database').data.data.password }}"

Method 3: Using hashi_vault lookup (legacy):

- name: Fetch API key
  set_fact:
    api_key: "{{ lookup('community.hashi_vault.hashi_vault', 'secret/myapp/api:key') }}"

Authentication Methods

Token auth (simple):

vars:
  vault_token: "{{ lookup('env', 'VAULT_TOKEN') }}"

lookup('community.hashi_vault.vault_kv2_get',
       'secret/data/myapp/database',
       token=vault_token)

AppRole auth (production):

vars:
  vault_role_id: "{{ lookup('env', 'VAULT_ROLE_ID') }}"
  vault_secret_id: "{{ lookup('env', 'VAULT_SECRET_ID') }}"

lookup('community.hashi_vault.vault_kv2_get',
       'secret/data/myapp/database',
       role_id=vault_role_id,
       secret_id=vault_secret_id)

AWS IAM auth:

lookup('community.hashi_vault.vault_kv2_get',
       'secret/data/myapp/database',
       auth_method='aws_iam',
       mount_point='aws')

Dynamic Secrets

Generate credentials on-demand.

Database credentials:

- name: Generate dynamic database credentials
  set_fact:
    db_creds: "{{ lookup('community.hashi_vault.vault_read', 'database/creds/myapp-role') }}"

- name: Use dynamic credentials
  debug:
    msg: |
      Username: {{ db_creds.data.username }}
      Password: {{ db_creds.data.password }}
      Lease: {{ db_creds.lease_duration }} seconds

AWS credentials:

- name: Generate AWS credentials
  set_fact:
    aws_creds: "{{ lookup('community.hashi_vault.vault_read', 'aws/creds/deploy-role') }}"

- name: Use AWS credentials
  aws_s3:
    aws_access_key: "{{ aws_creds.data.access_key }}"
    aws_secret_key: "{{ aws_creds.data.secret_key }}"
    bucket: mybucket
    object: myfile
    mode: put

Template Example

templates/database.conf.j2:

# Database Configuration
{% set db = lookup('community.hashi_vault.vault_kv2_get', 'secret/data/myapp/database') %}

[database]
host = {{ db.secret.host }}
port = {{ db.secret.port | default(5432) }}
name = {{ db.secret.database }}
user = {{ db.secret.username }}
password = {{ db.secret.password }}

[connection]
pool_size = {{ db_pool_size | default(10) }}

---

Best Practices

1. Separate Secrets from Configuration

Good structure:

group_vars/
├── all/
│   ├── vars.yml        # Unencrypted config
│   └── vault.yml       # Encrypted secrets
└── production/
    ├── vars.yml
    └── vault.yml

vars.yml (unencrypted):

db_host: "db.example.com"
db_user: "appuser"
db_password: "{{ vault_db_password }}"

vault.yml (encrypted):

vault_db_password: "SuperSecret123"

2. Prefix Vault Variables

# Good: Clear which vars are from vault
vault_db_password: "secret"
vault_api_key: "secret"
vault_ssl_cert: "secret"

# Bad: Unclear source
db_password: "secret"
api_key: "secret"
ssl_cert: "secret"

3. Never Commit Unencrypted Secrets

.gitignore:

# Vault password files
.vault_pass*
vault_password*

# Decrypted files (if working locally)
*_decrypted.yml
secrets_plain.yml

# SSH keys
*.pem
id_rsa

4. Rotate Secrets Regularly

# Update secret in vault
ansible-vault edit group_vars/all/vault.yml

# Rotate vault password
ansible-vault rekey group_vars/all/vault.yml

5. Use Different Passwords per Environment

.vault_pass_production   # Production password
.vault_pass_staging      # Staging password
.vault_pass_development  # Development password

6. Audit Secret Access

With HashiCorp Vault:

# Enable audit logging
vault audit enable file file_path=/var/log/vault_audit.log

# View audit log
tail -f /var/log/vault_audit.log

7. Limit Secret Scope

Don't put all secrets in one file.

Good:

group_vars/
├── webservers/
│   └── vault.yml      # Only web secrets
└── databases/
    └── vault.yml      # Only DB secrets

Bad:

group_vars/
└── all/
    └── vault.yml      # All secrets (unnecessary exposure)

8. Test Vault Access

# Test vault decryption
ansible-vault view group_vars/all/vault.yml --vault-password-file ~/.vault_pass

# Test playbook with vault
ansible-playbook site.yml --check --vault-password-file ~/.vault_pass

9. Use Vault for CI/CD

GitHub Actions example:

- name: Run Ansible playbook
  env:
    VAULT_PASSWORD: ${{ secrets.VAULT_PASSWORD }}
  run: |
    echo "$VAULT_PASSWORD" > .vault_pass
    ansible-playbook site.yml --vault-password-file .vault_pass
    rm .vault_pass

10. Document Secret Requirements

README.md:

## Required Secrets

### ansible-vault
- `vault_db_password` - PostgreSQL password
- `vault_api_key` - External API key
- `vault_ssl_private_key` - SSL private key

### HashiCorp Vault Paths
- `secret/myapp/database` - Database credentials
- `secret/myapp/api` - API configuration
- `secret/myapp/ssl` - SSL certificates

---

Comparison

When to Use ansible-vault

• Small teams (< 10 people)
• Simple secret management needs
• No compliance requirements
• Secrets change infrequently
• No need for audit trails

When to Use HashiCorp Vault

• Large teams or enterprises
• Dynamic secret generation needed
• Compliance requirements (SOC2, PCI-DSS)
• Frequent secret rotation
• Detailed audit logging required
• Integration with multiple tools (not just Ansible)
• Cloud-native architectures

Hybrid Approach

Use both for different purposes:

# Low-sensitivity config: ansible-vault
vault_app_config: "non-critical-config"

# High-sensitivity credentials: HashiCorp Vault
db_password: "{{ lookup('community.hashi_vault.vault_kv2_get', 'secret/data/myapp/database').secret.password }}"