infra-automation/docs/roles/role-index.md

# Ansible Roles Index

Comprehensive index of all Ansible roles in this infrastructure automation project.

## Overview

This document provides a central index of all custom roles with descriptions, purposes, and quick links to documentation.

---

## Production Roles

### deploy_linux_vm

**Purpose**: Automated deployment of Linux virtual machines on KVM/libvirt hypervisors with comprehensive security hardening and LVM storage management.

**Key Features**:
- Multi-distribution support (Debian, Ubuntu, RHEL, AlmaLinux, Rocky Linux, openSUSE)
- Automated cloud-init provisioning
- LVM storage with CLAUDE.md-compliant partition schema
- SSH hardening with GSSAPI disabled
- SELinux/AppArmor enforcement
- Firewall configuration (UFW/firewalld)
- Automatic security updates

**Status**: ✓ Production Ready

**Links**:
- [Role README](../../roles/deploy_linux_vm/README.md)
- [Role Documentation](./deploy_linux_vm.md)
- [Cheatsheet](../../cheatsheets/roles/deploy_linux_vm.md)

**Tags**: `deploy_linux_vm`, `validate`, `preflight`, `install`, `download`, `verify`, `storage`, `cloud-init`, `deploy`, `lvm`, `post-deploy`, `cleanup`

**Typical Usage**:
```yaml
- role: deploy_linux_vm
  vars:
    deploy_linux_vm_name: "webserver01"
    deploy_linux_vm_os_distribution: "ubuntu-22.04"
    deploy_linux_vm_vcpus: 4
    deploy_linux_vm_memory_mb: 8192
```

---

### system_info

**Purpose**: Comprehensive system information gathering for infrastructure inventory, capacity planning, and compliance documentation.

**Key Features**:
- CPU, GPU, RAM, disk, and network information collection
- Hypervisor detection (KVM, Proxmox, LXD, Docker, Podman)
- JSON export with timestamped backups
- Human-readable summary reports
- Health checks and validation
- CMDB integration support

**Status**: ✓ Production Ready

**Links**:
- [Role README](../../roles/system_info/README.md)
- [Role Documentation](./system_info.md)
- [Cheatsheet](../../cheatsheets/roles/system_info.md)

**Tags**: `system_info`, `install`, `gather`, `system`, `cpu`, `gpu`, `memory`, `disk`, `network`, `hypervisor`, `export`, `statistics`, `validate`, `health-check`, `security`

**Typical Usage**:
```yaml
- role: system_info
  vars:
    system_info_stats_base_dir: "./stats/machines"
    system_info_gather_gpu: true
    system_info_detect_hypervisor: true
```

**Output Location**: `./stats/machines/<fqdn>/system_info.json`

---

## Role Categories

### Infrastructure Management
- **deploy_linux_vm**: VM provisioning and deployment
- **system_info**: System inventory and information gathering

### Security & Compliance
- **deploy_linux_vm**: Security hardening, SSH configuration, firewall setup
- **system_info**: Security module detection, compliance data collection

### Monitoring & Observability
- **system_info**: Performance metrics, resource utilization

---

## Role Dependencies

```
┌─────────────────────┐
│  deploy_linux_vm    │  (No dependencies)
└──────────┬──────────┘
           │
           │ (typically followed by)
           ▼
┌─────────────────────┐
│    system_info      │  (No dependencies)
└─────────────────────┘
           │
           │ (data used by)
           ▼
┌─────────────────────┐
│  Application Roles  │  (Future: webserver, database, etc.)
└─────────────────────┘
```

---

## Role Selection Guide

### When to use deploy_linux_vm

Use this role when you need to:
- ✓ Create new Linux VMs on KVM hypervisors
- ✓ Automate VM provisioning with cloud-init
- ✓ Implement security-hardened infrastructure
- ✓ Configure LVM storage according to CLAUDE.md standards
- ✓ Deploy multi-distribution environments
- ✓ Maintain consistent VM configurations

**Do NOT use** when:
- ✗ Provisioning physical servers (use kickstart/preseed directly)
- ✗ Working with cloud providers (use cloud-specific modules)
- ✗ Managing existing VMs (use configuration management roles)

### When to use system_info

Use this role when you need to:
- ✓ Create infrastructure inventory
- ✓ Perform capacity planning analysis
- ✓ Generate compliance reports
- ✓ Audit system configurations
- ✓ Detect hypervisor capabilities
- ✓ Export data to CMDB systems

**Do NOT use** when:
- ✗ Real-time monitoring needed (use Prometheus/Grafana)
- ✗ Log aggregation required (use ELK/Graylog)
- ✗ Continuous metrics collection (use monitoring agents)

---

## Role Development Standards

All roles in this project follow these standards:

### Required Structure
```
roles/role_name/
├── README.md           # Comprehensive documentation
├── meta/
│   └── main.yml       # Dependencies and metadata
├── defaults/
│   └── main.yml       # Default variables
├── vars/
│   └── main.yml       # Role variables
├── tasks/
│   ├── main.yml       # Main task entry point
│   ├── install.yml    # Installation tasks
│   ├── configure.yml  # Configuration tasks
│   ├── security.yml   # Security hardening
│   └── validate.yml   # Validation and health checks
├── handlers/
│   └── main.yml       # Service handlers
├── templates/
│   └── *.j2           # Jinja2 templates
├── files/
│   └── *              # Static files
└── tests/
    └── test.yml       # Test playbook
```

