Services bereitstellen

Dieser Leitfaden bietet einen umfassenden Überblick über den Lebenszyklus eines Managed Service in Codesphere. Er beschreibt die praktischen Schritte zum Bereitstellen, Konfigurieren, Warten und schließlich Löschen von Services.

Managed Services bereitstellen

Das Bereitstellen eines Managed Service kann über die Codesphere UI oder die öffentliche API erfolgen.

Ein Managed Service kann entweder ein eigenständiges Deployment sein oder in den Landscape-Lebenszyklus integriert werden. Dieser Leitfaden beschreibt, wie ein eigenständiger Service bereitgestellt wird. Informationen zur Bereitstellung von Services als Teil einer Landscape finden sich im Abschnitt Managed Services in Landscapes.

UI

1. Navigieren: Gehe zum Tab Managed Services.

2. Auswählen: Wähle den gewünschten Service-Provider aus dem Katalog. Services sind mit Kategorien gekennzeichnet (z. B. Database, Cache). In diesem Beispiel wählen wir PostgreSQL. Klicke auf "Start Setup".

3. Konfigurieren: Ein Konfigurationsdialog erscheint. Lege die anfänglichen Parameter fest. Nicht erforderliche Parameter können auf ihren Standardwerten belassen und bei Bedarf später angepasst werden. Manche Parameter (wie der Benutzername in diesem PostgreSQL-Beispiel) haben spezifische Anforderungen. Fahre mit der Maus über das "Info"-Symbol, um mehr zu erfahren. Klicke auf "Define Secrets", um fortzufahren.

4. Secrets: Die meisten Services benötigen Secrets. Erzeuge diese auf deinem Rechner und gib sie hier ein. Codesphere zeigt diese Secrets nach diesem Schritt nicht mehr an, daher sollten sie sicher gespeichert werden. Gehen sie verloren, müssen die Secrets zurückgesetzt werden, was zu einem Ausfall des Services führt. Klicke auf "Create Service", um fortzufahren.

5. Bereitstellen: Nach dem Klick auf "Deploy" beginnt Codesphere mit der Bereitstellung der Ressourcen. Wechsle in der linken Seitenleiste zum Tab Managed Services, um den Fortschritt zu verfolgen. Statusanzeigen aktualisieren sich, während der Service von Creating zu Synchronized wechselt. Nutze das Event-Log, um weitere Details zum Bereitstellungsprozess zu erhalten. Bei Problemen während der Bereitstellung liefert das Event-Log Hinweise darauf, was schiefgelaufen ist und wie es behoben werden kann.

API

Ein Managed Service kann über den Endpunkt POST /managed-services erstellt werden.

