michaelschiemer/deployment/ansible/playbooks/README.md

Ansible Playbooks - Übersicht

Verfügbare Playbooks

Hinweis: Die meisten Playbooks wurden in wiederverwendbare Roles refactored. Die Playbooks sind jetzt Wrapper, die die entsprechenden Role-Tasks aufrufen. Dies verbessert Wiederverwendbarkeit, Wartbarkeit und folgt Ansible Best Practices.

Infrastructure Setup

• setup-infrastructure.yml - Deployed alle Stacks (Traefik, PostgreSQL, Redis, Registry, Gitea, Monitoring, Production)
• setup-production-secrets.yml - Deployed Secrets zu Production
• setup-ssl-certificates.yml - SSL Certificate Setup (Wrapper für traefik Role, tasks_from: ssl)
• setup-wireguard-host.yml - WireGuard VPN Setup
• sync-stacks.yml - Synchronisiert Stack-Konfigurationen zum Server

Deployment & Updates

• rollback.yml - Rollback zu vorheriger Version
• backup.yml - Erstellt Backups von PostgreSQL, Application Data, Gitea, Registry
• deploy-image.yml - Docker Image Deployment (wird von CI/CD Workflows verwendet)

Traefik Management (Role-basiert)

• restart-traefik.yml - Restart Traefik Container (Wrapper für traefik Role, tasks_from: restart)
• recreate-traefik.yml - Recreate Traefik Container (Wrapper für traefik Role, tasks_from: restart mit traefik_restart_action: recreate)
• deploy-traefik-config.yml - Deploy Traefik Configuration Files (Wrapper für traefik Role, tasks_from: config)
• check-traefik-acme-logs.yml - Check Traefik ACME Challenge Logs (Wrapper für traefik Role, tasks_from: logs)
• setup-ssl-certificates.yml - Setup Let's Encrypt SSL Certificates (Wrapper für traefik Role, tasks_from: ssl)

Gitea Management (Role-basiert)

• check-and-restart-gitea.yml - Check and Restart Gitea if Unhealthy (Wrapper für gitea Role, tasks_from: restart)
• fix-gitea-runner-config.yml - Fix Gitea Runner Configuration (Wrapper für gitea Role, tasks_from: runner mit gitea_runner_action: fix)
• register-gitea-runner.yml - Register Gitea Runner (Wrapper für gitea Role, tasks_from: runner mit gitea_runner_action: register)
• update-gitea-config.yml - Update Gitea Configuration (Wrapper für gitea Role, tasks_from: config)
• setup-gitea-initial-config.yml - Setup Gitea Initial Configuration (Wrapper für gitea Role, tasks_from: setup)
• setup-gitea-repository.yml - Setup Gitea Repository (Wrapper für gitea Role, tasks_from: repository)

Application Deployment (Role-basiert)

• deploy-application-code.yml - Deploy Application Code via Git (Wrapper für application Role, tasks_from: deploy_code mit application_deployment_method: git)
• sync-application-code.yml - Synchronize Application Code via Rsync (Wrapper für application Role, tasks_from: deploy_code mit application_deployment_method: rsync)
• install-composer-dependencies.yml - Install Composer Dependencies (Wrapper für application Role, tasks_from: composer)

Application Container Management (Role-basiert)

• check-container-status.yml - Check Container Status (Wrapper für application Role, tasks_from: health_check)
• check-container-logs.yml - Check Container Logs (Wrapper für application Role, tasks_from: logs)
• check-worker-logs.yml - Check Worker and Scheduler Logs (Wrapper für application Role, tasks_from: logs mit application_logs_check_vendor: true)
• check-final-status.yml - Check Final Container Status (Wrapper für application Role, tasks_from: health_check mit application_health_check_final: true)
• fix-container-issues.yml - Fix Container Issues (Wrapper für application Role, tasks_from: containers mit application_container_action: fix)
• fix-web-container.yml - Fix Web Container Permissions (Wrapper für application Role, tasks_from: containers mit application_container_action: fix-web)
• recreate-containers-with-env.yml - Recreate Containers with Environment Variables (Wrapper für application Role, tasks_from: containers mit application_container_action: recreate-with-env)
• sync-and-recreate-containers.yml - Sync and Recreate Containers (Wrapper für application Role, tasks_from: containers mit application_container_action: sync-recreate)

