# 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.