Benutzerdefiniertes Ziel erstellen

In diesem Dokument wird beschrieben, wie Sie einen benutzerdefinierten Cloud Deploy-Zieltyp erstellen und diesen als Ziel in einer Bereitstellungspipeline von Cloud Deploy verwenden.

Im Folgenden sehen Sie den übergeordneten Prozess zum Erstellen eines benutzerdefinierten Zieltyps und dessen Verwendung in Ihrer Bereitstellungspipeline:

Erstellen Sie eine oder mehrere Containeranwendungen mit den Funktionen zur Bereitstellung für Ihr benutzerdefiniertes Ziel und die die Anforderungen von Cloud Deploy für benutzerdefinierte Zieltypen erfüllen.
Definieren Sie eine benutzerdefinierte Aktion in skaffold.yaml, die auf diesen Container verweist und die Befehle angibt, die für den Container ausgeführt werden sollen.
Erstellen Sie eine CustomTargetType-Definition, die auf die benutzerdefinierte Aktion aus dem vorherigen Schritt verweist, und registrieren Sie sie als Cloud Deploy-Ressource.
Definieren Sie ein neues Ziel mit einer customTarget-Eigenschaft, die den neuen benutzerdefinierten Zieltyp identifiziert.
Verweisen Sie auf dieses Ziel im Fortschritt der Bereitstellungspipeline.
Release erstellen

Jeder dieser Schritte wird im weiteren Verlauf dieses Dokuments ausführlich beschrieben.

Containeranwendungen erstellen

Die Funktionalität zum Bereitstellen für Ihr benutzerdefiniertes Ziel wird in Containeranwendungen definiert, die Sie Cloud Deploy durch Verweisen auf Ihre skaffold.yaml-Datei bereitstellen. Wenn Ihre Bereitstellungspipeline ein Ziel enthält, das einen benutzerdefinierten Zieltyp verwendet, ruft Cloud Deploy die Container für benutzerdefinierte Aktionen auf, die für diesen benutzerdefinierten Zieltyp in Skaffold definiert wurden, um die von Ihnen definierten Rendering- und Bereitstellungsaktionen auszuführen.

Das Verhalten Ihrer Anwendungen ist Ihre Entscheidung. Er muss jedoch die von Cloud Deploy bereitgestellten Eingabeumgebungsvariablen verarbeiten und die erforderlichen Ausgaben zurückgeben.

In den meisten Fällen erstellen Sie für jeden benutzerdefinierten Zieltyp, den Sie erstellen, einen Container für die Renderingaktion und einen für die Bereitstellungsaktion. Die Renderingaktion ist optional, aber wenn Sie keine angeben, verwendet Cloud Deploy den Standardwert skaffold render.

Benutzerdefinierte Aktionen in Skaffold definieren

Nachdem Sie die Container-Images für benutzerdefinierte Aktionen eingerichtet haben, verweisen Sie sie in der skaffold.yaml-Konfigurationsdatei darauf.

Sie konfigurieren jede benutzerdefinierte Aktion für ein benutzerdefiniertes Ziel in einer customActions-Stanza. Für jeden benutzerdefinierten Zieltyp erstellen Sie in Skaffold eine benutzerdefinierte Aktion für das Rendering und eine für die Bereitstellung. Die CustomTargetType-Definition gibt an, welche benutzerdefinierte Aktion für das Rendering und welche für die Bereitstellung verwendet wird.

Im Folgenden finden Sie die Konfiguration für benutzerdefinierte Rendering- und Bereitstellungsaktionen in skaffold.yaml:

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

In dieser Skaffold-Konfiguration:

customActions.name

Ist ein beliebiger Name für die benutzerdefinierte Rendering- oder Bereitstellungsaktion. Die Definition CustomTargetType verweist im Attribut renderAction oder deployAction auf diesen Namen.
Die Stanza containers enthält Ihre Referenz und Befehle zum Ausführen dieses Containers.

Die Stanza containers lässt mehr als einen Container zu, Google empfiehlt jedoch, nur einen zu verwenden.
customActions.containers.name

Ist ein beliebiger Name für den Container, den Sie für diese Aktion verwenden. Als Best Practice sollte dieser Containername immer SHA-qualifiziert sein.
image

Ist der Pfad zum Container-Image.
command

Der oder die Befehle, die im Container ausgeführt werden sollen.
args

Ist eine Sammlung von Argumenten für command.

Eine ausführliche Dokumentation zu den Konfigurationsattributen, die in customActions verwendet werden, finden Sie in der Skaffold-YAML-Referenz.

Benutzerdefinierten Zieltyp festlegen