### Required Documentation
- ✓ README.md in role directory (comprehensive)
- ✓ Documentation file in `docs/roles/` (detailed)
- ✓ Cheatsheet in `cheatsheets/roles/` (quick reference)
- ✓ Entry in this index file

### Required Tags
All roles must implement these tags:
- `install`: Package installation
- `configure`: Configuration tasks
- `security`: Security hardening
- `validate`: Validation and health checks

### Security Requirements
- ✓ No hardcoded secrets or credentials
- ✓ Use `no_log: true` for sensitive output
- ✓ Validate file permissions
- ✓ Implement proper error handling
- ✓ Use HTTPS for downloads
- ✓ Verify checksums

### Production Readiness Checklist
- ✓ Comprehensive README with all sections
- ✓ All variables documented with types and examples
- ✓ Example playbooks provided
- ✓ Security considerations documented
- ✓ Tags implemented for selective execution
- ✓ Idempotency verified
- ✓ Multi-OS compatibility tested
- ✓ Molecule tests implemented (optional but recommended)

---

## Creating New Roles

### Process

1. **Create role skeleton**:
   ```bash
   ansible-galaxy role init roles/new_role_name
   ```

2. **Implement role following CLAUDE.md guidelines**:
   - Security-first approach
   - Modularity and reusability
   - Comprehensive variable documentation
   - Tag-based execution support

3. **Create documentation**:
   - `roles/new_role_name/README.md`
   - `docs/roles/new_role_name.md`
   - `cheatsheets/roles/new_role_name.md`

4. **Update this index**:
   - Add role entry with description
   - Update role categories
   - Update dependency diagram

5. **Test thoroughly**:
   - Implement Molecule tests (optional)
   - Test on all target distributions
   - Validate idempotency
   - Security scan

6. **Document and version**:
   - Semantic versioning (MAJOR.MINOR.PATCH)
   - Update CHANGELOG.md
   - Tag release in git

### Template

```yaml
---
# roles/new_role_name/README.md structure

# Role Name

Brief description

## Requirements
- Ansible version
- OS compatibility
- Dependencies

## Role Variables

| Variable | Default | Description | Required |
|----------|---------|-------------|----------|
| var_name | value   | Description | Yes/No   |

## Dependencies

List of dependent roles

## Example Playbook

```yaml
- hosts: servers
  roles:
    - role: new_role_name
      var_name: value
```

## Security Considerations

Document security implications

## License

Organization license

## Author

Maintainer information
```

---

## Role Versioning

| Role | Current Version | Last Updated | Status |
|------|----------------|--------------|--------|
| deploy_linux_vm | 1.0.0 | 2025-11-11 | ✓ Stable |
| system_info | 1.0.0 | 2025-11-11 | ✓ Stable |

---

## Future Roles (Planned)

### Application Roles
- **webserver**: Nginx/Apache web server configuration
- **database**: PostgreSQL/MySQL database setup
- **cache**: Redis/Memcached caching layer
- **message_queue**: RabbitMQ/Kafka message broker

### Security Roles
- **hardening**: OS-level security hardening (CIS compliance)
- **monitoring**: Prometheus/Grafana monitoring stack
- **logging**: ELK stack or Graylog setup
- **backup**: Automated backup configuration

### Infrastructure Roles
- **kubernetes_node**: Kubernetes cluster node setup
- **docker_host**: Docker host configuration
- **load_balancer**: HAProxy/Nginx load balancer
- **proxy**: Squid/Nginx proxy server

---

## Quick Reference

### Most Common Commands

```bash
# Deploy a VM
ansible-playbook site.yml -t deploy_linux_vm

# Gather system information
ansible-playbook site.yml -t system_info

# Deploy VM and gather info
ansible-playbook site.yml -t deploy_linux_vm,system_info

# Validation only
ansible-playbook site.yml -t validate

# Security hardening only
ansible-playbook site.yml -t security
```

### Finding Role Documentation

```bash
# Role README
cat roles/<role_name>/README.md

# Detailed documentation
cat docs/roles/<role_name>.md

# Quick reference cheatsheet
cat cheatsheets/roles/<role_name>.md

# List all role variables
grep "^[a-z_]*:" roles/<role_name>/defaults/main.yml
```

---

## Support and Contribution

### Getting Help
- Check role README.md first
- Review detailed documentation in docs/roles/
- Consult cheatsheets for quick reference
- Review CLAUDE.md for guidelines

### Contributing
- Follow CLAUDE.md development standards
- Document all changes
- Test on all supported distributions
- Update relevant documentation
- Submit for code review

### Reporting Issues
- Provide role name and version
- Include error messages and logs
- Describe expected vs actual behavior
- Include playbook excerpt if relevant

---

## Related Documentation

- [CLAUDE.md Guidelines](../../CLAUDE.md)
- [Architecture Overview](../architecture/overview.md)
- [Security Model](../architecture/security-model.md)
- [Variables Documentation](../variables.md)

---

**Document Version**: 1.0.0
**Last Updated**: 2025-11-11
**Maintained By**: Ansible Infrastructure Team