Benutzerdefinierte Ziele

In diesem Dokument wird beschrieben, wie benutzerdefinierte Ziele in Cloud Deploy funktionieren.

Cloud Deploy bietet integrierte Unterstützung für verschiedene Laufzeitumgebungen als Ziele. Die Liste der unterstützten Zieltypen ist jedoch begrenzt. Mit benutzerdefinierten Zielen können Sie die Bereitstellung auf anderen Systemen als den unterstützten Runtimes vornehmen.

Ein benutzerdefiniertes Ziel ist ein Ziel, das eine beliebige Ausgabenumgebung darstellt, die nicht von Cloud Deploy unterstützt wird.

Auf der Seite Benutzerdefiniertes Ziel erstellen wird beschrieben, wie Sie einen benutzerdefinierten Zieltyp definieren und als Ziel in einer Bereitstellungspipeline implementieren.

Was fließt in ein benutzerdefiniertes Zielvorhaben ein?

Jedes benutzerdefinierte Zielvorhaben besteht aus den folgenden Komponenten:

  • Benutzerdefinierte Aktionen, definiert in skaffold.yaml

    Sie ähneln den Bereitstellungshooks. In der Datei skaffold.yaml definieren Sie customActions. Jede benutzerdefinierte Aktion gibt ein zu verwendendes Container-Image und Befehle an, die in diesem Container ausgeführt werden sollen.

    Das benutzerdefinierte Ziel ist also einfach eine benutzerdefinierte Aktion oder eine Reihe von Aktionen.

    Für jeden benutzerdefinierten Zieltyp konfigurieren Sie eine benutzerdefinierte Rendering-Aktion und eine benutzerdefinierte Bereitstellungsaktion. Für diese Aktionen werden Werte aus Cloud Deploy verwendet und sie müssen eine Reihe erforderlicher Ausgaben erfüllen.

    Die benutzerdefinierte Render-Aktion ist optional. Sie müssen sie jedoch erstellen, es sei denn, Ihr benutzerdefiniertes Ziel funktioniert auch dann richtig, wenn es von skaffold render gerendert wird. Das ist die Standardeinstellung für Cloud Deploy.

  • Eine Definition des benutzerdefinierten Zieltyps

    CustomTargetType ist eine Cloud Deploy-Ressource, die die benutzerdefinierten Aktionen identifiziert, die für die Aktivitäten zum Rendern von Releases und zum Bereitstellen von Roll-outs für Ziele dieses Typs verwendet werden. Die benutzerdefinierten Aktionen werden separat in Ihrem skaffold.yaml definiert.

  • Eine Zieldefinition

    Die Zieldefinition für ein benutzerdefiniertes Ziel ist dieselbe wie für jeden anderen Zieltyp, mit der Ausnahme, dass sie das Attribut customTarget enthält, dessen Wert der Name des CustomTargetType ist.

Wenn diese Komponenten vorhanden sind, können Sie das Ziel wie jedes andere Ziel verwenden, es in Ihrer Bereitstellungspipeline referenzieren und die Cloud Deploy-Funktionen wie Hochstufung und Genehmigungen und Rollbacks vollständig nutzen.

Beispiel

Im Schnellstart wird ein benutzerdefinierter Zieltyp erstellt, der einfache Befehle enthält, die für ein Container-Image ausgeführt werden können – ein Befehl für das Rendern und einer für die Bereitstellung. Mit den Befehlen wird in diesem Fall nur Text zu den erforderlichen Ausgabedateien für das Rendern und Bereitstellen hinzugefügt.

Weitere Beispiele finden Sie unter Beispiele für benutzerdefinierte Ziele.

Erforderliche Ein- und Ausgaben

Jeder benutzerdefinierte Zieltyp, der für Cloud Deploy definiert ist, muss die Anforderungen für Ein- und Ausgabe sowohl für das Rendern als auch für die Bereitstellung erfüllen. In diesem Abschnitt wird aufgeführt, welche Ein- und Ausgaben erforderlich sind und wie sie bereitgestellt werden.

Cloud Deploy stellt die erforderlichen Eingaben für das Rendern und die Bereitstellung als Umgebungsvariablen bereit. In den folgenden Abschnitten werden diese Eingaben sowie die Ausgaben aufgeführt, die von Ihren benutzerdefinierten Render- und Bereitstellungsaktionen zurückgegeben werden müssen.

Parameter als Umgebungsvariablen bereitstellen

Zusätzlich zu den in diesem Abschnitt aufgeführten Umgebungsvariablen kann Cloud Deploy alle von Ihnen festgelegten Bereitstellungsparameter an Ihre benutzerdefinierten Container übergeben.

