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. Aber die Liste der Die unterstützten Zieltypen sind endlich. 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 als eine von Cloud Deploy unterstützte Laufzeit.

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, definiert in skaffold.yaml

    Sie ähneln der Definition von Deployment-Hooks. Im skaffold.yaml-Datei können Sie customActions definieren, in der jede benutzerdefinierte Aktion identifiziert das zu verwendende Container-Image und Befehle, die auf diesem Container ausgeführt werden sollen.

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

    Für jeden benutzerdefinierten Zieltyp können Sie eine benutzerdefinierte Renderingaktion und eine Bereitstellungsaktion. Diese Aktionen verbrauchen Werte, die von Cloud Deploy-Bereitstellung muss eine Gruppe 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 des benutzerdefinierten Zieltyps

    Die CustomTargetType ist eine Cloud Deploy-Ressource, die identifiziert die benutzerdefinierten Aktionen (separat in Ihren skaffold.yaml definiert), die auf Verwendung dieses Typs für Aktivitäten zum Rendern des Release und für die Bereitstellung von Roll-outs.

  • Eine Zieldefinition

    Die Zieldefinition für ein benutzerdefiniertes Ziel ist dieselbe wie für jeden anderen Zieltyp, Es enthält jedoch das Attribut customTarget, dessen Wert der Name ist der CustomTargetType.

Sobald diese Komponenten vorhanden sind, können Sie das Ziel wie jedes andere Ziel verwenden. auf den Fortschritt der Bereitstellungspipeline verweisen und Cloud Deploy-Features wie Hochstufung und Freigaben sowie Rollbacks.

Beispiel

Kurzanleitung Benutzerdefinierten Zieltyp definieren und verwenden erstellt einen benutzerdefinierten Zieltyp, der einfache Befehle enthält, die auf einem Container-Image – ein Befehl zum Rendern und einer zum Bereitstellen. Die Befehle, in diesem Fall einfach Text zu den erforderlichen Ausgabedateien für bereitstellen.

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

Erforderliche Ein- 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. Dieser Abschnitt welche Ein- und Ausgaben erforderlich sind und wie sie bereitgestellt werden.

Cloud Deploy stellt die erforderlichen Eingaben sowohl zum Rendern als auch bereitgestellt wird, als Umgebungsvariablen. 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 Cloud Deploy kann beliebige Werte an Ihre benutzerdefinierten Container übergeben Parameter bereitstellen, die Sie festgelegt haben.

Weitere Informationen

Eingaben für Renderingaktionen

Für benutzerdefinierte Renderaktionen stellt Cloud Deploy die folgenden erforderlichen Eingaben als Umgebungsvariablen bereit. Für mehrstufige Roll-outs (Canary-Deployments) Cloud Deploy stellt 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, das das benutzerdefinierte Ziel verwendet Typ.

  • CLOUD_DEPLOY_PHASE

    Die Einführungsphase dem 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 vom benutzerdefinierten die der 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 Ihnen, dass es beim Rendern fehlschlägt.

    Bei Standardimplementierungen ist dieses Feld leer. Für Canary-Deployments ist der Wert CANARY. Wenn der Wert von Cloud Deploy CANARY lautet, ist Ihre Renderingaktion für jede Phase in der Canary-Version aufgerufen. Der Canary-Prozentsatz für jede Phase in der Umgebungsvariable CLOUD_DEPLOY_PERCENTAGE_DEPLOY angegeben.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    Der Prozentsatz der Bereitstellung, der diesem Renderingvorgang zugeordnet ist. Wenn der Parameter Die Umgebungsvariable CLOUD_DEPLOY_FEATURES ist auf CANARY festgelegt, Ihre benutzerdefinierte wird für jede Phase aufgerufen. Diese Variable wird auf Canary-Prozentsatz für jede Phase. Für Standardbereitstellungen Für 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 Renderingdatei, der beim Release geschrieben wurde wurde erstellt.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Der Cloud Storage-Pfad, unter dem sich der benutzerdefinierte Renderingcontainer befindet Artefakte für die Bereitstellung hochzuladen. Das Rendering Für diese Aktion muss eine Datei mit dem Namen results.json hochgeladen werden, die die Ergebnisse dieser dargestellt wird. Weitere Informationen finden Sie unter Ausgaben der Renderingaktion.

