/managing-configuration

name: managing-configuration
description: Guide users through creating, managing, and testing server configuration automation using Ansible. When automating server configurations, deploying applications with Ansible playbooks, managing dynamic inventories for cloud environments, or testing roles with Molecule, this skill provides idempotency patterns, secrets management with ansible-vault and HashiCorp Vault, and GitOps workflows for configuration as code.

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/in