# Execution Plan - Ansible Infrastructure Automation

This document provides detailed, actionable todo lists for executing the roadmap objectives defined in [ROADMAP.md](ROADMAP.md).

**Created:** 2025-11-10
**Status:** Active
**Tracking Method:** GitHub Issues / Gitea Issues

---

## How to Use This Document

1. Each phase has detailed todo lists with actionable tasks
2. Tasks are marked with priorities: 🔴 HIGH, 🟡 MEDIUM, 🟢 LOW
3. Dependencies are clearly noted
4. Estimated effort is provided (hours/days)
5. Tasks can be converted to issues in Gitea for tracking

---

## Phase 1: Foundation Strengthening (Weeks 1-4)

### Week 1: Infrastructure Repository Organization

#### Task 1.1: Create Inventories Repository
**Priority:** 🔴 HIGH | **Effort:** 4 hours | **Assignee:** TBD

**Todo List:**
- [ ] Create new repository `ansible/inventories` on Gitea via API
  - Use API: `POST /api/v1/user/repos`
  - Set as public repository
  - Add description: "Ansible dynamic and static inventory configurations"
- [ ] Initialize repository with README.md
- [ ] Create directory structure:
  ```
  inventories/
  ├── README.md
  ├── production/
  │   ├── README.md
  │   ├── aws_ec2.yml
  │   ├── azure_rm.yml
  │   ├── libvirt_kvm.yml
  │   └── group_vars/
  ├── staging/
  │   └── [similar structure]
  └── development/
      └── hosts.yml
  ```
- [ ] Create `.gitignore` for inventory cache files
- [ ] Document inventory structure in README.md
- [ ] Add example inventory configurations for each type

**Acceptance Criteria:**
- Repository created and accessible
- All directories created with READMEs
- Example configurations present
- Documentation complete

---

#### Task 1.2: Configure Inventories as Submodule
**Priority:** 🔴 HIGH | **Effort:** 2 hours | **Depends On:** Task 1.1

**Todo List:**
- [ ] Remove current `inventories/` directory from main repo (if exists)
  ```bash
  git rm -rf inventories/
  ```
- [ ] Add inventories repository as git submodule
  ```bash
  git submodule add ssh://git@git.mymx.me:2222/ansible/inventories.git inventories
  ```
- [ ] Update `.gitmodules` file
- [ ] Test submodule operations:
  - [ ] Clone with submodules
  - [ ] Update submodule
  - [ ] Push changes to submodule
- [ ] Document submodule workflow in docs/inventory.md
- [ ] Create cheatsheet for submodule operations
- [ ] Update main README.md with submodule instructions

**Acceptance Criteria:**
- Inventories configured as submodule
- Submodule operations tested and working
- Documentation updated

---

#### Task 1.3: Migrate Existing Inventories
**Priority:** 🟡 MEDIUM | **Effort:** 3 hours | **Depends On:** Task 1.2

**Todo List:**
- [ ] Copy existing inventory files to inventories submodule
  - [ ] inventory-debian-vm.ini → inventories/development/
  - [ ] inventory-debian-vm-direct.ini → inventories/development/
- [ ] Copy dynamic inventory plugins
  - [ ] plugins/inventory/libvirt_kvm.py → inventories/production/libvirt_kvm.yml (config)
  - [ ] plugins/inventory/ssh_config_inventory.py → keep in main repo (plugin)
- [ ] Create inventory configuration for each environment
- [ ] Test all inventory sources
  ```bash
  ansible-inventory -i inventories/development/hosts.yml --list
  ansible-inventory -i inventories/production/libvirt_kvm.yml --list
  ```
- [ ] Update playbooks to reference new inventory locations
- [ ] Commit and push changes to inventories submodule
- [ ] Update CHANGELOG.md

**Acceptance Criteria:**
- All inventories migrated successfully
- No broken playbook references
- All inventory sources tested and working

---

### Week 2: CI/CD Pipeline Setup

#### Task 2.1: Configure Gitea Actions
**Priority:** 🔴 HIGH | **Effort:** 6 hours

**Todo List:**
- [ ] Research Gitea Actions capabilities and requirements
- [ ] Install Gitea Actions runner (if not available)
- [ ] Create `.gitea/workflows/` directory in main repository
- [ ] Create workflow: `lint.yml`
  ```yaml
  name: Ansible Lint
  on: [push, pull_request]
  jobs:
    lint:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
        - name: Run ansible-lint
          uses: ansible/ansible-lint-action@main
  ```