Ausgaben der Renderingaktion

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

  • 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 gerenderte Konfigurationsdatei oder -Dateien.

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

      Sie müssen die gerenderte Konfigurationsdatei angeben, auch wenn sie leer ist. Der Inhalt der Datei kann beliebig und in beliebigem Format sein, 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 Sie einbinden möchten

      Diese Metadaten werden durch das benutzerdefinierte Ziel erstellt. Diese Metadaten werden auf der Release im Feld custom_metadata.

Wenn Sie die Datei results.json z. B. für die Fehlerbehebung untersuchen möchten, gehen Sie folgendermaßen vor: den Cloud Storage-URI in den Cloud Build-Logs finden.

Beispieldatei für Renderergebnisse

Das folgende Beispiel zeigt die Ausgabe der results.json-Datei eines benutzerdefinierten Renderings Aktion:

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

  • CLOUD_DEPLOY_TARGET

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

  • CLOUD_DEPLOY_PHASE

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

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

    Für Standardbereitstellungen: ist das Feld leer. Für Canary-Deployments ist der Wert CANARY. Wenn der von Cloud Deploy bereitgestellte Wert CANARY ist, wird Ihre Renderaktion für jede Phase im Canary aufgerufen. Der Canary-Prozentsatz für jede Phase 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 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 dem sich die benutzerdefinierte Bereitstellung befindet für den Container wird erwartet, dass er Bereitstellungsartefakte hochlädt. 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 Cloud Storage-Bucket befinden, der von Cloud Deploy (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:

  • 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 des CLOUD_DEPLOY_OUTPUT_GCS_PATH bereitgestellt von Cloud Deploy:

    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 nicht erfolgreich ist (FAILED-Status wird zurückgegeben)

    Mit dieser Nachricht werden die failure_message auf der Jobausführung für diese Bereitstellungsaktion.

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

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

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

Wenn Sie die Datei results.json z. B. für die Fehlerbehebung untersuchen möchten, gehen Sie folgendermaßen vor: Cloud Storage-URI dafür im Cloud Build- Render-Logs für die Veröffentlichung.

Beispiel für Bereitstellungsergebnisdatei

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

Hinweise zur Einrichtung und Verwendung der benutzerdefinierten Ausrichtung Typen.

Benutzerdefinierte Aktionen ausführen

Ihre benutzerdefinierten Rendering- und Bereitstellungsaktionen werden in Cloud Deploy ausgeführt Ausführungsumgebung aus. Sie können nicht konfiguriert werden Ihre benutzerdefinierten Aktionen zur Ausführung in einem Google Kubernetes Engine-Cluster.

Remote-wiederverwendbare Skaffold-Konfigurationen verwenden

Wie in diesem Dokument beschrieben, konfigurieren Sie Ihre benutzerdefinierte Aktion in der skaffold.yaml Datei wurde beim Erstellen des Release bereitgestellt. Sie können aber auch Skaffold-Konfigurationen in einem Git-Repository oder in einem Cloud Storage-Bucket und Verweisen Sie in der Definition des benutzerdefinierten Zieltyps darauf. So können Sie benutzerdefinierte Aktionen verwenden, die in einem gemeinsamen, anstatt die benutzerdefinierten Aktionen mit den skaffold.yaml-Datei.

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. Automatisiert und kundenspezifisch automatisiert Canary-Dateien werden nicht unterstützt.

Benutzerdefinierte Ziele und Bereitstellungsparameter

Sie können Bereitstellungsparameter mit benutzerdefinierten Zielen verwenden. Sie können sie in der Bereitstellungspipeline festlegen stage für das Ziel, das benutzerdefinierten Zieltyps oder Release verfügbar.

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. In den folgenden Beispielen 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 die durch einen Google Cloud-Supportvertrag abgedeckt sind. Um Fehler zu melden oder eine Anfrage zu stellen Features eines Google Cloud-Produkts nutzen, wenden Sie sich an Google Cloud Support.

Nächste Schritte