AFC-Demo/terraform/QUICKSTART.md

🚀 Quickstart Guide - Laravel auf Azure AKS

Diese Anleitung führt dich in ~30 Minuten durch das komplette Deployment deiner Laravel-Anwendung auf Azure Kubernetes Service.

✅ Voraussetzungen Check

# Prüfe ob alle Tools installiert sind
terraform version  # >= 1.9.0
az version        # >= 2.0
kubectl version   # >= 1.28
docker version    # >= 20.10
php -v            # >= 8.2

📝 Schritt-für-Schritt Anleitung

1️⃣ Azure Login (2 Min)

# Login
az login

# Subscription setzen
az account set --subscription "77677a80-2dea-493d-9867-f1c961b80fb3"

# Verify
az account show

2️⃣ Container Registry Setup (5 Min)

# ACR erstellen (wenn nicht vorhanden)
az acr create \
  --resource-group trusted_ai_demo_rg \
  --name mylaravelregistry \
  --sku Basic \
  --location germanywestcentral

# AKS Zugriff auf ACR geben
az aks update \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --attach-acr mylaravelregistry

# Login
az acr login --name mylaravelregistry

3️⃣ Docker Image Build & Push (5 Min)

# Zum Projekt-Root wechseln
cd /Users/sebastianfrohlich/Herd/frontend

# Image bauen
docker build -t mylaravelregistry.azurecr.io/laravel-app:v1.0.0 .

# Image pushen
docker push mylaravelregistry.azurecr.io/laravel-app:v1.0.0

4️⃣ Laravel APP_KEY generieren (1 Min)

# Im Projekt-Root
php artisan key:generate --show

# Beispiel Output: base64:abcdefgh12345...
# Kopiere diesen Wert für den nächsten Schritt

5️⃣ Terraform Konfiguration (5 Min)

# Zu Terraform wechseln
cd terraform

# Konfiguration kopieren
cp terraform.tfvars.example terraform.tfvars

# Bearbeiten
nano terraform.tfvars

Wichtige Werte in terraform.tfvars ändern:

# Docker Image (von Schritt 3)
docker_image = "mylaravelregistry.azurecr.io/laravel-app:v1.0.0"

# Laravel Key (von Schritt 4)
app_key = "base64:abcdefgh12345..."

# PostgreSQL Password (sicheres Passwort wählen!)
postgresql_admin_password = "YourSecurePassword123!"

# Email für Alerts
alert_email_address = "your-email@example.com"

6️⃣ Deployment ausführen (10 Min)

# Automatisches Deployment mit Script
./scripts/deploy.sh

Das Script führt automatisch aus:

• ✅ Prerequisite-Check
• ✅ Terraform init
• ✅ Terraform validate
• ✅ Terraform plan
• ✅ Terraform apply (nach Bestätigung)
• ✅ kubectl konfigurieren
• ✅ Pod-Status prüfen

Oder manuell:

# Init
terraform init

# Plan
terraform plan -out=tfplan

# Apply
terraform apply tfplan

# kubectl konfigurieren
az aks get-credentials \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --overwrite-existing

7️⃣ Datenbank wiederherstellen (5 Min)

# Automatisches Restore-Script
./scripts/restore-db.sh

# Script fragt:
# - Welches Backup-File? (z.B. backup_backend_20251203_101741.dump)
# - Bestätigung: yes
# - Zeigt Fortschritt und Logs

Oder in terraform.tfvars setzen und nochmal apply:

db_restore_enabled  = true
db_backup_file_path = "../backups/backup_backend_20251203_101741.dump"

terraform apply

8️⃣ Anwendung testen (2 Min)

# LoadBalancer IP abrufen
kubectl get svc ingress-nginx-controller -n ingress-nginx

# Oder über Terraform Output
terraform output app_url

# Example Output:
# app_url = "http://20.79.123.456"

🎉 Öffne die URL im Browser!

9️⃣ Status prüfen

# Pods prüfen
kubectl get pods -n laravel-app

# Services prüfen
kubectl get svc -n laravel-app

# Ingress prüfen
kubectl get ingress -n laravel-app

# Logs anzeigen
kubectl logs -n laravel-app -l app=laravel-app -f

# Database restore job prüfen (wenn aktiviert)
kubectl get jobs -n laravel-app
kubectl logs -n laravel-app -l job-type=database-restore

🔧 Häufige Probleme

Problem: Pods starten nicht (ImagePullBackOff)

# Prüfe ob ACR-Integration funktioniert
az aks check-acr \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --acr mylaravelregistry.azurecr.io