- [ ] Create workflow: `syntax-check.yml`
  - Run ansible-playbook --syntax-check on all playbooks
- [ ] Create workflow: `yaml-lint.yml`
  - Run yamllint on all YAML files
- [ ] Test workflows with sample commits
- [ ] Configure branch protection for master/main
  - Require status checks to pass
  - Require pull request reviews
- [ ] Document CI/CD setup in docs/ci-cd.md
- [ ] Update CLAUDE.md with CI/CD requirements

**Acceptance Criteria:**
- Gitea Actions configured and running
- All workflows passing
- Branch protection enabled
- Documentation complete

---

#### Task 2.2: Setup Pre-commit Hooks
**Priority:** 🟡 MEDIUM | **Effort:** 3 hours | **Depends On:** Task 2.1

**Todo List:**
- [ ] Install pre-commit framework
  ```bash
  pip3 install pre-commit
  ```
- [ ] Create `.pre-commit-config.yaml` in repository root
  ```yaml
  repos:
    - repo: https://github.com/ansible/ansible-lint
      rev: v6.20.0
      hooks:
        - id: ansible-lint
    - repo: https://github.com/adrienverge/yamllint
      rev: v1.32.0
      hooks:
        - id: yamllint
    - repo: https://github.com/pre-commit/pre-commit-hooks
      rev: v4.5.0
      hooks:
        - id: trailing-whitespace
        - id: end-of-file-fixer
        - id: check-yaml
        - id: check-added-large-files
  ```
- [ ] Test pre-commit hooks locally
  ```bash
  pre-commit run --all-files
  ```
- [ ] Install pre-commit hooks
  ```bash
  pre-commit install
  ```
- [ ] Document pre-commit setup in CONTRIBUTING.md
- [ ] Add pre-commit installation to development setup docs
- [ ] Create troubleshooting guide for common pre-commit issues

**Acceptance Criteria:**
- Pre-commit hooks installed and working
- All hooks passing on current codebase
- Documentation complete

---

### Week 3: Testing Framework Setup

#### Task 3.1: Install and Configure Molecule
**Priority:** 🔴 HIGH | **Effort:** 8 hours

**Todo List:**
- [ ] Install Molecule and dependencies
  ```bash
  pip3 install molecule molecule-plugins[docker] ansible-lint
  ```
- [ ] Install Docker or Podman for test containers
  ```bash
  # Debian/Ubuntu
  apt-get install docker.io
  # OR
  apt-get install podman
  ```
- [ ] Configure user for Docker/Podman access
  ```bash
  usermod -aG docker $USER
  ```
- [ ] Create Molecule scenario for deploy_linux_vm role
  ```bash
  cd roles/deploy_linux_vm
  molecule init scenario --driver-name docker
  ```
- [ ] Configure molecule.yml for multi-platform testing
  - Debian 11
  - Debian 12
  - Ubuntu 22.04
  - Rocky Linux 9
- [ ] Create converge.yml playbook for testing
- [ ] Create verify.yml for test assertions
- [ ] Run initial tests
  ```bash
  molecule test
  ```
- [ ] Document Molecule usage in docs/testing.md
- [ ] Create testing cheatsheet
- [ ] Add Molecule tests to CI/CD pipeline

**Acceptance Criteria:**
- Molecule installed and configured
- Tests running successfully
- Multi-platform testing working
- Documentation complete
- CI/CD integration complete

---

#### Task 3.2: Create Test Coverage for Existing Role
**Priority:** 🔴 HIGH | **Effort:** 6 hours | **Depends On:** Task 3.1

**Todo List:**
- [ ] Analyze deploy_linux_vm role for test scenarios
- [ ] Create test cases for:
  - [ ] LVM configuration validation
  - [ ] Package installation verification
  - [ ] Service state checks
  - [ ] Security hardening validation
  - [ ] SSH configuration tests
  - [ ] Firewall rule verification
- [ ] Implement verify.yml with testinfra or Ansible asserts
- [ ] Add edge case testing:
  - [ ] Minimal resources scenario
  - [ ] Different OS distributions
  - [ ] Custom variable configurations