Sie definieren ein benutzerdefiniertes Ziel, indem Sie zuerst mithilfe der CustomTargetType-Konfiguration einen benutzerdefinierten Zieltyp erstellen. Sie können die CustomTargetType in derselben Datei wie die Definition Ihrer Bereitstellungspipeline, mit Zieldefinitionen oder in einer separaten Datei erstellen.

Die CustomTargetType-Definition sieht so aus:

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

CUSTOM_TARGET_TYPE_NAME

Ist ein beliebiger Name, den Sie dieser benutzerdefinierten Zieltypdefinition geben. Auf diesen Namen wird in der Zieldefinition für jedes Ziel verwiesen, das den von Ihnen definierten benutzerdefinierten Zieltyp verwendet.
RENDER_ACTION_NAME

Ist der Name der benutzerdefinierten Renderingaktion. Dieser Wert ist der in skaffold.yaml für die Renderingaktion definierte customAction.name.
DEPLOY_ACTION_NAME

Ist der Name der benutzerdefinierten Bereitstellungsaktion. Dieser Wert ist der in skaffold.yaml für die deploy definierte customAction.name.
includeSkaffoldModules

Ist eine optionale Stanza, die verwendet werden kann, wenn Sie Remote-Skatffold-Konfigurationen verwenden. Die Attribute in dieser Stanza werden im Abschnitt Remote-Stanza-Konfigurationen verwenden angezeigt.

Remote-Saffold-Konfigurationen verwenden

Sie können Skaffold-Konfigurationen in einem öffentlichen Git-Repository oder in einem Cloud Storage-Bucket speichern und in Ihrer Definition des benutzerdefinierten Zieltyps auf diese Konfigurationen verweisen.

Wenn Sie Remote-Skaffold-Konfigurationen verwenden, müssen für skaffold.yaml, die Sie zum Zeitpunkt der Veröffentlichung angeben, die benutzerdefinierten Aktionen nicht definiert sein. So können Sie benutzerdefinierte Aktionen in Ihrer gesamten Organisation freigeben.

So verwenden Sie Skaffold-Remote-Konfigurationen:

Erstellen Sie eine Skaffold-Konfiguration mit Ihrer benutzerdefinierten Aktion oder Ihren benutzerdefinierten Aktionen.
Speichern Sie die Konfiguration in einem Git-Repository oder in einem Cloud Storage-Bucket.
Fügen Sie in die Definition des benutzerdefinierten Zieltyps eine customActions.includeSkaffoldModules-Stanza hinzu.
Geben Sie unter includeSkaffoldModules Folgendes an:
- Optional ein oder mehrere configs-Elemente:
  
  - configs: ["name1", "name2"]
  
  Der Wert von configs ist eine Liste von Strings, die dem Attribut metadata.name in jeder einzuschließenden Skaffold-Konfiguration entsprechen. Wenn keine Angabe erfolgt, verwendet Cloud Deploy alle Konfigurationen im angegebenen Pfad.
- Entweder eine googleCloudStorage-Stanza oder eine git-Stanza.
  
  Für Cloud Storage:
```
googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME
```
  Für Git:
```
git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME
```
  Wobei:
  
  PATH_TO_GCS_BUCKET ist der Pfad zu einem Cloud Storage-Verzeichnis mit /*, in dem die Skaffold-Konfigurationen gespeichert sind. Skaffold lädt alle Dateien in diesem Verzeichnis herunter und findet dann die entsprechende Skaffold-Datei mit den Konfigurationen basierend auf dem konfigurierten relativen Pfad.
  
  FILENAME ist der Name der Datei, die die Skaffold-Konfigurationen enthält. Dieses Attribut path: ist optional. Wenn Sie es nicht angeben, wird in Cloud Deploy von skaffold.yaml ausgegangen. Wenn skaffold.yaml nicht vorhanden ist oder der von Ihnen angegebene Dateiname nicht vorhanden ist, schlägt das Erstellen des Release fehl.
  
  REPO_URL ist die URL zum Git-Repository.
  
  PATH_TO_FILE ist der Pfad in diesem Repository zu der Datei, die die Skafold-Konfigurationen enthält.
  
  BRANCH_NAME ist der Name des Zweigs (z. B. main), von dem die Skaffold-Konfigurationen abgerufen werden.

Beispiel

Die folgende benutzerdefinierte YAML-Datei vom Typ „Ziel“ ist eine customActions-Stanza mit der Stanza includeSkaffoldModules, die auf Skaffold-Konfigurationen verweist, die in einem Cloud Storage-Bucket gespeichert sind:

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

Die folgende YAML-Datei ist eine Skaffold-Konfiguration, auf die die gezeigte benutzerdefinierte Aktion verweist:

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

Benutzerdefinierten Zieltyp registrieren

Nachdem Sie CustomTargetType konfiguriert haben, führen Sie den Befehl gcloud deploy apply aus, um die Ressource CustomTargetType in einem Google Cloud-Projekt zu registrieren:

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

Wobei:

FILE ist der Name der Datei, in der Sie diesen benutzerdefinierten Zieltyp definiert haben.

PROJECT ist das Google Cloud-Projekt, in dem diese Ressource erstellt werden soll. Die CustomTargetType muss sich im selben Projekt wie die Ressource Target befinden, die darauf verweist. Sie müssen das Projekt nicht angeben, wenn Sie es als Standardprojekt für die Google Cloud CLI festgelegt haben.

REGION ist die Region (z. B. us-centra1), in der diese Ressource erstellt werden soll. Die CustomTargetType muss sich in derselben Region befinden wie die Ressource Target, die darauf verweist. Sie müssen die Region nicht angeben, wenn Sie sie als Standardregion für die gcloud CLI festgelegt haben.

Da die CustomTargetType jetzt als Cloud Deploy-Ressource erstellt wurde, können Sie sie jetzt in einer Target-Definition verwenden, um Ihr benutzerdefiniertes Ziel zu erstellen.

Weitere Informationen zur Definition von CustomTargetType finden Sie in der Referenz zum Konfigurationsschema von Cloud Deploy.

Ziel definieren

Der einzige Unterschied zwischen einer Zieldefinition für einen unterstützten Zieltyp und einer benutzerdefinierten Zieldefinition besteht darin, dass die benutzerdefinierte Zieldefinition die Stanza customTarget enthält. Die Syntax für customTarget lautet so:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Dabei ist CUSTOM_TARGET_TYPE_NAME der Wert des Attributs name, das in der Konfiguration des benutzerdefinierten Zieltyps definiert ist.

Ziel zur Bereitstellungspipeline hinzufügen

Sie können ein benutzerdefiniertes Ziel in einer Bereitstellungspipeline genauso wie einen unterstützten Zieltyp verwenden. Das heißt, es gibt keinen Unterschied beim Fortschritt der Bereitstellungspipeline zwischen Zielen eines unterstützten Zieltyps und benutzerdefinierten Zielen.

Alle Ziele in einer Bereitstellungspipeline müssen denselben Zieltyp verwenden. Sie können beispielsweise keine Bereitstellungspipeline haben, bei der einige Ziele in Google Kubernetes Engine bereitgestellt werden und einige benutzerdefinierte Ziele.

Wie bei unterstützten Zieltypen können Sie Bereitstellungsparameter in der Pipelinephase einbeziehen.

Release erstellen

Nachdem Sie Ihren benutzerdefinierten Zieltyp vollständig definiert und ein Ziel für die Verwendung dieses Typs erstellt haben, können Sie jetzt wie gewohnt einen Release erstellen:

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

Beim Erstellen des Release wird Ihre benutzerdefinierte Renderingaktion für jedes Ziel in der Bereitstellungspipeline ausgeführt, einschließlich der Verarbeitung von Bereitstellungsparametern, die für den Release, Ziele oder die Bereitstellungspipeline konfiguriert sind. Cloud Deploy stellt dem benutzerdefinierten Renderingcontainer die Bereitstellungsparameter als Eingabe bereit.

Ausgabe der benutzerdefinierten Ziele ansehen

Wenn Ihre benutzerdefinierte Aktion die Anforderungen für benutzerdefinierte Ziele erfüllt, können Sie die gerenderten Artefakte in der Google Cloud Console ansehen.

Führen Sie die folgenden Schritte aus, um die Ausgabe der benutzerdefinierten Renderingaktion aufzurufen.

Rufen Sie in der Google Cloud Console die Cloud Deploy-Seite Bereitstellungspipelines auf, um Ihre Bereitstellungspipeline anzusehen.

Zur Seite der Lieferpipelines
Klicken Sie auf den Namen Ihrer Bereitstellungspipeline.

Die Pipelinevisualisierung zeigt den Bereitstellungsstatus der Anwendung und Ihr Release wird auf dem Tab Releases unter Details der Bereitstellungspipeline aufgeführt.
Klicken Sie auf den Release-Namen.

Die Seite Releasedetails wird angezeigt.
Klicken Sie auf den Tab Artefakte.
Klicken Sie unter Zielartefakte auf den Pfeil neben Artefakte ansehen.

Die gerenderten Artefakte werden aufgeführt, einschließlich des gerenderten skaffold.yaml und der gerenderten Manifestdatei, die vom benutzerdefinierten Renderer generiert wurde. Außerdem können Sie neben jedem Standort auf den Link Speicherort klicken, um den Cloud Storage-Bucket aufzurufen und diese Dateien anzusehen.

Sie können auch auf den Link Artefakte ansehen klicken, um diese Dateien mithilfe des Release Inspectors nach Release, Ziel oder Phase anzusehen.