Benutzerdefinierte Ziele

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

Cloud Deploy unterstützt verschiedene Laufzeitumgebungen als Ziele. Die Liste der unterstützten Zieltypen ist jedoch endlich. Mit benutzerdefinierten Zielen können Sie Apps nicht nur in den unterstützten Laufzeiten, sondern auch in anderen Systemen bereitstellen.

Ein benutzerdefiniertes Ziel ist ein Ziel, das eine beliebige Ausgabeumgebung darstellt, wobei es sich nicht um eine von Cloud Deploy unterstützte Laufzeit handelt.

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

Was wird in ein benutzerdefiniertes Ziel aufgenommen?

Jedes benutzerdefinierte Ziel besteht aus den folgenden Komponenten:

• Benutzerdefinierte Aktionen, in skaffold.yaml definiert

  Diese ähneln der Definition von Bereitstellungs-Hooks. In der Datei skaffold.yaml definieren Sie customActions. Dabei definiert jede benutzerdefinierte Aktion das zu verwendende Container-Image und die Befehle, die für diesen Container ausgeführt werden sollen.

  Auf diese Weise 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 Werte, die von Cloud Deploy bereitgestellt werden, und müssen eine Reihe von erforderlichen Ausgaben erfüllen.

  Die benutzerdefinierte Renderingaktion ist optional, aber Sie müssen eine erstellen, es sei denn, Ihr benutzerdefiniertes Ziel funktioniert ordnungsgemäß, wenn es durch skaffold render gerendert wird. Dies ist die Standardeinstellung für Cloud Deploy.

• Definition eines benutzerdefinierten Zieltyps

  Die CustomTargetType ist eine Cloud Deploy-Ressource, die die benutzerdefinierten Aktionen identifiziert (separat in der skaffold.yaml definiert), die dieses Typ für Aktivitäten zum Rendern und Roll-out-Bereitstellung verwenden.

• Eine Zieldefinition

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

Sobald diese Komponenten vorhanden sind, können Sie das Ziel wie jedes andere Ziel verwenden, es auf den Verlauf Ihrer Bereitstellungspipeline verweisen und Cloud Deploy-Funktionen wie Hochstufung und Genehmigungen sowie Rollbacks in vollem Umfang nutzen.

Beispiel

Im Schnellstart Benutzerdefinierten Zieltyp definieren und verwenden wird ein benutzerdefinierter Zieltyp erstellt, der einfache Befehle zum Ausführen in einem Container-Image enthält – einen Befehl für das Rendering und einen für das Deployment. Mit den Befehlen wird in diesem Fall einfach den erforderlichen Ausgabedateien Text zum Rendern und Bereitstellen hinzugefügt.

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

Erforderliche Ein- und Ausgaben

Jeder für Cloud Deploy definierte benutzerdefinierte Zieltyp muss die Anforderungen an die Ein- und Ausgabe erfüllen, sowohl für das Rendering als auch für die Bereitstellung. 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 Rendering und die Bereitstellung 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 vorgesehen sind, 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 mit dem Namen customTarget/vertexAIModel definieren, verweisen Sie mit CLOUD_DEPLOY_customTarget_vertexAIModel darauf.

Eingaben zum Rendern von Aktionen

Für benutzerdefinierte Renderingaktionen stellt Cloud Deploy die folgenden erforderlichen Eingaben als Umgebungsvariablen bereit. Für mehrphasige Rollouts (Canary-Bereitstellungen) stellt Cloud Deploy diese Variablen für jede Phase zur Verfügung.

• 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, das den benutzerdefinierten Zieltyp verwendet.

• CLOUD_DEPLOY_PHASE

  Die Einführungsphase, 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 Features ausgefüllt, die in Ihrer Bereitstellungspipeline konfiguriert wurden.

  Falls die Implementierung die Funktionen in dieser Liste nicht unterstützt, sollte sie beim Rendern fehlschlagen.

  Bei Standardbereitstellungen ist dieser Wert leer. Bei Canary-Bereitstellungen ist der Wert CANARY. Lautet der von Cloud Deploy bereitgestellte Wert CANARY, wird die Renderingaktion für jede Phase in der Canary-Phase aufgerufen. Der Canary-Prozentsatz für jede Phase wird in der Umgebungsvariablen 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 Phase stable erreicht haben, ist dies 100.

• CLOUD_DEPLOY_STORAGE_TYPE

  Der Storage-Anbieter. Immer GCS.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  Der Cloud Storage-Pfad für das Renderingdateiarchiv, das beim Erstellen des Release geschrieben wurde.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  Der Cloud Storage-Pfad, in dem der benutzerdefinierte Renderingcontainer Artefakte hochlädt, die für die Bereitstellung verwendet werden sollen. Für die 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 bereitstellen. Die Informationen müssen in der Ergebnisdatei namens results.json enthalten sein. Sie befindet sich im von Cloud Deploy bereitgestellten Cloud Storage-Bucket.

