Coriolis/README.MD

ANLEITUNG: Installation des STACKIT Provider Plugins

Dies ist eine Schritt-für-Schritt-Anleitung, um Ihr benutzerdefiniertes STACKIT v2 Provider-Plugin auf einer laufenden Coriolis Appliance zu installieren.

Schritt 1: Code-Struktur vorbereiten

Stellen Sie sicher, dass Ihre Dateien exakt diese Struktur aufweisen. Sie benötigen einen Projekt-Ordner (z.B. `coriolis_stackit_plugin`) und darin das eigentliche Python-Paket.

```
coriolis_stackit_plugin/
├── setup.py
└── coriolis_stackit/
    ├── __init__.py
    └── provider.py
```

* `setup.py`: Registriert den Provider bei Coriolis.
* `coriolis_stackit/provider.py`: Enthält die `StackitProvider`-Klasse inkl. aller Worker- und Datentransfer-Funktionen.

> **Abhängigkeiten:**  
> Das Plugin benötigt mindestens `requests>=2.20.0` und `boto3>=1.24.0` (siehe `setup.py`), damit sowohl die STACKIT REST-APIs als auch optionale S3-Validierungen genutzt werden können.

Schritt 2: Plugin-Code auf die Appliance kopieren

1.  **Verbinden:** Stellen Sie per SSH eine Verbindung zu Ihrer Coriolis Appliance her.
    ```bash
    ssh [ihr_benutzer]@[ip_ihrer_coriolis_appliance]
    ```
2.  **Code kopieren:** Kopieren Sie den gesamten Ordner `coriolis_stackit_plugin` (z.B. mit `scp` oder `rsync`) in ein temporäres Verzeichnis auf der Appliance, z.B. `/tmp/`.

    *Beispiel mit `scp` (von Ihrem lokalen Rechner aus):*
    ```bash
    scp -r /pfad/zu/ihrem/coriolis_stackit_plugin [ihr_benutzer]@[ip_ihrer_coriolis_appliance]:/tmp/
    ```

Schritt 3: Plugin in Coriolis installieren

1.  **In das Verzeichnis wechseln:** 

Gehen Sie auf der Appliance in das Verzeichnis, das Sie gerade kopiert haben.
    ```bash
    cd /tmp/coriolis_stackit_plugin
    ```
2.  **Python-Umgebung aktivieren:** 

Coriolis verwendet eine eigene virtuelle Python-Umgebung (virtualenv). Der Pfad kann variieren, aber er ist oft unter `/opt/coriolis/` oder `/usr/share/coriolis/`. Sie müssen diese Umgebung aktivieren.
    *(Suchen Sie nach `activate` in `/opt/coriolis/` oder `/usr/share/coriolis/`)*

    *Beispiel:*
    ```bash
    source /opt/coriolis/coriolis-env/bin/activate
    ```
    *(Ihr Konsolen-Prompt sollte sich jetzt ändern und `(coriolis-env)` anzeigen)*

3.  **Plugin installieren:** 

Installieren Sie Ihr Plugin mit `pip` im "editable" Modus. Dies ist der wichtigste Befehl.
    ```bash
    pip install -e .
    ```
    *(Das `-e .` bedeutet, dass das Plugin von diesem Verzeichnis aus installiert wird. Pip liest die `setup.py` und führt die Installation durch.)*

4.  **Dienste neu starten:** 

Damit Coriolis das neu installierte Plugin erkennt, müssen Sie die Coriolis-Dienste neu starten.
    ```bash
    sudo systemctl restart coriolis-api
    sudo systemctl restart coriolis-worker
    ```
    *(Die Dienstnamen können leicht variieren, z.B. `coriolis-conductor`)*

Schritt 4: Konfiguration des Endpoints (in der Coriolis UI)

Nachdem das Plugin installiert und der Dienst neu gestartet wurde, ist Ihr Provider "stackit_v2" für Coriolis bekannt.

1. .endpoint-Datei erstellen:

   Erstellen Sie auf Ihrem lokalen Rechner eine Datei, z.B. stackit_v2.endpoint.

2. Inhalt einfügen:

   Fügen Sie den folgenden JSON-Inhalt ein und ersetzen Sie die Platzhalter.

   Sie finden eine ausführliche Vorlage in stackit_v2.endpoint. Die wichtigsten Felder sind:

   • project_id, region, api_url, object_storage_api_url, auth_url
   • Object-Storage-Einstellungen (object_storage_s3_endpoint_url, migration_bucket_name)
   • Worker-VM-Parameter (worker_image_id, worker_flavor_id, worker_network_id, worker_availability_zone, worker_security_group_ids, worker_keypair_name)
   • Run-Command Zugang (run_command_api_url, optional eigenes run_command_template, Timeout)
   • Optional: os_morphing_assets – Verweise auf S3-Objekte, die Skripte bzw. Treiber-Pakete für Linux- und Windows-OS-Morphing enthalten (siehe unten).
   • Optionale Worker-Metadaten und Steuerflags (worker_user, worker_auto_cleanup, worker_boot_volume_size)

   Diese Angaben werden von den Methoden export_snapshot_to_url() und create_volume_from_url() genutzt, um automatisch Buckets anzulegen, temporäre Access Keys zu erzeugen, Worker-VMs zu starten und anschließend über die STACKIT Run-Command API die eigentlichen Datenbefehle (Upload/Download) auf der Worker-VM auszuführen. Stellen Sie sicher, dass Ihr Worker-Image den STACKIT Agent aktiviert hat, damit Run-Command die Shell-Skripte ausführen darf.

OS-Morphing:
Zusätzlich stehen prepare_instance_for_os_morphing() und inject_drivers() zur Verfügung. Beide Funktionen erstellen ebenfalls eine Worker-VM, hängen das Ziel-Volume an und führen die Morphing-Schritte direkt auf dem Block-Device aus.

• Für Linux existiert eine eingebaute Standard-Logik (DHCP, Cloud-Init, VirtIO-Module). Optional kann über os_morphing_assets.linux.script ein eigenes Skript bereitgestellt werden; dieses wird mit den Umgebungsvariablen CORIOLIS_DEVICE und CORIOLIS_JOB_JSON auf dem Worker ausgeführt.
• Für Windows wird zwingend ein Skript (z.B. Shell/Python) über os_morphing_assets.windows.script erwartet, das die notwendigen Registry-/Treiber-Anpassungen vornimmt (z.B. durch Nutzung von ntfs-3g, chntpw, virtio-Treiberpaketen). Das Skript wird analog mit CORIOLIS_DEVICE und CORIOLIS_JOB_JSON aufgerufen und kann benötigte Pakete ebenfalls aus S3 laden.

* **WICHTIG:** 

Der `"provider"`-Name (`"stackit_v2"`) muss exakt mit dem Namen übereinstimmen, den Sie in der `setup.py` unter `entry_points` definiert haben.

3. In Coriolis hochladen:

   • Gehen Sie in Ihrer Coriolis Weboberfläche auf "Cloud Endpoints".
   • Klicken Sie auf "New Cloud Endpoint".
   • Klicken Sie unten auf den "upload"-Link (wie in Ihrem ersten Screenshot).
   • Laden Sie Ihre stackit_v2.endpoint-Datei hoch.

4. Validieren:

   Coriolis wird die Datei lesen, Ihren stackit_v2-Provider laden und die authenticate-Methode aufrufen. Wenn die Anmeldeinformationen korrekt sind, wird der Endpoint als "Valid" gespeichert.

Sie können nun mit dem Testen der list_...-Funktionen beginnen.