# Fix: ACR Integration neu setzen
az aks update \
  --resource-group trusted_ai_demo_rg \
  --name trai_k8s_cluster \
  --attach-acr mylaravelregistry

Problem: LoadBalancer IP bleibt "Pending"

# Prüfe Service Events
kubectl describe svc ingress-nginx-controller -n ingress-nginx

# Warte 5-10 Minuten - Azure braucht Zeit für LoadBalancer Setup
kubectl get svc -n ingress-nginx -w

Problem: Database Connection Failed

# Prüfe PostgreSQL Firewall Rules
az postgres flexible-server firewall-rule list \
  --resource-group trusted_ai_demo_rg \
  --name <server-name>

# Prüfe Secrets
kubectl get secret laravel-app-db-credentials -n laravel-app -o yaml | grep DB_

Problem: 502 Bad Gateway

# Prüfe ob Pods ready sind
kubectl get pods -n laravel-app

# Prüfe Pod Logs
kubectl logs -n laravel-app <pod-name>

# Teste direkt zum Service
kubectl port-forward -n laravel-app svc/laravel-app 8080:80
# Dann: http://localhost:8080

📊 Nützliche Befehle

Status-Übersicht

# Alles auf einen Blick
kubectl get all -n laravel-app
kubectl get all -n ingress-nginx

# Terraform Outputs
terraform output

Logs anzeigen

# Application Logs (alle Pods)
kubectl logs -n laravel-app -l app=laravel-app -f

# Bestimmter Pod
kubectl logs -n laravel-app <pod-name> -f

# Ingress Controller Logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller -f

Scale Up/Down

# Mehr Replicas
kubectl scale deployment/laravel-app --replicas=3 -n laravel-app

# Prüfen
kubectl get pods -n laravel-app

Shell in Pod

# Shell öffnen
kubectl exec -it -n laravel-app <pod-name> -- /bin/sh

# Laravel Artisan in Pod ausführen
kubectl exec -it -n laravel-app <pod-name> -- php artisan migrate:status
kubectl exec -it -n laravel-app <pod-name> -- php artisan route:list

Port-Forward für lokalen Zugriff

# App direkt aufrufen (ohne LoadBalancer)
kubectl port-forward -n laravel-app svc/laravel-app 8080:80

# Dann: http://localhost:8080

🔄 Updates deployen

Neue Version deployen

# 1. Code ändern
# 2. Neues Image bauen
docker build -t mylaravelregistry.azurecr.io/laravel-app:v1.0.1 .
docker push mylaravelregistry.azurecr.io/laravel-app:v1.0.1

# 3. Deployment updaten (schnell)
kubectl set image deployment/laravel-app \
  laravel-app=mylaravelregistry.azurecr.io/laravel-app:v1.0.1 \
  -n laravel-app

# Rollout Status prüfen
kubectl rollout status deployment/laravel-app -n laravel-app

Rollback

# Zur vorherigen Version zurück
kubectl rollout undo deployment/laravel-app -n laravel-app

🧹 Cleanup

Nur App löschen (DB behalten)

terraform destroy -target=kubernetes_deployment.app
terraform destroy -target=kubernetes_service.app

Alles löschen

terraform destroy

📚 Weitere Informationen

• Ausführliche Dokumentation: README.md
• Terraform Outputs: terraform output
• Azure Portal: https://portal.azure.com

🆘 Hilfe benötigt?

# Terraform Outputs anzeigen
terraform output deployment_instructions

# Kubernetes Events prüfen
kubectl get events -n laravel-app --sort-by='.lastTimestamp'

# Resource Status
kubectl describe deployment laravel-app -n laravel-app
kubectl describe svc laravel-app -n laravel-app

✨ Next Steps

Nach erfolgreichem Deployment:

1. Domain konfigurieren (optional):

   # In terraform.tfvars
   ingress_host = "app.yourdomain.com"
   ssl_enabled = true
   ssl_issuer_email = "admin@yourdomain.com"
   

   terraform apply
   

2. Monitoring einrichten: Prüfe Azure Monitor in Azure Portal

3. CI/CD Pipeline: Erstelle GitHub Actions oder Azure DevOps Pipeline

4. Backups testen: Teste Restore-Prozess

5. Security Hardening:

   • VNet Integration für PostgreSQL
   • Private Endpoints
   • RBAC konfigurieren

---

Deployment Time: ~30 Minuten Kosten: ~50-100€/Monat (abhängig von Ressourcen) Scaling: Horizontal (mehr Pods) & Vertikal (größere VMs)