- [ ] Achieve >80% test coverage
- [ ] Document test scenarios in role README.md
- [ ] Create test report generation
- [ ] Add test metrics to CI/CD pipeline

**Acceptance Criteria:**
- All critical paths tested
- >80% test coverage achieved
- Tests passing consistently
- Documentation updated

---

### Week 4: Testing Documentation & Optimization

#### Task 4.1: Create Comprehensive Testing Documentation
**Priority:** 🟡 MEDIUM | **Effort:** 4 hours

**Todo List:**
- [ ] Create docs/testing.md with:
  - [ ] Testing philosophy and approach
  - [ ] Molecule usage guide
  - [ ] Writing test cases
  - [ ] Running tests locally
  - [ ] Debugging failed tests
  - [ ] CI/CD test integration
- [ ] Create cheatsheets/testing.md with:
  - [ ] Common Molecule commands
  - [ ] Quick test scenarios
  - [ ] Troubleshooting tips
- [ ] Add testing section to CLAUDE.md
- [ ] Create video walkthrough (optional)
- [ ] Update CONTRIBUTING.md with testing requirements

**Acceptance Criteria:**
- Comprehensive testing documentation
- Cheatsheet created
- Guidelines updated

---

## Phase 2: Core Role Development (Weeks 5-8)

### Week 5: Common Role Development

#### Task 5.1: Create Common Base Role
**Priority:** 🔴 HIGH | **Effort:** 12 hours

**Todo List:**
- [ ] Create role structure
  ```bash
  ansible-galaxy init roles/common
  ```
- [ ] Design role architecture:
  - [ ] defaults/main.yml - Default variables
  - [ ] vars/Debian.yml - Debian family specific vars
  - [ ] vars/RedHat.yml - RedHat family specific vars
  - [ ] tasks/main.yml - Main entry point
  - [ ] tasks/packages.yml - Package installation
  - [ ] tasks/users.yml - User management
  - [ ] tasks/ssh.yml - SSH hardening
  - [ ] tasks/time.yml - Time synchronization
  - [ ] tasks/logging.yml - System logging
  - [ ] templates/sshd_config.j2 - SSH config template
  - [ ] templates/chrony.conf.j2 - Chrony config template
  - [ ] handlers/main.yml - Service handlers
- [ ] Implement package installation logic
  - Essential packages list (vim, htop, curl, wget, etc.)
  - OS-specific package handling
  - Package update mechanism
- [ ] Implement user management
  - ansible user creation
  - authorized_keys management
  - sudo configuration (NOPASSWD)
  - User groups
- [ ] Implement SSH hardening
  - Disable root login
  - Key-based authentication only
  - Configure SSH timeouts
  - Disable password authentication
  - Configure allowed users
- [ ] Implement time synchronization
  - Install and configure chrony
  - Configure NTP servers
  - Timezone configuration
  - Verify time sync status
- [ ] Implement logging configuration
  - Configure rsyslog
  - Log rotation settings
  - Remote syslog (optional)
  - journald configuration
- [ ] Create comprehensive README.md
- [ ] Add proper tagging (install, configure, users, ssh, time, logging)
- [ ] Create Molecule tests
- [ ] Test on multiple distributions
- [ ] Document variables and examples

**Acceptance Criteria:**
- Role complete and functional
- Tests passing on Debian and RHEL families
- Documentation complete
- Code passes ansible-lint

---

#### Task 5.2: Create Common Role Documentation
**Priority:** 🟡 MEDIUM | **Effort:** 3 hours | **Depends On:** Task 5.1

**Todo List:**
- [ ] Create detailed roles/common/README.md
  - Role purpose and features
  - Requirements
  - Variable documentation
  - Example playbooks
  - Dependencies
  - Compatibility matrix
- [ ] Create docs/roles/common.md
  - Architecture overview
  - Design decisions
  - Security considerations
  - Best practices
- [ ] Create cheatsheets/common-role.md
  - Quick usage examples
  - Common scenarios
  - Troubleshooting
- [ ] Add role to main README.md
- [ ] Update CHANGELOG.md

**Acceptance Criteria:**
- Complete documentation
- Examples tested and working
- Cheatsheet created

---

### Week 6: Security Hardening Role

