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 neben den unterstützten Laufzeiten auch auf anderen Systemen bereitstellen.

Ein benutzerdefiniertes Ziel ist ein Ziel, das eine beliebige Ausgabeumgebung darstellt, die nicht von einer Laufzeit unterstützt wird, die 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 gehört zu einem benutzerdefinierten Targeting?

Jedes benutzerdefinierte Ziel besteht aus den folgenden Komponenten:

  • Benutzerdefinierte Aktionen, in skaffold.yaml definiert

    Sie ähneln der Definition von Deployment-Hooks. In der Datei skaffold.yaml definieren Sie customActions. Jede benutzerdefinierte Aktion identifiziert ein zu verwendendes Container-Image und Befehle, 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 von Cloud Deploy verwendet und sie müssen eine Reihe von erforderlichen Ausgaben erfüllen.

    Die benutzerdefinierte Rendering-Aktion ist optional, Sie müssen sie jedoch erstellen, es sei denn, Ihr benutzerdefiniertes Ziel funktioniert ordnungsgemäß, wenn es von skaffold render gerendert wird, was der Standard für Cloud Deploy ist.

  • Eine Definition eines benutzerdefinierten Zieltyps

    Die CustomTargetType ist eine Cloud Deploy-Ressource, die die benutzerdefinierten Aktionen identifiziert, die in Ihrer skaffold.yaml separat definiert sind und die für Release-Rendering- und Roll-out-Bereitstellungsaktivitäten verwendet werden.

  • Eine Zieldefinition

    Die Zieldefinition für ein benutzerdefiniertes Ziel entspricht der Definition für jeden anderen Zieltyp, mit der Ausnahme, dass sie die Property customTarget enthält, deren Wert der Name der CustomTargetType ist.

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

Beispiel

In der Anleitung zum Definieren und Verwenden eines benutzerdefinierten Zieltyps wird ein benutzerdefinierter Zieltyp mit einfachen Befehlen zum Ausführen auf einem Container-Image erstellt – ein Befehl zum Rendern und ein Befehl zum Bereitstellen. Die Befehle fügen in diesem Fall nur Text zu den erforderlichen Ausgabedateien für das Rendern und Bereitstellen hinzu.

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

Erforderliche Eingaben und Ausgaben

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

Cloud Deploy stellt die erforderlichen Eingaben sowohl für das Rendern als auch für das Bereitstellen als Umgebungsvariablen bereit. In den folgenden Abschnitten werden diese Eingaben sowie die Ausgaben aufgeführt, die Ihre benutzerdefinierten Render- und Bereitstellungsaktionen zurückgeben 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 für das Rendern von Aktionen

Für benutzerdefinierte Renderaktionen stellt Cloud Deploy die folgenden erforderlichen Eingaben als Umgebungsvariablen bereit. Bei mehrstufigen Roll-outs (Kanarien-Bereitstellungen) stellt Cloud Deploy diese Variablen für jede Phase bereit.

  • CLOUD_DEPLOY_PROJECT

    Das Google Cloud-Projekt, in dem der benutzerdefinierte Zieltyp erstellt wird.

  • 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 den der Renderingvorgang aufgerufen wird.

  • CLOUD_DEPLOY_TARGET

    Der Name des Cloud Deploy-Ziels, für das der benutzerdefinierte Zieltyp verwendet wird.

  • CLOUD_DEPLOY_PHASE

    Die Roll-out-Phase, der das Rendern entspricht.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Bei der benutzerdefinierten Renderaktion ist dies immer RENDER.

  • CLOUD_DEPLOY_FEATURES

    Eine durch Kommas getrennte Liste der Cloud Deploy-Features, die der benutzerdefinierte Container unterstützen muss. Diese Variable wird anhand der 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 Standardimplementierungen ist dieses Feld leer. Bei Canary-Bereitstellungen ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY ist, wird Ihre Renderaktion für jede Phase im Canary aufgerufen. Der Prozentsatz der Canary-Version für jede Phase wird in der Umgebungsvariablen CLOUD_DEPLOY_PERCENTAGE_DEPLOY angegeben.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Der Prozentsatz der Bereitstellung, der mit diesem Renderingvorgang verknüpft ist. Wenn die Umgebungsvariable CLOUD_DEPLOY_FEATURES auf CANARY festgelegt ist, wird Ihre benutzerdefinierte Renderaktion für jede Phase aufgerufen und diese Variable wird für jede Phase auf den Canary-Prozentsatz festgelegt. Bei Standard-Deployments und Canary-Deployments, die die Phase stable erreicht haben, ist das 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Der Speicheranbieter. Immer GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Der Cloud Storage-Pfad für das Renderdateiarchiv, das beim Erstellen der Version geschrieben wurde.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Der Cloud Storage-Pfad, unter dem der benutzerdefinierte Rendercontainer Artefakte für die Bereitstellung hochladen soll. Die Renderaktion muss eine Datei mit dem Namen results.json hochladen, die die Ergebnisse dieses Rendervorgangs enthält. Weitere Informationen finden Sie unter Ausgaben der Renderaktion.

