# Ansible Infrastructure Project Rules

## Project Context
This is an Ansible infrastructure automation project managing multiple hosts including development machines, service VMs, and Proxmox infrastructure. The project uses Makefile for task automation and Ansible Vault for secrets management.

## Code Style & Conventions

### Ansible YAML Files
- Use 2 spaces for indentation (no tabs)
- Always include `name:` for tasks with descriptive names
- Use `become: true` at play level when most tasks need sudo
- Group related tasks with block statements
- Always use fully qualified module names (e.g., `ansible.builtin.package`)
- Use handlers for service restarts

### Variable Naming
- Prefix vault variables with `vault_` (e.g., `vault_tailscale_auth_key`)
- Use snake_case for all variables
- Define defaults in `roles/*/defaults/main.yml`
- Override in `group_vars/` or `host_vars/`
- Document variables with comments

### Role Structure
```
roles/role_name/
├── defaults/main.yml    # Default variables
├── handlers/main.yml    # Service handlers
├── tasks/main.yml       # Main tasks
├── templates/           # Jinja2 templates
├── files/              # Static files
├── vars/main.yml       # Role variables (rarely used)
└── README.md           # Role documentation
```

### Task Best Practices
```yaml
# Good
- name: Install required packages
  ansible.builtin.package:
    name: "{{ item }}"
    state: present
  loop: "{{ required_packages }}"
  when: required_packages is defined

# Bad
- package:
    name: vim
    state: present
```

## File Organization

### Documentation
- Place all documentation in `docs/` directory
- Use `docs/guides/` for how-to guides
- Use `docs/reference/` for technical references
- Keep README.md concise with links to detailed docs

### Playbook Organization
- One playbook per major function (dev, local, maintenance, etc.)
- Use tags for selective execution
- Import roles in logical order (base → specific)

### Inventory
- Group hosts logically in `hosts` file
- Use group_vars for shared configuration
- Use host_vars for host-specific settings

## Security Practices

### Vault Usage
- ALWAYS encrypt sensitive data with Ansible Vault
- Store vault password in `~/.ansible-vault-pass`
- Never commit unencrypted secrets
- Use `make create-vault` and `make edit-vault` commands

### SSH Security
- Use SSH keys only (no passwords)
- Implement fail2ban on all hosts
- Configure UFW firewall
- Use Tailscale for additional security layer

## Makefile Conventions

### Target Naming
- Use lowercase with hyphens (e.g., `tailscale-status`)
- Include help text with `##` comment
- Group related targets together
- Provide usage examples in help text

### Common Patterns
```makefile
target: ## Description (usage: make target [VAR=value])
	@echo "Executing target..."
	$(ANSIBLE_PLAYBOOK) playbook.yml $(ANSIBLE_ARGS)
```

## Development Workflow

### Before Making Changes
1. Test connectivity: `make ping`
2. Check current state: `make facts`
3. Review existing configuration in host_vars

### Making Changes
1. Edit role or playbook
2. Test with check mode: `make check`
3. Apply to single host first: `make dev HOST=testhost`
4. Apply to group/all: `make apply`

### Testing
- Always use `--check` mode first
- Test on single host before group
- Use `--diff` to see changes
- Verify idempotency (run twice, expect no changes)

## Common Patterns

### Installing Packages
```yaml
- name: Install packages
  ansible.builtin.package:
    name:
      - package1
      - package2
    state: present
  become: true
```

### Managing Services
```yaml
- name: Ensure service is running
  ansible.builtin.systemd:
    name: service_name
    state: started
    enabled: true
    daemon_reload: true
  become: true
```

### Using Templates
```yaml
- name: Deploy configuration
  ansible.builtin.template:
    src: config.j2
    dest: /etc/service/config
    owner: root
    group: root
    mode: '0644'
  become: true
  notify: restart service
```

### Conditional Execution
```yaml
- name: Task for Debian family
  ansible.builtin.package:
    name: package
    state: present
  when: ansible_os_family == "Debian"
```

## Error Handling

### Common Issues
1. **Vault password issues**: Check `~/.ansible-vault-pass`
2. **SSH connection failed**: Verify SSH keys with `make copy-ssh-key`
3. **Sudo password required**: Configure passwordless sudo or use `--ask-become-pass`
4. **Python not found**: Set `ansible_python_interpreter` in inventory

### Debugging
- Use `make debug` for verbose output
- Add `debugger: on_failed` to tasks
- Check logs in `/var/log/ansible/` on targets
- Use `ansible -m setup` to gather facts

## Performance Optimization

### Ansible Configuration
- Set appropriate `forks` value in ansible.cfg
- Use `pipelining = True` for SSH optimization
- Cache facts when appropriate
- Use `serial` for rolling updates

### Task Optimization
- Minimize `command` and `shell` usage
- Use native modules when available
- Batch operations with `loop` or `with_items`
- Use `async` for long-running tasks

## Documentation Standards

### Role Documentation
Each role must have a README.md with:
- Purpose and description
- Required variables
- Optional variables with defaults
- Example usage
- Dependencies

### Playbook Documentation
Include header comment with:
```yaml
---
# Playbook: name
# Purpose: what it does
# Targets: which hosts
# Tags: available tags
# Usage: make command examples
```

## Git Practices

### Commit Messages
- Use present tense ("Add feature" not "Added feature")
- Reference issue numbers when applicable
- Keep first line under 50 characters
- Add detailed description if needed

### Branch Strategy
- `master`: Stable, tested code
- `develop`: Integration branch
- `feature/*`: New features
- `fix/*`: Bug fixes
- `hotfix/*`: Urgent production fixes

## Maintenance

### Regular Tasks
- Update packages monthly: `make maintenance`
- Review and rotate vault passwords quarterly
- Audit SSH keys semi-annually
- Update Ansible and collections annually

### Monitoring
- Check service status: `make tailscale-status`
- Review logs regularly
- Monitor system health
- Track system resources

## Support & Resources

### Internal Documentation
- `/docs/guides/` - How-to guides
- `/docs/reference/` - Technical references
- Role README files
- Makefile help: `make help`

### External Resources
- Ansible documentation: https://docs.ansible.com
- Ansible Galaxy: https://galaxy.ansible.com
- Tailscale docs: https://tailscale.com/kb
- Project issues tracker

## AI Assistant Guidelines

When working with this project:
1. Always check existing patterns before suggesting changes
2. Maintain consistent style with existing code
3. Test all changes with check mode first
4. Update documentation when adding features
5. Use Makefile commands instead of direct ansible-playbook calls
6. Encrypt sensitive data with Ansible Vault
7. Follow security best practices
8. Consider idempotency in all tasks
9. Provide clear task names and comments
10. Group related changes logically