axion1337.chat-gitops/.devcontainer

🐳 DevContainer für ESS Community GitOps

Dieses DevContainer-Setup ermöglicht dir, auf macOS, Windows und Linux einheitlich zu entwickeln.

🚀 Schnelstart

VSCode mit Remote Containers Extension

1. VSCode Extension installieren:

   • Öffne VSCode → Extensions → Suche nach Dev Containers (Microsoft)
   • Installiere sie

2. GitOps Verzeichnis öffnen:

   cd "april mit Ansible/prod/gitops"
   code .
   

3. DevContainer starten:

   • Klick auf >< Symbol unten links in VSCode
   • Wähle Reopen in Container
   • Warte, bis das Image gebaut wurde (~3-5 Min beim ersten Mal)

Alternative: Docker + CLI

docker build -t ess-gitops .devcontainer
docker run -it --rm \
  -v ~/.kube:/home/vscode/.kube \
  -v ~/.ssh:/home/vscode/.ssh \
  -v ~/.age:/home/vscode/.age \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ess-gitops

📦 Enthaltene Tools

• kubectl - Kubernetes CLI
• flux - FluxCD GitOps Controller CLI
• helm - Kubernetes Package Manager
• sops - Secret Operations (Verschlüsselung)
• age - Modern File Encryption
• docker - Container CLI (über Host-Socket)
• git - Versionskontrolle
• jq/yq - JSON/YAML Processing
• zsh + oh-my-zsh - Shell mit Plugins

🔐 Wichtige Verzeichnis-Binds

Der Container mountet automatisch:

Host	Container	Zweck
~/.kube	/home/vscode/.kube	Kubernetes Config
~/.ssh	/home/vscode/.ssh	SSH Keys
~/.age	/home/vscode/.age	Age Encryption Keys
/var/run/docker.sock	/var/run/docker.sock	Docker Daemon (für docker Befehle)

⚙️ Kubeconfig Einrichten

1. Host-Machine (z.B. macOS):

   # Stelle sicher, dass ~/.kube/config existiert und den richtigen Cluster enthält
   kubectl get nodes
   

2. Im Container:

   kubectl get nodes  # Sollte jetzt auch dein Cluster zeigen
   kubectl config current-context
   

🔐 SOPS + Age Setup

Damit du Secrets bearbeiten kannst, brauchst du den privaten age-Key. Dieser ist in .sops.yaml konfiguriert.

Schritt 1: Age-Key bereitstellen

# Host-Machine: Key-Datei erstellen
mkdir -p ~/.age
# Füge deinen privaten Key ein (Format: "age-secret-key-...")
echo "age-secret-key-xxx..." > ~/.age/keys.txt
chmod 600 ~/.age/keys.txt

Schritt 2: Im Container konfigurieren

Der Container mounted ~/.age automatisch. Setze die Umgebungsvariable:

# Im Container-Terminal (SOPS_AGE_KEY_FILE ist bereits automatisch gesetzt!)
# Jetzt kannst du Secrets bearbeiten (wird transparent ver-/entschlüsselt):
sops apps/production/custom-configs/mas-secrets.sops.yaml

Schritt 3: VSCode Integration (optional)

Um die Umgebungsvariable beim Start zu setzen, nutze die .devcontainer/devcontainer.json:

"remoteEnv": {
  "KUBECONFIG": "/home/vscode/.kube/config",
  "SOPS_AGE_KEY_FILE": "/home/vscode/.age/keys.txt"
}

Wie es funktioniert

• .sops.yaml definiert, dass Secrets mit age verschlüsselt werden
• Beim Öffnen mit sops <datei> wird die Datei entschlüsselt → du editierst den plaintext in deinem Editor
• Beim Speichern wird alles wieder automatisch verschlüsselt
• Wichtig: Niemals den plaintext-Buffer commiten!

📝 Nach Container-Start: Git Hooks Installieren

Wichtig für die ConfigMap Auto-Sync (verhindert Merge-Konflikte):

./scripts/install-hooks.sh

Mehr Details: docs/ops-configmap-sync.md

📝 Nützliche Befehle

# Status des Deployments
kubectl get pods -n matrix
flux get helmreleases -A

# Secrets bearbeiten (mit verschlüsselung)
sops apps/production/custom-configs/mas-secrets.sops.yaml

# FluxCD Sync erzwingen
flux reconcile kustomization production-apps --with-source

# Zertifikate debuggen
kubectl get certificate -n matrix
kubectl describe certificate matrix-ingress -n matrix

# HelmRelease Status prüfen
flux describe helmrelease matrix-stack -n matrix

🛠️ Anpassungen für Windows/WSL2

Falls du Windows nutzt:

1. Docker Desktop installieren (mit WSL2 Backend)
2. VSCode mit WSL Extension öffnen
3. Im WSL Terminal:

   cd /mnt/c/path/to/projekt
   code .
   

4. Dann Dev Containers: Reopen in Container

Das funktioniert seamless, weil Docker Desktop unter WSL2 läuft.

🔧 Troubleshooting

Problem: SOPS_AGE_KEY_FILE not found

Lösung: Key muss in ~/.age/keys.txt auf der Host-Machine sein:

# Host
mkdir -p ~/.age
echo "your-age-private-key" > ~/.age/keys.txt

Der Container mountet ~/.age automatisch → sollte dann funktionieren.

Problem: kubectl: connection refused

Lösung: ~/.kube/config muss auf Host vorhanden sein:

# Host
kubectl get nodes  # Test, ob Zugriff existiert
# Dann Container neustarten

Problem: HelmChart is not ready: stat ... no such file or directory

Siehe README.md → Issue 1. Kontrolliere:

• HelmRepository nutzt type: oci
• URL ist oci://ghcr.io/element-hq/ess-helm

Problem: values don't meet the specifications of the schema

Siehe README.md → Issue 2. Häufige Fehler:

• tls: darf nicht im ingress: Block sein
• serverName muss auf Root-Ebene der values stehen
• Komponenten-Namen: camelCase (z.B. elementWeb, matrixAuthenticationService)

Problem: Let's Encrypt 403 Order's status is processing

Siehe README.md → Issue 3. Kurz:

• wellKnownDelegation: enabled: false setzen
• Oder .well-known/matrix/server manuell auf elementWeb weiterleiten

📚 Weitere Ressourcen

• Dev Containers Docs
• FluxCD Dokumentation
• SOPS Anleitung
• Projekt-README: README.md (Architektur, Issues, Best Practices)
• Setup-Docs: docs/setup/
• Install-Guide: docs/install.md