curl -X POST "<your-codesphere-instance-url>/api/managed-services" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 123,
    "name": "my-postgres-db",
    "provider": {
      "name": "postgresql",
      "version": "v1"
    },
    "plan": {
      "id": 1,
      "parameters": {
        "storage": 512
      }
    },
    "config": {
      "version": "17.9"
    },
    "secrets": {
      "userPassword": "secure-password",
      "superuserPassword": "secure-password"
    },
    "backups": {
      "enabled": true,
      "intervalH": 24,
      "deleteRetentionDays": 7,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/",
        "accessKeyId": "YOUR_S3_ACCESS_KEY"
      },
      "secrets": {
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

Parameter:

• teamId (integer, erforderlich): Die ID des Teams, in dem der Service erstellt wird.
• name (string, erforderlich): Ein eindeutiger Name für den Service.
• provider (object, erforderlich):
  • name: Der Name des Service-Providers (z. B. postgresql, redis).
  • version: Das Provider-Versions-Tag (z. B. v1).
• plan (object, erforderlich):
  • id: Die Plan-ID.
  • parameters: Planspezifische Parameter (z. B. Speichergröße in MiB).
• secrets (object): Schlüssel-Wert-Paare für geheime Service-Zugangsdaten.
• backups (object): Konfiguration automatisierter Backups. Für Provider, die dies unterstützen. Details siehe Leitfaden Managed Service Backups.
• recoverFrom (object): Initialisiert die Instanz automatisch anhand eines Point-in-Time-Backup-Objekts oder eines bestimmten Backups. Erfordert die backups-Konfiguration und die zugehörigen Secrets. Siehe Leitfaden Managed Service Backups.

Vollständige Schema-Details siehe API-Dokumentation.

info

API-Endpunkte stehen für alle Lebenszyklus-Operationen zur Verfügung, einschließlich Bereitstellung, Konfigurationsänderungen, Pausieren und Löschen.

info

Die Bereitstellungszeiten variieren je nach Service. Komplexe Datenbanken können einige Minuten benötigen, bis sie vollständig einsatzbereit sind.

Wie geht es weiter?

Sobald der Service läuft, folge der Managed Service Provider Referenz, um zu erfahren, wie dieser spezifische Service aus dem Workspace heraus angesprochen wird.

Aktualisieren / Konfigurieren

Die Konfiguration eines laufenden Services kann geändert werden, um sich an geänderte Anforderungen anzupassen.

UI

1. Suchen: Finde den bereitgestellten Service, der aktualisiert werden soll.
2. Einstellungen öffnen: Klicke auf das Zahnrad-Symbol rechts in der Tabellenzeile, um die Detailansicht des Services zu öffnen.
3. Ändern: Wechsle zum Tab Configuration und klicke auf Edit Configuration. Dies aktiviert die Bearbeitung konfigurierbarer Parameter. Zu beachten ist, dass nicht jede Option, die im Erstellungsprozess verfügbar war, auch für Updates verfügbar ist. Muss ein nicht editierbarer Parameter geändert werden, muss der Service gelöscht und mit der gewünschten Konfiguration neu erstellt werden.
4. Anwenden: Klicke auf Save, um die Änderungen anzuwenden. Der Service-Status wechselt von Synchronized zu Updating, während die Änderungen angewendet werden. Nach Abschluss kehrt er zu Synchronized zurück. Weitere Details zum Aktualisierungsprozess finden sich im Event-Log.

API

Ein Managed Service kann über den Endpunkt PATCH /managed-services/{id} aktualisiert werden.

curl -X PATCH "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "version": "17.9"
    },
    "plan": {
      "id": 1,
      "parameters": {
        "storage": 1024
      }
    },
    "secrets": {
      "userPassword": "new-secure-password",
      "superuserPassword": "new-secure-superuser-password"
    },
    "backups": {
      "enabled": true,
      "intervalH": 12,
      "deleteRetentionDays": 30,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/",
        "accessKeyId": "YOUR_S3_ACCESS_KEY"
      },
      "secrets": {
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    },
    "version": "v2"
  }'

Parameter:

• id (string, Pfadparameter): Die UUID des zu aktualisierenden Managed Service.
• config (object, optional): Konfigurationsänderungen.
• plan (object, optional):
  • id: Die neue Plan-ID.
  • parameters: Aktualisierte Plan-Parameter (z. B. Speicherplatz).
• secrets (object, optional): Aktualisierte Secrets.
• backups (object, optional): Konfiguration automatisierter Backups.
• name (string, optional): Neuer Name für den Service.
• pause (boolean, optional): Auf true setzen, um den Service zu pausieren.
• version (string, optional): Das neue Provider-Versions-Tag (z. B. v2). Weitere Details siehe Abschnitt Upgrade auf eine neue Version.

Die unterstützten Felder config, plan.parameters, secrets, Backup-Einstellungen und Provider-Versionen variieren je nach Service. Siehe Managed Service Provider Referenz für verfügbare Felder, zulässige Werte, Standardwerte und Update-Einschränkungen je Provider.

Vollständige Schema-Details siehe API-Dokumentation.

warnung

Manche Konfigurationsänderungen können einen Neustart des Services auslösen, was zu einem kurzen Ausfall führt.

