Mit Cloud Deploy können Sie Parameter für Ihren Release übergeben. Diese Werte werden dem Manifest oder den Manifesten bereitgestellt, bevor diese Manifeste auf die jeweiligen Ziele angewendet werden. Diese Ersetzung erfolgt im letzten Schritt des Cloud Deploy-Renderingvorgangs, nachdem Manifeste gerendert wurden. Werte werden an alle in der Datei skaffold.yaml angegebenen Manifeste gesendet, die die entsprechenden Platzhalter enthalten.
Sie müssen lediglich Platzhalter in Ihr Manifest einfügen und die Werte für diese Platzhalter entweder in der Bereitstellungspipeline oder Zielkonfiguration von Cloud Deploy oder beim Erstellen eines Release festlegen.
In diesem Artikel erfahren Sie, wie Sie das tun können.
Vorteile von Bereitstellungsparametern
Ein typischer Anwendungsfall wäre die Anwendung verschiedener Werte auf Manifeste für verschiedene Ziele in einer parallelen Bereitstellung. Sie können aber Bereitstellungsparameter für alle Zwecke verwenden, für die in Ihrem Manifest das Ersetzen von Schlüssel/Wert-Paaren nach dem Rendering erforderlich ist.
Funktionsweise
In den folgenden Schritten wird das allgemeine Verfahren zum Konfigurieren von Bereitstellungsparametern und Bereitstellen von Werten beschrieben:
Die Bereitstellungsparameter werden wie hier beschrieben konfiguriert.
Der Support umfasst
Füge die Platzhalter zu deinem Manifest hinzu.
Fügen Sie Werte für diese Platzhalter hinzu.
Dafür gibt es drei hier beschriebene Möglichkeiten.
Wenn Sie einen Release erstellen, wird Ihr Manifest gerendert.
Wenn Sie mit einer Manifestvorlage beginnen, werden jetzt Werte auf Vorlagenvariablen angewendet. Wenn Sie mit einem Rohmanifest beginnen, bleibt es unverändert. Das Rendering wird von Skaffold durchgeführt.
Ihr Manifest kann jedoch zusätzliche Variablen enthalten, für die beim Rendering keine Werte angewendet werden. Dies sind die in diesem Dokument beschriebenen Bereitstellungsparameter.
Beim Erstellen des Release werden alle Bereitstellungsparameter in einem Wörterbuch kompiliert, das die Werte vor dem Anwenden der Manifeste ersetzt.
Nach dem Rendering ersetzt Cloud Deploy Werte durch Bereitstellungsparameter.
Das sind die Werte, die Sie im ersten Schritt konfiguriert haben.
Im Renderingprozess wurden bereits Werte auf Manifestvorlagen angewendet, einige Werte wurden ersetzt und für Cloud Deploy spezifische Labels hinzugefügt. Die Werte für diese Bereitstellungsparameter werden jedoch nach dem Rendering ersetzt. Die Unterschiede zwischen Manifestvorlagen und Bereitstellungsparametern werden hier beschrieben.
Das Manifest wird auf die Ziellaufzeit angewendet, um Ihre Anwendung bereitzustellen.
Dies schließt die Werte, die zum Zeitpunkt des Renderings ersetzt werden, sowie die Werte für alle Bereitstellungsparameter ein.
Verschiedene Möglichkeiten zum Übergeben von Werten
Sie können Parameter und Werte für diese Parameter auf drei Arten angeben:
In der Definition der Bereitstellungspipeline
Sie geben den Parameter und seinen Wert in der Definition für eine Phase der Auslieferungspipeline an. Der Parameter wird an das durch diese Phase repräsentierte Ziel übergeben. Wenn diese Phase auf ein Multi-Ziel verweist, werden die hier festgelegten Werte für alle untergeordneten Ziele verwendet.
Mit dieser Methode können Sie einen Wert für alle Releases in einer bestimmten Pipeline und für alle betroffenen Ziele ersetzen. Die für eine Phase definierten Parameter identifizieren ein Label. Das entsprechende Ziel für diese Phase muss ein übereinstimmendes Label haben.
-
Sie konfigurieren den Parameter und seinen Wert in der Definition für das Ziel selbst. Mit dieser Methode können Sie einen Wert für dieses Ziel für alle Releases ersetzen.
In der Befehlszeile, wenn Sie einen Release erstellen
Fügen Sie den Parameter und seinen Wert mit dem Flag
--deploy-parametersim Befehlgcloud deploy releases createein.Mit dieser Methode können Sie einen Wert zum Zeitpunkt der Release-Erstellung ersetzen und ihn auf die Manifeste aller betroffenen Ziele anwenden.
Die entsprechende Konfiguration wird hier ausführlicher erläutert.
Kann ich mehrere dieser Methoden verwenden?
Ja, Sie können Bereitstellungsparameter in der Pipelinephase, in der Zielkonfiguration und in der Befehlszeile einfügen. Das führt dazu, dass alle Parameter akzeptiert und dem Wörterbuch hinzugefügt werden. Wenn ein bestimmter Parameter jedoch an mehreren Stellen, aber mit unterschiedlichen Werten übergeben wird, schlägt der Befehl gcloud deploy releases
create mit einem Fehler fehl.
Parameter mit benutzerdefinierten Zielen bereitstellen
Sie können beliebige Bereitstellungsparameter als Umgebungsvariablen in benutzerdefinierten Zielen verwenden. Verwenden Sie dabei die syntax, die für benutzerdefinierte Ziele angegeben ist.
Wie unterscheidet sich dies von Manifestvorlagen?
Bereitstellungsparameter, wie in diesem Artikel beschrieben, unterscheiden sich durch die syntax von Platzhaltern in einem Manifestvorlage. Wenn Sie sich jedoch fragen, warum Sie Bereitstellungsparameter benötigen, anstatt nur die Standardtechniken für Manifestvorlagen zu verwenden, zeigt die folgende Tabelle die verschiedenen Zwecke:
| Verfahren | Ersetzungszeit | Gilt für |
|---|---|---|
| Manifestvorlage | Rendering phase | Bestimmter Release; bestimmtes Ziel |
| In der Befehlszeile | Post-Rendering | Bestimmter Release; alle Ziele |
| Bei der Bereitstellungspipeline | Post-Rendering | Alle Releases; bestimmte Ziele (nach Label) |
| Entspricht Ziel | Post-Rendering | Alle Releases, bestimmtes Ziel |
In diesem Dokument geht es nur um Bereitstellungsparameter (für die Befehlszeile, die Pipeline und das Ziel), nicht um Manifestdateien.
Beschränkungen
Für jeden Parametertyp können maximal 25 Parameter erstellt werden.
Ein untergeordnetes Ziel kann zusätzlich bis zu 25 Parameter vom übergeordneten Multi-Ziel übernehmen, bis zu 100 Parameter für die Ziele, einschließlich der Parameter, die in der Pipelinephase festgelegt wurden.
Der Schlüsselname ist auf maximal 63 Zeichen beschränkt und der folgende reguläre Ausdruck verwendet:
^[a-zA-Z0-9][-A-Za-z0-9_.]{0,61}[a-zA-Z0-9]$Eine Ausnahme hiervon ist, wenn Sie einen Bereitstellungsparameter als Umgebungsvariable in einem benutzerdefinierten Ziel verwenden, müssen Sie zwischen dem Suchbegriff
customTargetund dem Variablennamen (customTarget/VAR_NAME) einen Schrägstrich verwenden. Die unterstützte Syntax finden Sie unter Erforderliche Ein- und Ausgaben.Das Präfix
CLOUD_DEPLOY_ist reserviert und kann nicht für einen Schlüsselnamen verwendet werden.Zwei Schlüssel mit demselben Namen können nicht auf dasselbe Ziel angewendet werden.
Der Wert kann leer sein, hat aber maximal 512 Zeichen.
Bereitstellungsparameter konfigurieren
In diesem Abschnitt wird beschrieben, wie Sie Bereitstellungsparameterwerte konfigurieren, die auf Ihr Kubernetes-Manifest, Ihren Cloud Run-Dienst oder Ihre Helm-Vorlage angewendet werden.
Neben der Konfiguration dieser Schlüssel/Wert-Paare müssen Sie Ihrem Manifest den Platzhalter oder die Platzhalter hinzufügen, wie in diesem Abschnitt beschrieben.
Platzhalter zum Manifest hinzufügen
Im Kubernetes-Manifest (für GKE) oder in der Dienst-YAML-Datei (für Cloud Run) fügen Sie Platzhalter für alle Werte hinzu, die Sie nach dem Rendering ersetzen möchten.
Syntax
Verwenden Sie bei Releases, in denen nicht der Helm-Renderer mit Skafold verwendet wird, die folgende Syntax für Platzhalter:
[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}
In dieser Zeile...
PROPERTY:
Das Konfigurationsattribut in Ihrem Kubernetes-Manifest oder in der YAML-Datei für den Cloud Run-Dienst.
DEFAULT_VALUE
Ist ein Wert, der verwendet werden soll, wenn für dieses Attribut in der Befehlszeile, in der Pipeline oder der Zielkonfiguration keine Werte angegeben sind.
# from-param:
Verwendet ein Kommentarzeichen, um die Cloud Deploy-Anweisung
deploy-parametersauszulösen, undfrom-param:weist Cloud Deploy an, dass eindeploy-parameters-Platzhalter folgt.${VAR_NAME}
Ist der zu ersetzende Platzhalter. Er muss mit dem Schlüssel eines Schlüssel/Wert-Paars übereinstimmen, das in der Bereitstellungspipeline oder Zielkonfiguration oder bei der Releaseerstellung bereitgestellt wird.
Helm-spezifische Syntax
Wenn Sie den Helm-Renderer mit Skaffold verwenden, nutzen Sie die folgende Syntax in Ihrer Helm-Vorlage, um Platzhalter hinzuzufügen:
[PROPERTY]: {{ .Values.VAR_NAME }}
Parameter zur Pipelinephase hinzufügen
Sie können einer Phase in der Bereitstellungspipeline Schlüssel/Wert-Paare hinzufügen. Dies ist nützlich bei parallelen Bereitstellungen, um zwischen untergeordneten Zielen zu unterscheiden.
Fügen Sie Ihrem Kubernetes-Manifest oder Ihrem Cloud Run-Dienst die Platzhalter wie hier beschrieben hinzu.
Beispiel:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: replicas: 1 # from-param: ${deploy_replicas} selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.14.2 ports: - containerPort: 80Konfigurieren Sie die Bereitstellungspipeline so, dass sie
deployParametersfür die entsprechende Pipelinephase enthält.Die folgende YAML-Datei ist die Konfiguration für eine Pipelinephase, deren Ziel ein Multi-Ziel ist, das in diesem Fall zwei untergeordnete Ziele hat:
serialPipeline: stages: - targetId: dev profiles: [] - targetId: prod # multi-target profiles: [] deployParameters: - values: deploy_replicas: 1 log_level: "NOTICE" matchTargetLabels: # optional, applies to all resources if unspecified; AND'd my-app: "post-render-config-1" - values: deploy_replicas: 2 log_level: "WARNING" matchTargetLabels: # optional, applies to all resources if unspecified; AND'd my-app: "post-render-config-2"In dieser Bereitstellungspipeline-Konfiguration enthält die Stanza
deployParameterszweivalues, die jeweils Folgendes enthalten:Den Variablennamen. Dies ist der gleiche Name wie die Variable, die Sie im Manifest festgelegt haben.
Ein Wert für diese Variable
Ein oder mehrere Labels (optional) für den Abgleich mit zielspezifischen Labels
Wenn Sie in einer
matchTargetLabels-Stanza kein Label angeben, wird dieser Wert für alle Ziele in der Phase verwendet.
Wenn Sie
matchTargetLabelsangegeben haben , müssen Sie auch Labels für die Ziele angeben, damit sie abgeglichen werden können. Auf diese Weise können Sie ermitteln, welcher Wert welchem untergeordneten Ziel zugewiesen werden soll.Das Ziel muss mit allen Labels übereinstimmen, die in der Stanza
valuesfestgelegt sind.Wenn Sie
matchTargetLabelsweglassen, werden die in der Pipeline festgelegtenvaluesauf alle untergeordneten Ziele angewendet. Wenn Sie jedoch mehr als einen Wert für denselben Parameter festlegen, schlägt der Release fehl.
Nachdem jedes Manifest gerendert wurde, fügt Cloud Deploy dem gerenderten Manifest den Wert für jede Variable hinzu.
Parameter zur Zielkonfiguration hinzufügen
Sie können einem Ziel Schlüssel/Wert-Paare hinzufügen. Wenn Sie Bereitstellungsparameter verwenden, um zwischen mehreren untergeordneten Zielen zu unterscheiden, konfigurieren Sie sie für diese untergeordneten Ziele und nicht für die Multi-Ziele.
Konfigurieren Sie das Kubernetes-Manifest oder die Cloud Run-Dienstdefinition mit einem Parameter anstelle des Werts, den Sie bei der Bereitstellung festlegen möchten.
Beispiel:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.14.2 env: - name: envvar1 value: example1 # from-param: ${application_env1} - name: envvar2 value: example2 # from-param: ${application_env2}In diesem Manifest ist der Parameter
envvar1auf den Standardwertexample1undenvvar2auf den Standardwertexample2festgelegt.Konfigurieren Sie Ihre Ziele so, dass sie
deployParametersenthalten.Für jeden aufgenommenen Parameter geben Sie Folgendes an:
Der Schlüsselname. Dabei handelt es sich um denselben Namen wie der Schlüssel (Variable), den Sie im Manifest festgelegt haben.
Ein Wert für diesen Schlüssel. Wenn Sie keinen Wert angeben, wird der im Manifest festgelegte Standardwert verwendet.
Die folgende YAML-Datei enthält die Konfiguration für zwei Ziele. Jedes Ziel enthält eine
deployParameters-Stanza, die einen Wert festlegt. Jedes Ziel enthält auch ein Label, das mit Bereitstellungsparametern abgeglichen wird, die in einer Pipelinephase konfiguriert wurden.apiVersion: deploy.cloud.google.com/v1beta1 kind: Target metadata: name: prod1 labels: my-app: "post-render-config-1" description: development cluster deployParameters: application_env1: "newValue1" --- apiVersion: deploy.cloud.google.com/v1beta1 kind: target metadata: name: prod2 labels: my-app: "post-render-config-2" description: development cluster deployParameters: application_env1: "newValue2"
Beim Erstellen des Release, aber nach dem Rendern der Manifeste, fügt Cloud Deploy diese Werte den gerenderten Manifesten hinzu, sofern sie die zugehörigen Schlüssel enthalten.
Parameter beim Erstellen des Release übergeben
So übergeben Sie Parameter und Werte an den Release:
Konfigurieren Sie das Kubernetes-Manifest oder die Cloud Run-Dienstdefinition mit einem Parameter anstelle des Werts, den Sie bei der Bereitstellung festlegen möchten.
Beispiel:
apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: selector: matchLabels: app: nginx template: metadata: labels: app: nginx annotations: commit: defaultShaValue # from-param: ${git-sha} spec: containers: - name: nginx image: nginx:1.14.2In diesem Beispiel wird der Commit-SHA als Variable namens
${git-sha}festgelegt. Ein Wert hierfür wird beim Erstellen des Release mit der Option--deploy-parameters=übergeben, wie im nächsten Schritt beschrieben.Die Syntax für diese Variable lautet
$plus dem Variablennamen in geschweiften Klammern. In diesem Beispiel ist das${git-sha}.Fügen Sie beim Erstellen eines Release die Option
--deploy-parametersin den Befehlgcloud deploy releases createein.--deploy-parametersverwendet eine durch Kommas getrennte Liste von Schlüssel/Wert-Paaren, wobei der Schlüssel der Platzhalter ist, den Sie dem Manifest hinzugefügt haben.Der Befehl sieht in etwa so aus:
gcloud deploy releases create test-release-001 \ --project=my-example-project \ --region=us-central1 \ --delivery-pipeline=my-params-demo-app-1 \ --images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \ --deploy-parameters="git-sha=f787cac"
Wenn der Release erstellt wird, aber nach dem Rendern des Manifests, stellt Cloud Deploy die Werte für die gerenderten Manifeste bereit, sofern diese die zugehörigen Schlüssel enthalten.
Alle Parameter für einen Release ansehen
Sie können sich die Parameter ansehen, die für einen bestimmten Release festgelegt wurden. Sie werden in einer Tabelle auf der Seite Releasedetails und in der Befehlszeile (gcloud deploy releases describe) angezeigt.
Klicken Sie auf der Hauptseite von Cloud Deploy auf die Bereitstellungspipeline, die den gewünschten Release enthält.
Wählen Sie auf der Seite Release-Details den Tab Artefakte aus.
Alle Bereitstellungsparameter, die für diesen Release festgelegt wurden, werden in einer Tabelle mit dem Variablennamen und -wert in einer Spalte und dem betroffenen Ziel bzw. den betroffenen Zielen in der anderen Spalte angezeigt.
