Managing Configuration

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