Upgrade auf eine neue Version

Enthält eine Update-Anfrage eine Änderung des Versionsparameters, löst dies ein Versions-Upgrade oder -Downgrade aus. Der Fortschritt kann im Event-Log des Managed Service verfolgt werden.

Bei REST-basierten Providern hängt der Upgrade-Prozess von der jeweiligen Implementierung des Providers ab. Bei Landscape-basierten Providern läuft er stets wie folgt ab:

1. Git Checkout

Die kontrollierte Landscape führt einen Git-Checkout der in der Provider-Definition für die neue Version angegebenen Git-Referenz durch. Dabei kann es sich um einen Branch, einen Commit-Hash oder einen Tag handeln. Es wird der Git-Token des Nutzers verwendet, der die Aktualisierung ausgelöst hat, um vom Remote zu pullen.

2. Neustart

Die CI/CD-Pipeline der kontrollierten Landscape wird neu gestartet (zuerst stop all, dann run all). Dabei wird das in der Provider-Definition für die neue Version angegebene CI-Profil verwendet. Während der Dauer des Neustarts ist der Service nicht verfügbar.

warnung

Es gibt kein automatisches Rollback, falls das Upgrade fehlschlägt. Teste den Managed Service nach der Durchführung des Upgrades gründlich. Bei Problemen kann durch Senden einer Update-Anfrage mit der vorherigen Version ein Downgrade durchgeführt werden.

Pausieren

Codesphere ermöglicht es, bestimmte Managed Services zu pausieren, wenn sie nicht aktiv genutzt werden. Dies eignet sich ideal für Entwicklungsumgebungen oder Prototypen.

Funktionsweise

Nicht jeder Service unterstützt das Pausieren. Falls ein Service pausiert werden kann, ist diese Option unter den capabilities des Services sichtbar. Capabilities lassen sich über den GET providers Endpunkt der öffentlichen API einsehen.

• Pause: Nimmt den Service offline und gibt die Compute-Ressourcen (CPU & RAM) frei. Der Service-Status ändert sich zu Paused oder Stopped.
• Resume: Stellt die Compute-Ressourcen erneut bereit und bringt den Service wieder online.

Landscapes pausieren ihre eigenen Services automatisch, wenn sie abgebaut werden.

UI

Derzeit wird das Pausieren von Managed Services nur über die öffentliche API unterstützt. Anweisungen dazu finden sich im API-Tab.

API

Ein Managed Service kann pausiert werden, indem die Eigenschaft pause über den Endpunkt PATCH /managed-services/{id} auf true gesetzt wird.

Service pausieren:

curl -X PATCH "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pause": true
  }'

Service fortsetzen:

curl -X PATCH "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pause": false
  }'

Datenpersistenz

Bei Codesphere-verwalteten Services wie Managed Storage oder Object Store bleiben die Daten während einer Pause sicher. Das mit dem Service verbundene persistente Volume (Disk) wird nicht gelöscht. Beim Fortsetzen des Services wird es wieder mit demselben Volume verbunden, sodass alle Daten erhalten bleiben.

Landscape-basierte und benutzerdefinierte Provider

Dieses Verhalten gilt derzeit für eigenständige Managed Services. Bei Services, die in Landscape-Lebenszyklen integriert sind, oder bei benutzerdefinierten Service-Providern hängt die Datenpersistenz während der Pause von der jeweiligen Implementierung ab.

tipp

Das Pausieren nicht genutzter Services ist eine hervorragende Möglichkeit, Ressourcennutzung und Kosten zu optimieren.

Backups

Codesphere unterstützt automatisierte Backups und Point-in-Time Recovery für bestimmte Managed Service Provider (wie PostgreSQL, Babelfish und Object Storage). Dadurch lassen sich Daten sicher in einem externen S3-kompatiblen Service speichern.

Vollständige Anweisungen zur Konfiguration automatisierter Backups, zur Durchführung manueller Backups und zur Wiederherstellung eines Services aus einem früheren Zeitpunkt oder einer Backup-ID finden sich im entsprechenden Leitfaden Managed Service Backups.

