In diesem Dokument wird beschrieben, wie benutzerdefinierte Ziele in Cloud Deploy funktionieren.
Cloud Deploy unterstützt verschiedene Laufzeiten Umgebungen als Ziele. Aber die Liste der Die unterstützten Zieltypen sind endlich. Mit benutzerdefinierten Zielen können Sie unterstützten Laufzeiten.
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 Folgendes beschrieben: wie Sie einen benutzerdefinierten Zieltyp definieren und als Ziel einer Bereitstellungspipeline.
Was gehört in ein benutzerdefiniertes Ziel?
Jedes benutzerdefinierte Ziel besteht aus den folgenden Komponenten:
Benutzerdefinierte Aktionen, definiert in
skaffold.yaml
Die Vorgehensweise ähnelt der Definition von Bereitstellungs-Hooks. Im
skaffold.yaml
-Datei können SiecustomActions
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.
Das benutzerdefinierte Rendering ist optional. Sie müssen jedoch eine erstellen, es sei denn, Das benutzerdefinierte Ziel funktioniert korrekt, wenn es von
skaffold render
gerendert wird, Standardeinstellung für Cloud Deploy.Eine Definition des benutzerdefinierten Zieltyps
Die
CustomTargetType
ist eine Cloud Deploy-Ressource, die identifiziert die benutzerdefinierten Aktionen (separat in Ihrenskaffold.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 derCustomTargetType
.
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 Ziele.
Erforderliche Ein- und Ausgaben
Jeder für Cloud Deploy definierte benutzerdefinierte Zieltyp muss folgende Anforderungen erfüllen: Anforderungen für Ein- und Ausgabe, sowohl für Rendering als auch für Bereitstellung. 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 werden, als Umgebungsvariablen. In den folgenden Abschnitten werden diese Eingaben sowie die Ausgaben, die Ihre benutzerdefinierten Render- 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.
Eingaben für Renderingaktionen
Für benutzerdefinierte Renderingaktionen bietet Cloud Deploy Folgendes: erforderlichen Eingaben als Umgebungsvariablen. 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 Zieltyps.
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 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 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 Wert von Cloud DeployCANARY
lautet, ist Ihre Renderingaktion für jede Phase in der Canary-Version aufgerufen. Der Canary-Prozentsatz für jede Phase in der UmgebungsvariableCLOUD_DEPLOY_PERCENTAGE_DEPLOY
angegeben.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
Der Prozentsatz der Bereitstellung, der diesem Renderingvorgang zugeordnet ist. Wenn die Die Umgebungsvariable
CLOUD_DEPLOY_FEATURES
ist aufCANARY
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 diestable
-Phase erreicht haben, ist dies100
.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 Renderingaktion muss die in dieser
. 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:Gibt den Erfolgs- oder Fehlerstatus der benutzerdefinierten Aktion an.
Gültige Werte sind
SUCCEEDED
undFAILED
.Optional: alle Fehlermeldungen, die durch die benutzerdefinierte 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 bereitstellen, auch wenn sie leer ist. Die Dateien können ein beliebiges Format haben, die von Ihrer benutzerdefinierten Bereitstellungsaktion genutzt werden können. Wir empfehlen, diese Datei manuell zu bearbeiten damit Sie und andere Nutzer in Ihrer Organisation diese im Release Inspector.
(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.
Beispiel für eine Datei mit Renderingergebnissen
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 bietet Cloud Deploy Folgendes: erforderlichen Eingaben als Umgebungsvariablen:
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 den für das der benutzerdefinierte Ausrichtungstyp 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, das das benutzerdefinierte Ziel verwendet Typ.
CLOUD_DEPLOY_PHASE
Die Einführungsphase dem 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 vom benutzerdefinierten die der 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 Wert von Cloud DeployCANARY
lautet, ist Ihre Renderingaktion für jede Phase in der Canary-Version aufgerufen. Der Canary-Prozentsatz für jede Phase in der UmgebungsvariableCLOUD_DEPLOY_PERCENTAGE_DEPLOY
angegeben.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
Der Prozentsatz der Bereitstellung, die diesem Bereitstellungsvorgang zugeordnet ist. Wenn die Die Umgebungsvariable
CLOUD_DEPLOY_FEATURES
ist aufCANARY
festgelegt, Ihre benutzerdefinierte wird für jede Phase aufgerufen und diese Variable Canary-Prozentsatz für jede Phase. 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 den gerenderten Renderer geschrieben hat Konfigurationsdateien.
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:
SUCCEEDED
FAILED
SKIPPED
(für Canary-Deployments, bei denen Canary-Phasen werden übersprungen um direkt nachstable
zu gelangen.)
(Optional) eine Liste der Bereitstellungsartefaktdateien in der Form Cloud Storage-Pfade
Der Pfad ist der vollständige URI. Sie füllen sie teilweise mit dem Wert der Eigenschaft
CLOUD_DEPLOY_OUTPUT_GCS_PATH
bereitgestellt von Cloud Deploy:Die hier aufgeführten Dateien haben Ressourcen für Jobausführungen wenn Artefakte bereitgestellt werden.
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
Das folgende Beispiel zeigt die Ausgabe einer results.json
-Datei aus einer benutzerdefinierten Bereitstellung
Aktion:
{
"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. Konfiguration nicht möglich 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 vollständig unterstützt für Standard-Bereitstellungen.
Cloud Deploy unterstützt Canary-Deployments, sofern der Parameter benutzerdefinierte Renderer und Deployer unterstützen die Canary-Funktion.
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 an Ihre benutzerdefinierten Rendering- und Bereitstellungscontainer übergeben: Umgebungsvariablen nutzen, bereits bereitgestellte Elemente.
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
Sie wissen nun, was benutzerdefinierte Ziele sind. Im Folgenden erfahren Sie, wie Sie konfigurieren und verwenden.
Kurzanleitung: Benutzerdefinierten Zieltyp definieren und verwenden
Informationen zu Ausführungsumgebungen für Cloud Deploy