CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an Ansible setup repository for managing system configurations. The project uses Ansible for infrastructure automation and configuration management.

License: GNU Affero General Public License v3.0 (AGPL-3.0)

Repository Structure

This repository is currently in early setup phase. Typical Ansible project structure includes:

playbooks/ - Ansible playbooks for orchestrating configurations
roles/ - Reusable Ansible roles
inventory/ - Host inventory files (hosts.ini, hosts.yml)
group_vars/ - Variables organized by groups
host_vars/ - Variables for specific hosts
ansible.cfg - Ansible configuration file

Common Ansible Commands

Running Playbooks

# Run a playbook
ansible-playbook playbooks/site.yml

# Run with specific inventory
ansible-playbook -i inventory/hosts.ini playbooks/site.yml

# Check mode (dry run)
ansible-playbook --check playbooks/site.yml

# Run with specific tags
ansible-playbook playbooks/site.yml --tags "web,database"

# Run specific hosts
ansible-playbook playbooks/site.yml --limit "webservers"

Testing and Validation

# Check playbook syntax
ansible-playbook --syntax-check playbooks/site.yml

# List tasks in a playbook
ansible-playbook --list-tasks playbooks/site.yml

# List hosts that will be affected
ansible-playbook --list-hosts playbooks/site.yml

# Validate inventory
ansible-inventory --list -i inventory/hosts.ini
ansible-inventory --graph -i inventory/hosts.ini

Ad-hoc Commands

# Ping all hosts
ansible all -m ping

# Check disk space on all hosts
ansible all -a "df -h"

# Gather facts from hosts
ansible all -m setup

Ansible Vault (for sensitive data)

# Create encrypted file
ansible-vault create group_vars/production/vault.yml

# Edit encrypted file
ansible-vault edit group_vars/production/vault.yml

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

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

Development Workflow

When Creating Playbooks

Use YAML syntax with proper indentation (2 spaces)
Start playbooks with descriptive names and hosts definitions
Include gather_facts: yes/no explicitly
Use become: yes when privilege escalation is needed
Group related tasks using block statements
Add meaningful task names that describe the action

When Creating Roles

Follow Ansible Galaxy role structure: tasks/, handlers/, templates/, files/, vars/, defaults/, meta/
Keep roles focused on a single responsibility
Use role dependencies in meta/main.yml when appropriate
Test roles independently before integrating

Variables and Inventory

Use group_vars for shared variables across host groups
Use host_vars for host-specific configurations
Prefer YAML format over INI for inventory when complexity grows
Never commit sensitive data unencrypted (use ansible-vault)

Best Practices

Always test with --check mode first
Use handlers for service restarts and reloads
Leverage tags for partial playbook execution
Use templates (Jinja2) for dynamic configuration files
Register task outputs when results are needed in subsequent tasks
Use changed_when and failed_when to control task status reporting

3.3 KiB Raw Blame History