Weitere Informationen

Eingaben zum Rendern von Aktionen

Für benutzerdefinierte Render-Aktionen stellt Cloud Deploy die folgenden Eingaben als Umgebungsvariablen bereit. Für mehrphasige Rollouts (Canary-Bereitstellungen) stellt Cloud Deploy diese Variablen für jede Phase bereit.

  • CLOUD_DEPLOY_PROJECT

    Die Google Cloud Projektnummer des Projekts, in dem das benutzerdefinierte Zielvorhaben erstellt wird.

  • CLOUD_DEPLOY_PROJECT_ID

    Die Google Cloud Projekt-ID für das Projekt.

  • CLOUD_DEPLOY_LOCATION

    Die Google Cloud -Region für den benutzerdefinierten Zieltyp.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Der Name der Cloud Deploy-Bereitstellungspipeline, die auf den benutzerdefinierten Zieltyp verweist.

  • CLOUD_DEPLOY_RELEASE

    Der Name des Release, für das der Rendering-Vorgang aufgerufen wird.

  • CLOUD_DEPLOY_TARGET

    Der Name des Cloud Deploy-Ziels, das den benutzerdefinierten Zieltyp verwendet.

  • CLOUD_DEPLOY_PHASE

    Die Rollout-Phase, der das Rendering entspricht.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Bei der benutzerdefinierten Rendering-Aktion ist dies immer RENDER.

  • CLOUD_DEPLOY_FEATURES

    Eine durch Kommas getrennte Liste der Cloud Deploy-Funktionen, die der benutzerdefinierte Container unterstützen muss. Diese Variable wird basierend auf den in Ihrer Bereitstellungspipeline konfigurierten Funktionen ausgefüllt.

    Wenn Ihre Implementierung die Funktionen in dieser Liste nicht unterstützt, empfehlen wir, dass sie beim Rendern fehlschlägt.

    Bei Standardbereitstellungen ist dieses Feld leer. Bei Canary-Bereitstellungen ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY ist, wird die Render-Aktion für jede Phase im Canary aufgerufen. Der Canary-Prozentsatz für jede Phase wird in der Umgebungsvariable CLOUD_DEPLOY_PERCENTAGE_DEPLOY angegeben.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Der Prozentsatz der Bereitstellung, der mit diesem Rendervorgang verknüpft ist. Wenn die Umgebungsvariable CLOUD_DEPLOY_FEATURES auf CANARY gesetzt ist, wird Ihre benutzerdefinierte Render-Aktion für jede Phase aufgerufen und diese Variable wird für jede Phase auf den Canary-Prozentsatz gesetzt. Bei Standard-Deployments und bei Canary-Deployments, die die stable-Phase erreicht haben, ist dies 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Der Speicheranbieter. Immer GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Der Cloud Storage-Pfad für das Archiv der gerenderten Datei, das beim Erstellen des Releases geschrieben wurde.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Der Cloud Storage-Pfad, in den der benutzerdefinierte Rendering-Container Artefakte hochladen soll, die für die Bereitstellung verwendet werden. Beachten Sie, dass mit der Aktion „render“ eine Datei namens results.json hochgeladen werden muss, die die Ergebnisse dieses Rendervorgangs enthält. Weitere Informationen finden Sie unter Ausgaben der Render-Aktion.

Ausgaben der Render-Aktion

Ihre benutzerdefinierte Render-Aktion muss die in diesem Abschnitt beschriebenen Informationen enthalten. Die Informationen müssen in der Ergebnisdatei mit dem Namen results.json enthalten sein, die sich im von Cloud Deploy bereitgestellten Cloud Storage-Bucket befindet.

  • Gerenderte Konfigurationsdatei(en)

  • Eine results.json-Datei mit den folgenden Informationen:

    • Eine Angabe des Erfolgs- oder Fehlerstatus der benutzerdefinierten Aktion.

      Gültige Werte sind SUCCEEDED und FAILED.

    • Optional: Fehlermeldungen, die von der benutzerdefinierten Aktion generiert werden.

    • Der Cloud Storage-Pfad für die gerenderte Konfigurationsdatei oder die gerenderten Konfigurationsdateien.

      Der Pfad für alle gerenderten Konfigurationsdateien ist der vollständige URI. Sie wird teilweise mit dem Wert von CLOUD_DEPLOY_OUTPUT_GCS_PATH gefüllt, der von Cloud Deploy bereitgestellt wird.

      Sie müssen die gerenderte Konfigurationsdatei angeben, auch wenn sie leer ist. Der Inhalt der Datei kann beliebig sein, solange er von Ihrer benutzerdefinierten Bereitstellungsaktion verarbeitet werden kann. Wir empfehlen, dass diese Datei für Menschen lesbar ist, damit Sie und andere Nutzer in Ihrer Organisation sie in der Versionsprüfung ansehen können.

    • Optional: eine Zuordnung der Metadaten, die Sie einfügen möchten

      Diese Metadaten werden durch Ihr benutzerdefiniertes Zielvorhaben erstellt. Diese Metadaten werden in der Veröffentlichung im Feld custom_metadata gespeichert.

