Benutzerdefinierte Ziele

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

Cloud Deploy unterstützt verschiedene Laufzeitumgebungen als Ziele eingebunden. Die Liste der unterstützten Zieltypen ist jedoch endlos. Mit benutzerdefinierten Zielen können Sie zusätzlich zu den unterstützten Laufzeiten weitere Systeme bereitstellen.

Ein benutzerdefiniertes Ziel ist ein Ziel, das eine beliebige Ausgabeumgebung darstellt, die sich von einer von Cloud Deploy unterstützten Laufzeit unterscheidet.

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

Was gehört in ein benutzerdefiniertes Ziel?

Jedes benutzerdefinierte Ziel besteht aus den folgenden Komponenten:

  • Benutzerdefinierte Aktionen, in skaffold.yaml definiert

    Die Vorgehensweise ähnelt der Definition von Bereitstellungs-Hooks. In der Datei skaffold.yaml definieren Sie customActions, wobei jede benutzerdefinierte Aktion das zu verwendende Container-Image angibt und Befehle, die auf diesem Container ausgeführt werden sollen.

    Daher ist das benutzerdefinierte Ziel einfach eine benutzerdefinierte Aktion oder eine Gruppe von Aktionen.

    Für jeden benutzerdefinierten Zieltyp konfigurieren Sie eine benutzerdefinierte Renderingaktion und eine benutzerdefinierte Bereitstellungsaktion. Diese Aktionen verbrauchen von Cloud Deploy bereitgestellte Werte und müssen eine Gruppe von erforderlichen Ausgaben erfüllen.

    Die benutzerdefinierte Renderingaktion ist optional. Sie müssen jedoch eine erstellen, wenn Ihr benutzerdefiniertes Ziel nicht korrekt funktioniert, wenn es von skaffold render gerendert wird. Dies ist die Standardeinstellung für Cloud Deploy.

  • Eine Definition des benutzerdefinierten Zieltyps

    Die CustomTargetType ist eine Cloud Deploy-Ressource, die die benutzerdefinierten Aktionen identifiziert (separat in Ihrer skaffold.yaml definiert), die auf diesen Typ abzielen und für Aktivitäten zur Release-Rendering- und Roll-out-Bereitstellung bestimmt sind.

  • Eine Zieldefinition

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

Sobald diese Komponenten vorhanden sind, können Sie das Ziel wie jedes andere Ziel verwenden, darauf aus der Fortschrittspipeline der Bereitstellungspipeline verweisen und die Cloud Deploy-Features wie Hochstufung und Genehmigungen und Rollbacks in vollem Umfang nutzen.

Beispiel

In der Kurzanleitung Benutzerdefinierten Zieltyp definieren und verwenden wird ein benutzerdefinierter Zieltyp erstellt, der einfache Befehle zur Ausführung auf einem Container-Image enthält: einen Befehl zum Rendern und einen zum Bereitstellen. Mit den Befehlen fügen Sie den erforderlichen Ausgabedateien zum Rendern und Bereitstellen einfach Text hinzu.

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

Erforderliche Ein- und Ausgaben

Jeder für Cloud Deploy definierte benutzerdefinierte Zieltyp muss sowohl beim Rendern als auch beim Bereitstellen die Anforderungen an die Ein- und Ausgabe 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 sowohl zum Rendern als auch zum Bereitstellen als Umgebungsvariablen bereit. In den folgenden Abschnitten werden diese Eingaben sowie die Ausgaben aufgeführt, die Ihre benutzerdefinierten Rendering- 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.

Bereitstellungsparameter, die als Eingaben für benutzerdefinierte Ziele dienen, müssen mit customTarget/ beginnen, z. B. customTarget/vertexAIModel. Verwenden Sie die folgende Syntax, wenn Sie als Umgebungsvariable auf einen Bereitstellungsparameter verweisen:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Dabei ist VAR_NAME der Name nach dem Schrägstrich im Namen des Bereitstellungsparameters. Wenn Sie beispielsweise einen Bereitstellungsparameter namens customTarget/vertexAIModel definieren, verweisen Sie mit CLOUD_DEPLOY_customTarget_vertexAIModel darauf.

