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
• Role Documentation
• Cheatsheet

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

Typical Usage:

- 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
• Role Documentation
• Cheatsheet

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

Typical Usage:

- 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:

   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

---
# 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

# 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
• Architecture Overview
• Security Model
• Variables Documentation

---

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