Wenn Sie die Datei results.json untersuchen müssen, z. B. zur Fehlerbehebung, finden Sie den Cloud Storage-URI dafür in den Cloud Build-Logs.

Beispieldatei mit Render-Ergebnissen

Im Folgenden sehen Sie ein Beispiel für die Ausgabe einer results.json-Datei aus einer benutzerdefinierten Renderaktion:

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Eingaben zum Bereitstellen von Aktionen

Für benutzerdefinierte Bereitstellungsaktionen stellt Cloud Deploy die folgenden Eingaben als Umgebungsvariablen bereit:

  • CLOUD_DEPLOY_PROJECT

    Die Google Cloud Projektnummer des Projekts, in dem das benutzerdefinierte Zielvorhaben erstellt wird.

  • CLOUD_DEPLOY_PROJECT_ID

    Die Google Cloud Projekt-ID für das Projekt.

  • CLOUD_DEPLOY_LOCATION

    Die Google Cloud -Region für den benutzerdefinierten Zieltyp.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Der Name der Cloud Deploy-Bereitstellungspipeline, die auf das Ziel verweist, das den benutzerdefinierten Zieltyp verwendet.

  • CLOUD_DEPLOY_RELEASE

    Der Name des Release, für den der Bereitstellungsvorgang aufgerufen wird.

  • CLOUD_DEPLOY_ROLLOUT

    Der Name des Cloud Deploy-Roll-outs, für das diese Bereitstellung erfolgt.

  • CLOUD_DEPLOY_TARGET

    Der Name des Cloud Deploy-Ziels, das den benutzerdefinierten Zieltyp verwendet.

  • CLOUD_DEPLOY_PHASE

    Die Rollout-Phase, der die Bereitstellung entspricht.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Für die benutzerdefinierte Bereitstellungsaktion ist dies immer DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Eine durch Kommas getrennte Liste der Cloud Deploy-Funktionen, die der benutzerdefinierte Container unterstützen muss. Diese Variable wird basierend auf den in Ihrer Bereitstellungspipeline konfigurierten Funktionen ausgefüllt.

    Wenn Ihre Implementierung die Funktionen in dieser Liste nicht unterstützt, empfehlen wir, dass sie beim Rendern fehlschlägt.

    Bei Standardbereitstellungen ist dieses Feld leer. Bei Canary-Bereitstellungen ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY ist, wird die Render-Aktion für jede Phase im Canary aufgerufen. Der Canary-Prozentsatz für jede Phase wird in der Umgebungsvariable CLOUD_DEPLOY_PERCENTAGE_DEPLOY angegeben.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Der Prozentsatz der Bereitstellung, der mit diesem Bereitstellungsvorgang verknüpft ist. Wenn die Umgebungsvariable CLOUD_DEPLOY_FEATURES auf CANARY gesetzt ist, wird Ihre benutzerdefinierte Bereitstellungsaktion für jede Phase aufgerufen und diese Variable wird für jede Phase auf den Canary-Prozentsatz gesetzt. Ihre Bereitstellungsaktion muss für jede Phase ausgeführt werden.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Der Speicheranbieter. Immer GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Der Cloud Storage-Pfad, in den der benutzerdefinierte Renderer die gerenderten Konfigurationsdateien geschrieben hat.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Der Cloud Storage-Pfad zur gerenderten Skaffold-Konfiguration.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Der Cloud Storage-Pfad zur gerenderten Manifestdatei.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Der Pfad zum Cloud Storage-Verzeichnis, in das der benutzerdefinierte Bereitstellungscontainer Bereitstellungsartefakte hochladen soll. Weitere Informationen finden Sie unter Ausgaben der Bereitstellungsaktion.

Ausgaben der Bereitstellungsaktion