#### Task 6.1: Create Security Hardening Role
**Priority:** 🔴 HIGH | **Effort:** 16 hours

**Todo List:**
- [ ] Create role structure
  ```bash
  ansible-galaxy init roles/security_hardening
  ```
- [ ] Design role architecture with tasks:
  - [ ] tasks/main.yml - Orchestration
  - [ ] tasks/selinux.yml - SELinux configuration (RHEL)
  - [ ] tasks/apparmor.yml - AppArmor configuration (Debian)
  - [ ] tasks/firewall.yml - Firewall setup
  - [ ] tasks/fail2ban.yml - Fail2ban configuration
  - [ ] tasks/aide.yml - File integrity monitoring
  - [ ] tasks/auditd.yml - System auditing
  - [ ] tasks/kernel.yml - Kernel hardening (sysctl)
  - [ ] tasks/pam.yml - PAM configuration
  - [ ] tasks/passwords.yml - Password policies
  - [ ] tasks/network.yml - Network security
- [ ] Implement SELinux enforcement (RHEL family)
  - Enable SELinux
  - Set to enforcing mode
  - Install setroubleshoot
  - Configure custom policies (if needed)
- [ ] Implement AppArmor (Debian family)
  - Enable AppArmor
  - Install profiles
  - Enforce profiles
- [ ] Implement firewall configuration
  - Install firewalld (RHEL) or ufw (Debian)
  - Configure default deny policy
  - Allow SSH
  - Allow custom ports (configurable)
  - Enable firewall service
- [ ] Implement Fail2ban
  - Install fail2ban
  - Configure SSH jail
  - Configure ban time and retry limits
  - Email notifications (optional)
- [ ] Implement AIDE
  - Install AIDE
  - Initialize database
  - Configure check schedules
  - Email reports
- [ ] Implement auditd
  - Install auditd
  - Configure audit rules
  - Log rotation
  - Remote logging (optional)
- [ ] Implement kernel hardening
  - Create sysctl security settings
  - Disable IPv6 (optional)
  - Enable ASLR
  - Configure IP forwarding
  - SYN flood protection
- [ ] Implement PAM configuration
  - Password complexity
  - Account lockout
  - Login restrictions
- [ ] Implement password policies
  - Password aging
  - Password history
  - Minimum password length
- [ ] Implement network security
  - Disable unnecessary services
  - Configure TCP wrappers
  - Network parameter hardening
- [ ] Create templates for all configs
- [ ] Add CIS Benchmark compliance checks
- [ ] Create Molecule tests for all features
- [ ] Test on multiple distributions
- [ ] Create comprehensive documentation

**Acceptance Criteria:**
- Role implements CIS Benchmark controls
- Tests passing on Debian and RHEL
- No security vulnerabilities
- Complete documentation

---

### Week 7-8: Monitoring & Observability

#### Task 7.1: Create Prometheus Node Exporter Role
**Priority:** 🟡 MEDIUM | **Effort:** 8 hours

**Todo List:**
- [ ] Create role structure
  ```bash
  ansible-galaxy init roles/prometheus_node_exporter
  ```
- [ ] Implement installation
  - Download node_exporter binary
  - Verify checksum
  - Install to /usr/local/bin
  - Create systemd service
- [ ] Configure node_exporter
  - Set listen address
  - Configure collectors
  - TLS configuration (optional)
  - Basic auth (optional)
- [ ] Implement firewall rules
  - Open port 9100
- [ ] Create health check tasks
- [ ] Add monitoring validation
- [ ] Create Molecule tests
- [ ] Document configuration
- [ ] Create usage examples

**Acceptance Criteria:**
- Role functional and tested
- Metrics accessible
- Documentation complete

---

#### Task 7.2: Create Monitoring Client Role
**Priority:** 🟡 MEDIUM | **Effort:** 6 hours

**Todo List:**
- [ ] Create unified monitoring role
  ```bash
  ansible-galaxy init roles/monitoring_client
  ```
- [ ] Integrate with:
  - [ ] Prometheus node_exporter
  - [ ] Grafana agent (logs)
  - [ ] Optional: Custom exporters
- [ ] Create role dependencies in meta/main.yml
- [ ] Configure centralized logging
- [ ] Configure metrics collection
- [ ] Create monitoring playbook
- [ ] Document monitoring architecture
- [ ] Create monitoring dashboard examples