Managed Services löschen

Beim Löschen eines Services wird der Lösch-Endpunkt eines Managed-Service-Backends aufgerufen. Bei von Codesphere angebotenen Managed Services werden dadurch alle mit diesem Service verbundenen Ressourcen entfernt.

Beim Auslösen einer Löschung beginnt Codesphere stets mit einem Soft Delete. Der Service wird mit einem deletedAt-Zeitstempel markiert und wechselt in den Status Deleting.

Ablauf der Löschung

1. Soft Delete: Der Service wird mit einem deletedAt-Zeitstempel markiert. Der Service-Status wechselt zu Deleting.
2. Finales Backup (falls aktiviert): Unterstützt der Provider Backups und sind Backups für den Service aktiviert, stellt der Reconciler sicher, dass nach Beginn der Löschung ein Backup eingeplant wird, und wartet, bis dieses Backup bestätigt ist, bevor fortgefahren wird.
3. Löschung beim Provider: Der Reconciler sendet die Löschanfrage an das Provider-Backend, wodurch Compute-Ressourcen und persistente Daten entfernt werden.
4. Aufbewahrungsfrist: Der Soft-gelöschte Service-Datensatz bleibt für eine Aufbewahrungsfrist sichtbar und wird anschließend durch den Cleanup-Prozess endgültig gelöscht (Hard Delete). Während dieses Zeitraums ist der Service weiterhin sichtbar, indem in der Service-Tabelle "Show recently Deleted" aktiviert wird.

UI

1. Navigieren: Gehe zur Seite der Service-Tabelle.
2. Löschen: Finde die Schaltfläche "Delete" im 3-Punkte-Menü.
3. Bestätigen: Zur Bestätigung der Aktion muss der Name des Services eingegeben werden.

API

Ein Managed Service kann über den Endpunkt DELETE /managed-services/{id} gelöscht werden.

curl -X DELETE "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Um den Schritt des finalen Backups zu überspringen und direkt mit der Löschung beim Provider fortzufahren, kann forceDelete: true im Request-Body übergeben werden:

curl -X DELETE "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forceDelete": true}'

Parameter:

• id (string, Pfadparameter): Die UUID des zu löschenden Managed Service.
• forceDelete (boolean, optional): Bei true wird das Warten auf das finale Backup übersprungen und direkt mit der Löschung beim Provider fortgefahren. Standardmäßig false (normaler Löschablauf).

Vollständige Schema-Details siehe API-Dokumentation.

warnung

Das Löschen eines Managed Service ist endgültig. Dabei werden sowohl die Compute-Ressourcen als auch das persistente Datenvolume entfernt. Diese Aktion kann nicht rückgängig gemacht werden. Kürzlich gelöschte Services lassen sich über die Checkbox "Show recently Deleted" einsehen, können jedoch nicht wiederhergestellt werden.

Force Delete

Bleibt ein Service im Status Deleting hängen, weil das finale Backup nicht erfolgreich abgeschlossen wird (dies lässt sich im Event-Log prüfen), kann Force Delete verwendet werden, um das Warten auf das finale Backup zu umgehen und den Service-Datensatz sofort zu entfernen.

So wird ein Service über die UI zwangsweise gelöscht:

1. Öffne den Menüpunkt "Delete" für den hängenden Service.
2. Aktiviere im Bestätigungsdialog die Checkbox "Force Delete".
3. Gib zur Bestätigung den Servicenamen ein und klicke dann auf Delete.

gefahr

Force Delete umgeht die Datensicherheitsprüfungen und führt zu endgültigem Datenverlust. Alle noch nicht gesicherten Daten sind dann nicht wiederherstellbar. Diese Option sollte nur verwendet werden, wenn der Standard-Löschablauf fehlgeschlagen ist und das Risiko eines Datenverlusts akzeptiert wird.