Eingaben für Renderingaktionen

Für benutzerdefinierte Renderingaktionen stellt Cloud Deploy die folgenden erforderlichen Eingaben als Umgebungsvariablen bereit. Bei mehrstufigen Rollouts (Canary-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 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 Renderingaktion ist dies immer RENDER.

  • CLOUD_DEPLOY_FEATURES

    Eine durch Kommas getrennte Liste von Cloud Deploy-Features, die der benutzerdefinierte Container unterstützen muss. Diese Variable wird anhand der in Ihrer Bereitstellungspipeline konfigurierten Features ausgefüllt.

    Wenn deine Implementierung die in dieser Liste aufgeführten Funktionen nicht unterstützt, sollte beim Rendern ein Fehler auftreten.

    Bei Standardbereitstellungen ist dieses Feld leer. Für Canary-Deployments ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY lautet, wird die Renderingaktion für jede Canary-Phase 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 diesem Renderingvorgang zugeordnet ist. Wenn die Umgebungsvariable CLOUD_DEPLOY_FEATURES auf CANARY gesetzt ist, wird die benutzerdefinierte Renderingaktion für jede Phase aufgerufen und diese Variable auf den Canary-Prozentsatz für jede Phase gesetzt. Für Standardbereitstellungen und Canary-Bereitstellungen, 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 Renderingdateien, der beim Erstellen des Release geschrieben wurde.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Der Cloud Storage-Pfad, in den der benutzerdefinierte Renderingcontainer Artefakte für die Bereitstellung hochladen soll. Bei der Renderingaktion muss eine Datei mit dem Namen results.json hochgeladen werden, die die Ergebnisse dieses Renderingvorgangs enthält. Weitere Informationen finden Sie unter Ausgaben der Renderingaktion.

Ausgaben der Renderingaktion

Die benutzerdefinierte Renderingaktion muss die in diesem Abschnitt beschriebenen Informationen enthalten. Die Informationen müssen in der Ergebnisdatei 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:

    • Gibt den Erfolgs- oder Fehlerstatus der benutzerdefinierten Aktion an.

      Gültige Werte sind SUCCEEDED und FAILED.

    • Optional: alle Fehlermeldungen, die durch die benutzerdefinierte Aktion generiert werden.

    • Der Cloud Storage-Pfad für die gerenderte Konfigurationsdatei(en).

      Der Pfad für alle gerenderten Konfigurationsdateien ist der vollständige URI. Sie füllen es teilweise mit dem Wert der von Cloud Deploy CLOUD_DEPLOY_OUTPUT_GCS_PATH bereitgestellten.

      Sie müssen die gerenderte Konfigurationsdatei bereitstellen, auch wenn sie leer ist. Der Inhalt der Datei kann ein beliebiges Format sein, solange er von Ihrer benutzerdefinierten Bereitstellungsaktion verwendet werden kann. Wir empfehlen, diese Datei lesbar zu machen, damit Sie und andere Nutzer in Ihrer Organisation sie im Release Inspector ansehen können.

    • (Optional) eine Zuordnung aller Metadaten, die Sie einbinden möchten

      Diese Metadaten werden durch das benutzerdefinierte Ziel erstellt. Diese Metadaten werden für den Release im Feld custom_metadata gespeichert.

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

Beispiel für eine Datei mit Renderingergebnissen

Das folgende Beispiel zeigt die Ausgabe einer results.json-Datei aus einer benutzerdefinierten Renderingaktion:

{
  "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 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-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 bestimmt ist.

  • 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 von Cloud Deploy-Features, die der benutzerdefinierte Container unterstützen muss. Diese Variable wird anhand der in Ihrer Bereitstellungspipeline konfigurierten Features ausgefüllt.

    Wenn deine Implementierung die in dieser Liste aufgeführten Funktionen nicht unterstützt, sollte beim Rendern ein Fehler auftreten.

    Bei Standardbereitstellungen ist dieses Feld leer. Für Canary-Deployments ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY lautet, wird die Renderingaktion für jede Canary-Phase 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, die diesem Bereitstellungsvorgang zugeordnet ist. Wenn die Umgebungsvariable CLOUD_DEPLOY_FEATURES auf CANARY gesetzt ist, wird Ihre benutzerdefinierte Bereitstellungsaktion für jede Phase aufgerufen und diese Variable auf den Canary-Prozentsatz für jede Phase 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 voraussichtlich 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 in dem von Cloud Deploy bereitgestellten Cloud Storage-Bucket befinden (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

Die Datei muss Folgendes enthalten:

  • Ein Hinweis auf den Erfolgs- oder Fehlerstatus der benutzerdefinierten Bereitstellungsaktion.

    Folgende Status sind gültig:

    • SUCCEEDED

    • FAILED

    • SKIPPED (für Canary-Bereitstellungen, bei denen Canary-Phasen übersprungen werden, um direkt zu stable zu gelangen)

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

    Der Pfad ist der vollständige URI. Sie füllen ihn teilweise mit dem Wert des CLOUD_DEPLOY_OUTPUT_GCS_PATH, der von Cloud Deploy bereitgestellt wird.

    Die hier aufgeführten Dateien werden als Bereitstellungsartefakte in Jobausführungsressourcen dargestellt.

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

    Mit dieser Nachricht wird der failure_message bei der Jobausführung für diese Bereitstellungsaktion ausgefüllt.

  • (Optional) eine Überspringungsmeldung, um zusätzliche Informationen bereitzustellen, wenn die Aktion den Status SKIPPED zurückgibt.

  • (Optional) eine Zuordnung aller Metadaten, die Sie einbinden möchten

    Diese Metadaten werden durch das benutzerdefinierte Ziel erstellt. Diese Metadaten werden bei der Jobausführung und beim Roll-out im Feld custom_metadata gespeichert.

Wenn Sie die Datei results.json beispielsweise für die Fehlerbehebung untersuchen müssen, finden Sie den Cloud Storage-URI dafür in den Renderinglogs des Cloud Build-Release.

Beispiel für Bereitstellungsergebnisdatei

Das folgende Beispiel zeigt 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 von benutzerdefinierten Zieltypen 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 für die Ausführung in einem Google Kubernetes Engine-Cluster konfigurieren.

Remote-wiederverwendbare Skaffold-Konfigurationen verwenden

Wie in diesem Dokument beschrieben, konfigurieren Sie Ihre benutzerdefinierte Aktion in der Datei skaffold.yaml, die beim Erstellen des Release bereitgestellt wird. Sie können Skaffold-Konfigurationen aber auch in einem Git-Repository oder in einem Cloud Storage-Bucket speichern und von der Definition des benutzerdefinierten Zieltyps aus darauf verweisen. So können Sie benutzerdefinierte Aktionen verwenden, die an einem gemeinsamen, gemeinsamen Speicherort definiert und gespeichert werden, anstatt die benutzerdefinierten Aktionen in die skaffold.yaml-Datei jedes Releases aufzunehmen.

Benutzerdefinierte Ziele und Bereitstellungsstrategien

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

Cloud Deploy unterstützt Canary-Deployments, solange der benutzerdefinierte Renderer und Bereitsteller das Canary-Feature unterstützen.

Sie müssen eine benutzerdefinierte Canary-Konfiguration verwenden. Automatisierte und benutzerdefiniert automatisierte Canarys werden nicht unterstützt.

Benutzerdefinierte Ziele und Bereitstellungsparameter

Sie können Bereitstellungsparameter mit benutzerdefinierten Zielen verwenden. Sie können sie in der Bereitstellungspipeline-Phase, auf dem Ziel, das einen benutzerdefinierten Zieltyp verwendet, oder auf dem Release 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 Beispielen für benutzerdefinierte Zielimplementierungen. Folgende Beispiele sind verfügbar:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Jedes Beispiel enthält eine Kurzanleitung.

Diese Beispiele sind kein unterstütztes Google Cloud-Produkt und nicht durch einen Google Cloud-Supportvertrag abgedeckt. Wenn Sie Fehler in einem Google Cloud-Produkt melden oder Funktionen anfragen möchten, wenden Sie sich an den Google Cloud-Support.

Nächste Schritte