**Acceptance Criteria:**
- Unified monitoring setup
- All components integrated
- Documentation complete

---

## Phase 3: Secrets Management (Weeks 9-10)

### Week 9: Ansible Vault Implementation

#### Task 9.1: Configure Ansible Vault
**Priority:** 🔴 HIGH | **Effort:** 6 hours

**Todo List:**
- [ ] Create vault structure in secrets repository
  ```
  secrets/
  ├── production/
  │   ├── vault.yml (encrypted)
  │   └── vault_password.txt (gitignored)
  ├── staging/
  │   └── vault.yml
  └── development/
      └── vault.yml
  ```
- [ ] Create vault password management procedure
  - Document password generation
  - Secure storage guidelines
  - Rotation procedure
- [ ] Create vault templates
  - Database credentials
  - API keys
  - SSL certificates
  - SSH keys
- [ ] Encrypt existing secrets
  ```bash
  ansible-vault encrypt secrets/production/vault.yml
  ```
- [ ] Configure ansible.cfg for vault
  ```ini
  [defaults]
  vault_password_file = ~/.ansible/vault_password.txt
  ```
- [ ] Create vault management scripts
  - encrypt-secret.sh
  - decrypt-secret.sh
  - rotate-vault-password.sh
- [ ] Test vault operations
  - Encrypt/decrypt
  - Edit encrypted files
  - Use in playbooks
- [ ] Document vault procedures in docs/secrets-management.md
- [ ] Create cheatsheet for vault operations
- [ ] Update CLAUDE.md with vault requirements

**Acceptance Criteria:**
- Vault structure created
- Secrets encrypted
- Procedures documented
- Scripts tested and working

---

#### Task 9.2: Implement Vault Best Practices
**Priority:** 🟡 MEDIUM | **Effort:** 4 hours | **Depends On:** Task 9.1

**Todo List:**
- [ ] Implement vault password rotation
  - Create rotation procedure
  - Test re-keying process
  - Schedule regular rotations (90 days)
- [ ] Create vault usage patterns
  - Variable precedence with vault
  - Combining vault with group_vars
  - Environment-specific vaults
- [ ] Implement vault validation
  - Pre-commit hook for unencrypted secrets
  - CI/CD checks for exposed secrets
- [ ] Create vault backup procedures
  - Backup encrypted vaults
  - Secure password backups
  - Disaster recovery plan
- [ ] Document security considerations
- [ ] Create training materials
- [ ] Add vault examples to playbooks

**Acceptance Criteria:**
- Best practices documented
- Validation working
- Backup procedures in place

---

### Week 10: HashiCorp Vault (Optional)

#### Task 10.1: Evaluate HashiCorp Vault
**Priority:** 🟢 LOW | **Effort:** 8 hours

**Todo List:**
- [ ] Research HashiCorp Vault features
- [ ] Compare with Ansible Vault
- [ ] Evaluate deployment requirements
- [ ] Test Vault in development
  - Install Vault server
  - Configure authentication
  - Test secret storage
  - Test Ansible integration
- [ ] Document findings
- [ ] Create POC deployment
- [ ] Assess costs and benefits
- [ ] Make recommendation
- [ ] Document decision in ADR (Architecture Decision Record)

**Acceptance Criteria:**
- Evaluation complete
- POC tested
- Recommendation documented

---

## Phase 4: Application Deployment (Weeks 11-12)

### Week 11: Web Server Roles

#### Task 11.1: Create Nginx Role
**Priority:** 🟡 MEDIUM | **Effort:** 10 hours

**Todo List:**
- [ ] Create role structure
- [ ] Implement Nginx installation
  - Official repository setup
  - Package installation
  - Service management
- [ ] Configure Nginx
  - Main configuration
  - Virtual host templates
  - SSL/TLS configuration
  - Security headers
  - Rate limiting
- [ ] Implement SSL certificate management
  - Let's Encrypt integration
  - Certificate renewal
  - Self-signed certificates (dev)
- [ ] Configure logging
  - Access logs
  - Error logs
  - Log rotation
- [ ] Implement security hardening
  - Hide version
  - Disable unnecessary modules
  - Security headers (HSTS, CSP, etc.)
