Diese Betriebsdokumentation richtet sich an den ICT Server Support der Abyss Inc. Sie beschreibt das Deployment-Tool für EC2-Instanzen so, dass das System ohne langwierige Einführung eigenständig betrieben, gewartet und im Fehlerfall entstört werden kann. Sie ist Teil des öffentlichen Git-Repositories und damit für das gesamte Support-Team an einem zentralen Ort zugänglich.

Es wird durchgehend eine einheitliche Terminologie verwendet und bewusst auf implizites Vorwissen verzichtet. Wo AWS-spezifische Begriffe nötig sind, werden sie kurz erläutert.

Systemübersicht & Architektur

Das Produkt ist ein einzelnes, portables Bash-Skript (source/main.sh), das über die AWS CLI mit der AWS-API kommuniziert und daraus EC2-Instanzen provisioniert. Die Basiskonfiguration der Instanz (Pakete, User, SSH-Keys) wird aus dem Template source/userdata.yml.template über Cloud-Init ausgerollt.

graph LR
    A[Supporter / Konsole] -->|interaktive Eingabe| B[main.sh]
    B -->|liest & befüllt| C[userdata.yml.template]
    B -->|AWS CLI / HTTPS 443| D[AWS EC2 API]
    D -->|provisioniert| E[EC2-Instanz]
    C -->|Cloud-Init Userdata| E
    A -.->|SSH / Port 22| E

Komponenten & Abhängigkeiten:

Komponente	Rolle	Schnittstelle / Port
main.sh	Steuert den gesamten Deployment-Ablauf	lokale Ausführung (Bash)
AWS CLI	Übermittelt die Requests an AWS	HTTPS / 443 (ausgehend)
AWS EC2 API	Erstellt und verwaltet die Instanzen	HTTPS / 443
userdata.yml.template	Liefert die Cloud-Init-Basiskonfiguration	Datei-Referenz (file://)
EC2-Instanz	Das deployte Zielsystem	SSH / 22 (Zugriff via abyss-admin)

Voraussetzungen:

• Installierte AWS CLI (aws --version)
• Gültige AWS-Credentials (aws configure), prüfbar via aws sts get-caller-identity
• Ausgehender Zugriff auf die AWS-API (Port 443)

Daily Operations (Normalbetrieb)

Standard-Deployment (Prod / Int / Dev)

Das Skript wird interaktiv aus dem Ordner source/ gestartet:

./main.sh

Der Ablauf ist für alle Umgebungen identisch; einzig die Auswahl der Umgebung unterscheidet sich:

1. Umgebung wählen: Im Auswahlmenü Produktion (Prod), Integration (Int) oder Entwicklung (Dev) auswählen. Damit werden AMI-ID, Instance-Type, Subnet und Security Group automatisch aus den Standards (/.admin/Standards_AbyssInc.md) vorbelegt.
2. Werte bestätigen: Die vorgeschlagenen Standardwerte können per Enter übernommen oder bei Bedarf überschrieben werden.
3. Instance-Type wählen: Aus der nummerierten Liste auswählen (Standard der Umgebung ist bereits angegeben).
4. Hostname (optional) setzen, dann läuft das Deployment durch.
5. Zusammenfassung prüfen: Am Ende werden Instance-ID, Public IP und ein Direktlink zur AWS-Konsole ausgegeben.

Für die Umgebung Custom werden keine Defaults gesetzt; alle AWS-IDs müssen manuell eingegeben werden (nur für Server mit Ausnahmebewilligung).

Parameter vorab prüfen (Dry-Run)

Vor einem echten Deployment können die Parameter ohne Kostenfolge gegen die AWS-API getestet werden:

./main.sh --dry-run

Erscheint die Meldung “Die Parameter sind gültig”, würde ein echtes Deployment funktionieren.

Logfiles

Ort	Inhalt
Konsolen-Ausgabe von main.sh	Vollständiger Ablauf inkl. Fehlermeldungen. Für eine Persistenz empfiehlt sich ./main.sh \| tee deployment.log.
/var/log/cloud-init.log (auf der Instanz)	Ablauf von Cloud-Init beim ersten Boot
/var/log/cloud-init-output.log (auf der Instanz)	Konsolen-Output der Cloud-Init-Schritte (Paketinstallation etc.)
AWS CloudTrail	API-seitige Nachvollziehbarkeit der run-instances-Aufrufe

Troubleshooting

Die folgenden drei Szenarien decken die häufigsten Fehlerbilder ab. Lässt sich ein Problem damit nicht lösen, gilt der Eskalationspfad weiter unten.

Runbook 1 – “AWS Credentials nicht erkannt oder ungültig”

Symptom: Das Skript bricht direkt nach dem Start mit dieser Meldung ab.

Lösung:

1. Credentials prüfen: aws sts get-caller-identity
2. Sind keine/abgelaufene Credentials hinterlegt: aws configure ausführen und Access Key, Secret sowie Region setzen.
3. Erneut starten.

Runbook 2 – “Das Deployment wurde von AWS abgelehnt”

Symptom: Der Request an AWS schlägt fehl, die Original-Fehlermeldung von AWS wird angezeigt.

Lösung:

1. Region, AMI-ID, Subnet-ID und Security-Group-ID gegen die Standards (/.admin/Standards_AbyssInc.md) abgleichen – Subnet und Security Group müssen zur gleichen Umgebung gehören.
2. Berechtigungen des verwendeten AWS-Users prüfen (IAM).
3. Im Zweifel zuerst mit --dry-run testen, um die Parameter isoliert zu validieren.

Runbook 3 – “Instanz läuft, ist aber per SSH nicht erreichbar”

Symptom: Das Deployment war erfolgreich (Instance-ID & IP vorhanden), eine SSH-Verbindung auf Port 22 kommt jedoch nicht zustande.

Lösung:

1. Prüfen, ob die korrekte umgebungsspezifische Security Group gesetzt wurde – die AWS-Default-Security-Group blockiert eingehenden Verkehr und darf nicht verwendet werden.
2. Sicherstellen, dass Port 22 in der Security Group für die Quell-IP freigegeben ist.
3. Kurz warten: Direkt nach dem Start ist die Instanz teils noch im Boot-/Cloud-Init-Vorgang.

Zuständigkeiten & Eskalation

Stufe	Zuständig	Wofür
1st Level	ICT Server Support	Durchführen der Deployments, Abarbeiten der Runbooks
2nd Level	Fachexperte Infrastruktur (A. Dörzbach)	AWS-/Infrastruktur-Themen (Security Groups, Subnets, IAM)
3rd Level	Projektleitung / Developer (R. Schmocker)	Fehler im Skript selbst, Anpassungen am Tool

Die Kommunikation und Eskalation erfolgt grundsätzlich über den MS-Teams-Kanal. Lässt sich ein Vorfall mit den obigen Runbooks nicht lösen, wird er an die nächsthöhere Stufe übergeben.