113 lines
3.3 KiB
Markdown
113 lines
3.3 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
# 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
|