Ihre benutzerdefinierte Bereitstellungsaktion muss eine results.json-Ausgabedatei schreiben. Diese Datei muss sich im Cloud Storage-Bucket befinden, der von Cloud Deploy bereitgestellt wird (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

Die Datei muss Folgendes enthalten:

  • Eine Angabe des Erfolgs- oder Fehlerstatus der benutzerdefinierten Bereitstellungsaktion.

    Die folgenden Status sind gültig:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Dies gilt für Canary-Bereitstellungen, bei denen Canary-Phasen übersprungen werden, um direkt zu stable zu wechseln.

  • (Optional) Eine Liste von Bereitstellungsartefaktdateien in Form von Cloud Storage-Pfaden.

    Der Pfad ist der vollständige URI. Sie wird teilweise mit dem Wert von CLOUD_DEPLOY_OUTPUT_GCS_PATH provided (bereitgestellt) von Cloud Deploy gefüllt.

    Die hier aufgeführten Dateien werden in Job-Ausführungsressourcen als Bereitstellungsartefakte eingefügt.

  • Optional: eine Fehlermeldung, wenn die benutzerdefinierte Bereitstellungsaktion fehlschlägt (Status FAILED wird zurückgegeben)

    Mit dieser Nachricht wird failure_message im Joblauf für diese Bereitstellungsaktion ausgefüllt.

  • Optional: Eine Überspringensnachricht, um zusätzliche Informationen bereitzustellen, wenn für die Aktion der Status SKIPPED zurückgegeben wird.

  • Optional: eine Zuordnung der Metadaten, die Sie einfügen möchten

    Diese Metadaten werden durch Ihr benutzerdefiniertes Zielvorhaben erstellt. Diese Metadaten werden im Joblauf und im Rollout im Feld custom_metadata gespeichert.

Wenn Sie die Datei results.json untersuchen müssen, z. B. zur Fehlerbehebung, finden Sie den Cloud Storage-URI dafür in den Cloud Build-Release-Render-Logs.

Beispieldatei mit Bereitstellungsergebnissen

Im Folgenden finden Sie ein Beispiel für die Ausgabe einer results.json-Datei aus einer benutzerdefinierten Bereitstellungsaktion:

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Weitere Informationen zu benutzerdefinierten Aktionen

Hier sind einige Punkte, die Sie beim Einrichten und Verwenden benutzerdefinierter Zieltypen beachten sollten.

Benutzerdefinierte Aktionen ausführen

Ihre benutzerdefinierten Rendering- und Bereitstellungsaktionen werden in der Ausführungsumgebung von Cloud Deploy ausgeführt. Sie können Ihre benutzerdefinierten Aktionen nicht so konfigurieren, dass sie in einem Google Kubernetes Engine-Cluster ausgeführt werden.

Remote-Skaffold-Konfigurationen verwenden

Wie in diesem Dokument beschrieben, konfigurieren Sie Ihre benutzerdefinierte Aktion in der Datei skaffold.yaml, die beim Erstellen der Version bereitgestellt wird. Sie können Skaffold-Konfigurationen aber auch in einem Git-Repository oder in einem Cloud Storage-Bucket speichern und in der Definition des benutzerdefinierten Zieltyps darauf verweisen. So können Sie benutzerdefinierte Aktionen verwenden, die an einem einzigen, freigegebenen Ort definiert und gespeichert sind, anstatt sie in die skaffold.yaml-Datei jeder Version aufzunehmen.

Benutzerdefinierte Ziele und Bereitstellungsstrategien

Benutzerdefinierte Ziele werden für Standardbereitstellungen vollständig unterstützt.

Cloud Deploy unterstützt Canary-Deployments, sofern der benutzerdefinierte Renderer und Deployer die Canary-Funktion unterstützen.

Sie müssen eine benutzerdefinierte Canary-Konfiguration verwenden. Automatisierte und benutzerdefinierte automatisierte Canaries werden bei benutzerdefinierten Zielen nicht unterstützt.

Benutzerdefinierte Ziele und Bereitstellungsparameter

Sie können Bereitstellungsparameter mit benutzerdefinierten Zielen verwenden. Sie können sie in der Phase der Auslieferungspipeline, für das Ziel mit einem benutzerdefinierten Zieltyp oder für die Version festlegen.

Bereitstellungsparameter werden zusätzlich zu den bereits bereitgestellten als Umgebungsvariablen an Ihre benutzerdefinierten Render- und Deployment-Container übergeben.

Beispiele für benutzerdefinierte Ziele

Das cloud-deploy-samples-Repository enthält eine Reihe von Implementierungen für benutzerdefinierte Ziele. Die folgenden Beispiele sind verfügbar:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Jedes Beispiel enthält einen Schnellstart.

Diese Muster sind kein unterstütztes Google Cloud Produkt und fallen nicht unter einen Google Cloud Supportvertrag. Wenn Sie Fehler melden oder Funktionen in einem Google Cloud Produkt anfordern möchten, wenden Sie sich an den Google CloudSupport.

Nächste Schritte