- [ ] Create health checks
- [ ] Add firewall rules
- [ ] Create Molecule tests
- [ ] Document configuration options
- [ ] Create usage examples

**Acceptance Criteria:**
- Role functional and secure
- SSL working
- Tests passing
- Documentation complete

---

### Week 12: Database Roles

#### Task 12.1: Create PostgreSQL Role
**Priority:** 🟡 MEDIUM | **Effort:** 12 hours

**Todo List:**
- [ ] Create role structure
- [ ] Implement PostgreSQL installation
  - Official repository
  - Version selection
  - Package installation
- [ ] Configure PostgreSQL
  - Main configuration (postgresql.conf)
  - Authentication (pg_hba.conf)
  - Connection limits
  - Memory settings
  - Logging configuration
- [ ] Implement database management
  - Create databases
  - Create users
  - Grant privileges
  - Password management (vault integration)
- [ ] Implement backup configuration
  - pg_dump automation
  - Backup schedules
  - Retention policy
  - Backup verification
- [ ] Implement replication (optional)
  - Primary/replica setup
  - Streaming replication
  - Failover procedures
- [ ] Security hardening
  - Network restrictions
  - SSL connections
  - Password encryption
- [ ] Add monitoring
  - PostgreSQL exporter
  - Query statistics
- [ ] Create Molecule tests
- [ ] Document administration procedures
- [ ] Create backup/restore guides

**Acceptance Criteria:**
- Role functional and secure
- Backup working
- Tests passing
- Documentation complete

---

## Tracking and Reporting

### Issue Creation
Each task above should be created as an issue in Gitea:

```bash
# Example using Gitea API
curl -X POST "https://git.mymx.me/api/v1/repos/ansible/infra-automation/issues" \
  -H "Content-Type: application/json" \
  -u "ansible@mymx.me:PASSWORD" \
  -d '{
    "title": "Task 1.1: Create Inventories Repository",
    "body": "[Task details from execution plan]",
    "labels": ["enhancement", "phase-1", "high-priority"]
  }'
```

### Progress Tracking

Create labels in Gitea:
- `phase-1`, `phase-2`, `phase-3`, `phase-4`
- `priority-high`, `priority-medium`, `priority-low`
- `status-todo`, `status-in-progress`, `status-blocked`, `status-done`
- `type-feature`, `type-bug`, `type-docs`, `type-test`

### Weekly Review Process

1. **Monday:** Week planning, assign tasks
2. **Wednesday:** Mid-week check-in, unblock issues
3. **Friday:** Week review, update roadmap
4. **Monthly:** Progress report, roadmap adjustment

### Reporting Template

```markdown
## Weekly Progress Report - Week X

### Completed Tasks
- [x] Task X.X: Description
- [x] Task X.X: Description

### In Progress Tasks
- [ ] Task X.X: Description (75% complete)
- [ ] Task X.X: Description (40% complete)

### Blocked Tasks
- [ ] Task X.X: Description
  - Blocker: [description]
  - Resolution plan: [plan]

### Next Week Plan
- [ ] Task X.X: Description
- [ ] Task X.X: Description

### Metrics
- Tasks completed: X
- Tests written: X
- Test coverage: X%
- Roles created: X
- Documentation pages: X

### Risks and Issues
- [Issue description and mitigation]
```

---

## Success Criteria Summary

### Phase 1 Success (Week 4)
- ✅ Inventories repository created and integrated
- ✅ CI/CD pipeline operational
- ✅ Molecule testing framework working
- ✅ deploy_linux_vm role has >80% test coverage
- ✅ All documentation updated

### Phase 2 Success (Week 8)
- ✅ Common role production-ready
- ✅ Security hardening role complete
- ✅ Monitoring client role functional
- ✅ All roles tested on Debian and RHEL
- ✅ Complete documentation for all roles

### Phase 3 Success (Week 10)
- ✅ Ansible Vault implemented
- ✅ All secrets encrypted
- ✅ Vault procedures documented
- ✅ HashiCorp Vault evaluated

### Phase 4 Success (Week 12)
- ✅ Nginx role production-ready
- ✅ PostgreSQL role complete
- ✅ Application deployment patterns established
- ✅ Backup procedures implemented

---

**Document Owner:** Ansible Infrastructure Team
**Last Updated:** 2025-11-10
**Next Review:** Weekly