Ausgaben aus der Renderaktion

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

  • Gerenderte Konfigurationsdatei(en)

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

    • Eine Angabe zum Erfolg oder Fehlschlag der benutzerdefinierten Aktion.

      Gültige Werte sind SUCCEEDED und FAILED.

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

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

      Der Pfad für alle gerenderten Konfigurationsdateien ist der vollständige URI. Sie füllen es teilweise mit dem Wert von CLOUD_DEPLOY_OUTPUT_GCS_PATH aus, der von Cloud Deploy zur Verfügung gestellt wird.

      Sie müssen die gerenderte Konfigurationsdatei angeben, auch wenn sie leer ist. Der Inhalt der Datei kann beliebig sein und in jedem Format vorliegen, solange er von Ihrer benutzerdefinierten Bereitstellungsaktion verwendet werden kann. Wir empfehlen, dass diese Datei für Menschen lesbar ist, damit Sie und andere Nutzer in Ihrer Organisation sie im Release-Inspektor aufrufen können.

    • Optional: Eine Zuordnung aller Metadaten, die eingefügt werden sollen

      Diese Metadaten werden von Ihrem benutzerdefinierten Ziel erstellt. Diese Metadaten werden im Release im Feld custom_metadata gespeichert.

Wenn Sie die Datei results.json beispielsweise zum Debuggen prüfen möchten, finden Sie den Cloud Storage-URI dazu in den Cloud Build-Protokollen.

Beispieldatei für Rendering-Ergebnisse

Im Folgenden finden 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 für die Bereitstellung von Aktionen

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

  • CLOUD_DEPLOY_PROJECT

    Das Google Cloud-Projekt, in dem das benutzerdefinierte Ziel erstellt wird.

  • CLOUD_DEPLOY_LOCATION

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

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Der Name der Cloud Deploy-Auslieferungspipeline, der auf das Ziel verweist, für das der benutzerdefinierte Zieltyp verwendet wird.

  • 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, für das der benutzerdefinierte Zieltyp verwendet wird.

  • CLOUD_DEPLOY_PHASE

    Die Roll-out-Phase, der die Bereitstellung entspricht.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Bei der benutzerdefinierten Bereitstellungsaktion ist dies immer DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Eine durch Kommas getrennte Liste der Cloud Deploy-Features, die der benutzerdefinierte Container unterstützen muss. Diese Variable wird anhand der 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 Standardimplementierungen ist dieses Feld leer. Bei Canary-Bereitstellungen ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY ist, wird Ihre Renderaktion für jede Phase im Canary aufgerufen. Der Prozentsatz der Canary-Version für jede Phase wird in der Umgebungsvariablen 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. Die 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 aus der Bereitstellungsaktion

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

Die Datei muss Folgendes enthalten:

  • Eine Angabe zum Erfolg oder Fehlschlag der benutzerdefinierten Bereitstellungsaktion.

    Folgende Status sind zulässig:

  • Optional: Eine Liste von Bereitstellungsartefaktdateien in Form von Cloud Storage-Pfaden

    Der Pfad ist der vollständige URI. Sie füllen sie teilweise mit dem Wert der von Cloud Deploy angegebenen CLOUD_DEPLOY_OUTPUT_GCS_PATH aus.

    Die hier aufgeführten Dateien werden als Bereitstellungsartefakte in den Ressourcen für die Jobausführung eingefügt.

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

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

  • Optional: Eine Ignoriernachricht, um zusätzliche Informationen bereitzustellen, wenn die Aktion den Status SKIPPED zurückgibt.

  • Optional: Eine Zuordnung aller Metadaten, die eingefügt werden sollen

    Diese Metadaten werden von Ihrem benutzerdefinierten Ziel erstellt. Diese Metadaten werden im Feld custom_metadata für den Job und für das Roll-out gespeichert.

Wenn Sie die Datei results.json beispielsweise zum Debuggen untersuchen möchten, finden Sie den Cloud Storage-URI in den Cloud Build-Release-Renderprotokollen.

Beispieldatei für Bereitstellungsergebnisse

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

Beachten Sie beim Einrichten und Verwenden benutzerdefinierter Targeting-Typen Folgendes:

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-fähige, wiederverwendbare Skaffold-Konfigurationen verwenden

Wie in diesem Dokument beschrieben, konfigurierst du deine benutzerdefinierte Aktion in der skaffold.yaml-Datei, die bei der Erstellung der Version bereitgestellt wird. Sie können Skaffold-Konfigurationen aber auch in einem Git-Repository oder in einem Cloud Storage-Bucket speichern und über die Definition des benutzerdefinierten Zieltyps darauf verweisen. So können Sie benutzerdefinierte Aktionen verwenden, die an einem einzigen freigegebenen Speicherort definiert und gespeichert sind, anstatt die benutzerdefinierten Aktionen in die skaffold.yaml-Datei jeder Version aufzunehmen.

Benutzerdefinierte Ziele und Bereitstellungsstrategien

Benutzerdefinierte Ziele werden bei Standard-Deployments 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. Automatische und benutzerdefinierte automatische Kanarien werden nicht unterstützt.

Benutzerdefinierte Ziele und Bereitstellungsparameter

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

Bereitstellungsparameter werden zusätzlich zu den bereits bereitgestellten als Umgebungsvariablen an Ihre benutzerdefinierten Rendering- und Bereitstellungscontainer übergeben.

Beispiele für benutzerdefinierte Ziele

Das cloud-deploy-samples-Repository enthält eine Reihe von Beispielimplementierungen für benutzerdefinierte Ziele. Folgende Samples sind verfügbar:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Jedes Beispiel enthält einen Schnellstart.

Diese Samples 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 Cloud-Support.

Nächste Schritte