• Gerenderte Konfigurationsdatei(en)

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

  • Der Status „Erfolg“ oder „Fehlgeschlagen“ der benutzerdefinierten Aktion.

    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 ihn teilweise mithilfe des CLOUD_DEPLOY_OUTPUT_GCS_PATH-Werts aus, der von Cloud Deploy bereitgestellt wird.

    Sie müssen die gerenderte Konfigurationsdatei angeben, auch wenn sie leer ist. Der Inhalt der Datei kann ein beliebiges Format in jedem Format haben, solange die Datei 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 im Release Inspector ansehen können.

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

Beispiel für eine Datei mit Rendering-Ergebnissen

Im Folgenden sehen Sie eine exemplarische results.json-Dateiausgabe einer benutzerdefinierten Renderingaktion:

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

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

  Bei der benutzerdefinierten 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 Features ausgefüllt, die in Ihrer Bereitstellungspipeline konfiguriert wurden.

  Falls die Implementierung die Funktionen in dieser Liste nicht unterstützt, sollte sie beim Rendern fehlschlagen.

  Bei Standardbereitstellungen ist dieser Wert leer. Bei Canary-Bereitstellungen ist der Wert CANARY. Lautet der von Cloud Deploy bereitgestellte Wert CANARY, wird die Renderingaktion für jede Phase in der Canary-Phase aufgerufen. Der Canary-Prozentsatz für jede Phase wird in der Umgebungsvariablen 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 die benutzerdefinierte Bereitstellungsaktion für jede Phase aufgerufen und diese Variable auf den Canary-Prozentsatz für jede Phase festgelegt. Die Bereitstellungsaktion muss für jede Phase ausgeführt werden.

• CLOUD_DEPLOY_STORAGE_TYPE

  Der Storage-Anbieter. 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

Die benutzerdefinierte Bereitstellungsaktion muss eine results.json-Ausgabedatei schreiben. Diese Datei muss sich im 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 Statusangaben sind gültig:

  • SUCCEEDED

  • FAILED

  • SKIPPED (für Canary-Deployments, 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 von Cloud Deploy bereitgestellten CLOUD_DEPLOY_OUTPUT_GCS_PATH aus.

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

• (Optional) Eine Fehlermeldung, wenn die benutzerdefinierte Bereitstellungsaktion nicht erfolgreich war und der Status FAILED zurückgegeben wird.

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

• (Optional) Eine Nachricht zum Überspringen mit zusätzlichen Informationen, wenn die Aktion den Status SKIPPED zurückgibt.

Wenn Sie die Datei results.json prüfen möchten, um beispielsweise Fehler zu beheben, finden Sie den entsprechenden Cloud Storage-URI in den Renderinglogs der Cloud Build-Version.

Beispiel für eine Datei mit Bereitstellungsergebnissen

Im Folgenden sehen Sie eine Beispieldatei für die results.json-Datei, die von einer benutzerdefinierten Bereitstellungsaktion ausgegeben wird:

{
  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: ""
}

Weitere Informationen zu benutzerdefinierten Aktionen

Beim Einrichten und Verwenden benutzerdefinierter Zieltypen ist Folgendes zu beachten.

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.

Wiederverwendbare Remote-Skaffold-Konfigurationen verwenden

Wie in diesem Dokument beschrieben, konfigurieren Sie die benutzerdefinierte Aktion in der Datei skaffold.yaml, die beim Erstellen des Release bereitgestellt wird. Sie können Skaffel-Konfigurationen aber auch in einem Git-Repository oder in einem Cloud Storage-Bucket speichern und in Ihrer benutzerdefinierten Zieltypdefinition darauf verweisen. So können Sie benutzerdefinierte Aktionen verwenden, die an einem einzigen, gemeinsam genutzten 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 der Bereitsteller die Canary-Funktion unterstützen.

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

Benutzerdefinierte Ziele und Bereitstellungsparameter

Sie können Bereitstellungsparameter mit benutzerdefinierten Zielen verwenden. Sie können sie in der Phase der Bereitstellungspipeline, für das Ziel, das einen benutzerdefinierten Zieltyp verwendet, oder im 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-sample-Repository enthält eine Reihe von beispielhaften benutzerdefinierten Zielimplementierungen. Folgende Beispiele sind verfügbar:

• GitOps

• Vertex AI

• Terraform

• Infrastructure Manager

• Helm

Jedes Beispiel enthält eine Kurzanleitung.

Diese Beispiele gehören nicht zu den unterstützten Google Cloud-Produkten und sind nicht durch einen Google Cloud-Supportvertrag abgedeckt. Wenn Sie Fehler in einem Google Cloud-Produkt melden oder Features anfordern möchten, wenden Sie sich an den Google Cloud-Support.

Nächste Schritte

• Sie haben nun benutzerdefinierte Ziele kennengelernt. Hier erfahren Sie, wie Sie diese konfigurieren und verwenden.

• Kurzanleitung: Benutzerdefinierten Zieltyp definieren und verwenden

• Weitere Informationen zum Konfigurieren von Cloud Deploy-Zielen

• Informationen zu Ausführungsumgebungen von Cloud Deploy