Maintenance

• cleanup-all-containers.yml - Stoppt und entfernt alle Container, bereinigt Netzwerke und Volumes (für vollständigen Server-Reset)
• system-maintenance.yml - System-Updates, Unattended-Upgrades, Docker-Pruning
• troubleshoot.yml - Unified Troubleshooting mit Tags

WireGuard

• generate-wireguard-client.yml - Generiert WireGuard Client-Config
• wireguard-routing.yml - Konfiguriert WireGuard Routing

Initial Deployment

• build-initial-image.yml - Build und Push des initialen Docker Images (für erstes Deployment)

CI/CD & Development

• setup-gitea-runner-ci.yml - Gitea Runner CI Setup
• install-docker.yml - Docker Installation auf Server

Entfernte/Legacy Playbooks

Die folgenden Playbooks wurden entfernt, da sie nicht mehr benötigt werden:

• build-and-push.yml - Wird durch CI/CD Pipeline ersetzt
• remove-framework-production-stack.yml - Temporäres Playbook
• remove-temporary-grafana-ip.yml - Temporäres Playbook

Verwendung

Standard-Verwendung

cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/<playbook>.yml --vault-password-file secrets/.vault_pass

Role-basierte Playbooks

Die meisten Playbooks sind jetzt Wrapper, die Roles verwenden. Die Funktionalität bleibt gleich, aber die Implementierung ist jetzt in wiederverwendbaren Roles organisiert:

Beispiel: Traefik Restart

# Alte Methode (funktioniert noch, ruft jetzt aber die Role auf):
ansible-playbook -i inventory/production.yml playbooks/restart-traefik.yml --vault-password-file secrets/.vault_pass

# Direkte Role-Verwendung (alternative Methode):
ansible-playbook -i inventory/production.yml -e "traefik_restart_action=restart" -e "traefik_show_status=true" playbooks/restart-traefik.yml

Beispiel: Gitea Runner Fix

ansible-playbook -i inventory/production.yml playbooks/fix-gitea-runner-config.yml --vault-password-file secrets/.vault_pass

Beispiel: Application Code Deployment

# Git-basiert (Standard):
ansible-playbook -i inventory/production.yml playbooks/deploy-application-code.yml \
  -e "deployment_environment=staging" \
  -e "git_branch=staging" \
  --vault-password-file secrets/.vault_pass

# Rsync-basiert (für Initial Deployment):
ansible-playbook -i inventory/production.yml playbooks/sync-application-code.yml \
  --vault-password-file secrets/.vault_pass

Tags verwenden

Viele Playbooks unterstützen Tags für selektive Ausführung:

# Nur Traefik-bezogene Tasks:
ansible-playbook -i inventory/production.yml playbooks/restart-traefik.yml --tags traefik,restart

# Nur Gitea-bezogene Tasks:
ansible-playbook -i inventory/production.yml playbooks/check-and-restart-gitea.yml --tags gitea,restart

# Nur Application-bezogene Tasks:
ansible-playbook -i inventory/production.yml playbooks/deploy-application-code.yml --tags application,deploy

Role-Struktur

Die Playbooks verwenden jetzt folgende Roles:

traefik Role

• Tasks: restart, config, logs, ssl
• Location: roles/traefik/tasks/
• Defaults: roles/traefik/defaults/main.yml

gitea Role

• Tasks: restart, runner, config, setup, repository
• Location: roles/gitea/tasks/
• Defaults: roles/gitea/defaults/main.yml

application Role

• Tasks: deploy_code, composer, containers, health_check, logs, deploy
• Location: roles/application/tasks/
• Defaults: roles/application/defaults/main.yml

Vorteile der Role-basierten Struktur

1. Wiederverwendbarkeit: Tasks können in mehreren Playbooks genutzt werden
2. Wartbarkeit: Änderungen zentral in Roles
3. Testbarkeit: Roles isoliert testbar
4. Klarheit: Klare Struktur nach Komponenten
5. Best Practices: Folgt Ansible-Empfehlungen