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 ihre jeweiligen Ziele angewendet werden. Diese Ersetzung erfolgt nach dem Rendering von Manifesten. Dies ist der letzte Schritt im Renderingvorgang von Cloud Deploy. Werte werden für alle Manifeste bereitgestellt, die in der skaffold.yaml-Datei angegeben sind und die entsprechenden Platzhalter enthalten.
Sie müssen lediglich Platzhalter in Ihr Manifest einfügen und die Werte für diese Platzhalter entweder in Ihrer Cloud Deploy-Bereitstellungspipeline oder in der Zielkonfiguration oder beim Erstellen eines Release festlegen.
In diesem Artikel erfahren Sie, wie das funktioniert.
Vorteile von Bereitstellungsparametern
Ein typischer Anwendungsfall ist die Anwendung verschiedener Werte auf Manifeste für verschiedene Ziele in einer parallelen Bereitstellung. Sie können jedoch Bereitstellungsparameter für alles verwenden, bei dem in Ihrem Manifest Schlüssel/Wert-Paare nach dem Rendering ersetzt werden müssen.
Funktionsweise
In den folgenden Schritten wird der allgemeine Prozess zum Konfigurieren von Bereitstellungsparametern und zum Bereitstellen von Werten beschrieben:
Die Bereitstellungsparametrisierung wird wie hier beschrieben konfiguriert.
Der Support umfasst
Fügen Sie Ihrem Manifest die Platzhalter hinzu.
Fügen Sie Werte für diese Platzhalter hinzu.
Dafür gibt es drei Möglichkeiten, die hier beschrieben werden.
Wenn Sie einen Release erstellen, wird das Manifest gerendert.
Wenn Sie mit einer Manifest-Vorlage beginnen, werden Werte jetzt auf Vorlagenvariablen angewendet. Wenn Sie mit einem Raw-Manifest beginnen, bleibt es unverändert. Dieses Rendering erfolgt von Skaffold.
Sie können Ihrem Manifest jedoch zusätzliche Variablen hinzufügen, 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 ein Wörterbuch kompiliert, das vor dem Anwenden der Manifeste Werte ersetzt.
Nach dem Rendering ersetzt Cloud Deploy die Bereitstellungsparameter durch Werte.
Dies sind die Werte, die Sie im ersten Schritt konfiguriert haben.
Beim Rendering wurden bereits Werte auf Manifestvorlagen angewendet, wodurch einige Werte ersetzt und Cloud Deploy-spezifische Labels hinzugefügt wurden. 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.
Dazu gehören die Werte, die zum Zeitpunkt des Renderings ersetzt wurden, sowie die Werte für etwaige Bereitstellungsparameter
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 Bereitstellungspipeline an. Der Parameter wird an das in dieser Phase dargestellte 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 und 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.
Über die Befehlszeile beim Erstellen eines Release
Sie fügen den Parameter und seinen Wert mit dem Flag
--deploy-parametersin den Befehlgcloud deploy releases createein.Mit dieser Methode können Sie einen Wert beim Erstellen des Release ersetzen und auf diese 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 Ergebnis ist, dass alle Parameter akzeptiert und dem Wörterbuch hinzugefügt werden. Wenn jedoch ein bestimmter Parameter an mehr als einer Stelle, jedoch 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 jeden Bereitstellungsparameter als Umgebungsvariablen in benutzerdefinierten Zielen verwenden. Verwenden Sie dabei die für benutzerdefinierte Ziele angegebene syntax.
Wie unterscheidet sich das von Manifestvorlagen
Bereitstellungsparameter, wie in diesem Artikel beschrieben, unterscheiden sich durch die syntax von Platzhaltern in einem Manifest mit Vorlagen. Wenn Sie sich jedoch fragen, warum Sie Parameter bereitstellen müssen, anstatt nur die Standardtechniken für Manifestvorlagen zu verwenden, sehen Sie in der folgenden Tabelle die verschiedenen Zwecke:
| Verfahren | Ersetzungszeit | Gilt für |
|---|---|---|
| Manifestvorlage | Rendering phase | Spezifischer Release; spezifisches Ziel |
| Über die Befehlszeile | Nach dem Rendern | Bestimmter Release; alle Ziele |
| Pipeline für die Bereitstellung | Nach dem Rendern | Alle Releases; spezifische Ziele (nach Label) |
| Entspricht Ziel | Nach dem Rendern | Alle Releases; bestimmtes Ziel |
In diesem Dokument geht es nur um Bereitstellungsparameter (in Befehlszeile, Pipeline und Ziel), nicht um Manifestvorlagen.
Beschränkungen
Für jeden Parametertyp können maximal 25 Parameter erstellt werden.
Ein untergeordnetes Ziel kann zusätzlich bis zu 25 Parameter von seinem übergeordneten Mehrfachziel übernehmen, bis zu 100 Parameter für die Ziele, einschließlich der Parameter, die in der Pipelinephase festgelegt wurden.
Der Schlüsselname und der folgende reguläre Ausdruck sind auf maximal 63 Zeichen beschränkt:
^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$Eine Ausnahme besteht darin, dass Sie bei Verwendung eines Bereitstellungsparameters als Umgebungsvariable in einem benutzerdefinierten Ziel einen Schrägstrich zwischen dem Schlüsselwort
customTargetund dem Variablennamen (customTarget/VAR_NAME) verwenden müssen. Informationen zur unterstützten Syntax finden Sie unter Erforderliche Eingaben 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.
Platzhalter für Bereitstellungsparameter können nicht für Helm-Konfigurationswerte verwendet werden, müssen jedoch gemäß der Konvention übergeben werden.
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 den Platzhalter bzw. die Platzhalter zu Ihrem Manifest hinzufügen, wie in diesem Abschnitt beschrieben.
Platzhalter zum Manifest hinzufügen
Fügen Sie im Kubernetes-Manifest (für GKE) oder im Dienst-YAML-Code (für Cloud Run) Platzhalter für alle Werte hinzu, die Sie nach dem Rendering ersetzen möchten.
Syntax
Verwenden Sie für Releases, in denen der Helm-Renderer mit Skaffold nicht verwendet wird, die folgende Syntax für die Platzhalter:
[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}
In dieser Zeile...
PROPERTY:
Ist das Konfigurationsattribut in Ihrem Kubernetes-Manifest oder in der YAML-Datei des Cloud Run-Dienstes.
DEFAULT_VALUE
Ist ein Wert, der verwendet werden soll, wenn in der Befehlszeile, der Pipeline oder der Zielkonfiguration keine Werte für dieses Attribut angegeben sind.
# from-param:
Verwendet ein Kommentarzeichen, um die Cloud Deploy-Anweisung
deploy-parametersauszulösen, undfrom-param:teilt Cloud Deploy mit, dass eindeploy-parameters-Platzhalter folgt.${VAR_NAME}
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 angegeben ist.
Parameter für Helm-Diagrammwerte
Wenn Sie ein Helm-Diagramm rendern, in dem Konfigurationswerte akzeptiert werden, und Sie diese Werte mithilfe von Bereitstellungsparametern festlegen möchten, müssen die Namen der Bereitstellungsparameter den festzulegenden Helm-Konfigurationswerten entsprechen.
Alle Bereitstellungsparameter werden zum Zeitpunkt des Renderings als --set-Argumente an Helm übergeben, ohne dass eine Änderung von skaffold.yaml erforderlich ist.
Wenn Ihre skaffold.yaml beispielsweise ein Helm-Diagramm installiert, das den Konfigurationsparameter webserver.port verwendet, um anzugeben, an welchem Port der Webserver beginnt, und Sie dies dynamisch über einen Bereitstellungsparameter festlegen möchten, müssen Sie einen Bereitstellungsparameter mit dem Namen webserver.port mit dem Wert erstellen, den Sie für den Webserverport verwenden möchten.
Wenn Sie in skaffold.yaml nicht nur auf Helm-Vorlagen verweisen, sondern auch diese erstellen, können Sie die Standardsyntax der Helm-Variable von {{ .Values.VAR_NAME }} in Ihren Helm-Vorlagen verwenden.
Wenn beispielsweise der Bereitstellungsparameter webserver.port konfiguriert ist, könnten Sie ihn so verwenden:
apiVersion: apps/v1
kind: Deployment
metadata:
name: webserver
spec:
replicas: 3
selector:
matchLabels:
app: webserver
template:
metadata:
labels:
app: webserver
spec:
containers:
- name: webserver
image: gcr.io/example/webserver:latest
ports:
- containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
name: web
env:
- name: WEBSERVER_PORT
value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
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 die Platzhalter zu Ihrem Kubernetes-Manifest oder zum Cloud Run-Dienst hinzu, wie hier beschrieben.
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
deployParameters-Stanza zweivalues, von denen jede Folgendes hat:Der Variablenname, also den gleichen Namen 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 kein Label in einer
matchTargetLabels-Stanza angeben, wird dieser Wert für alle Ziele in der Phase verwendet.
Wenn Sie
matchTargetLabelseingeschlossen haben , müssen Sie auch Labels für die Ziele angeben, damit sie abgeglichen werden können. Auf diese Weise bestimmen Sie, welcher Wert welchem untergeordneten Ziel zugewiesen werden soll.Das Ziel muss mit allen Labels übereinstimmen, die in der
values-Stanza festgelegt sind.Wenn Sie
matchTargetLabelsweglassen, werden dievalues, die Sie für die Pipeline festgelegt haben, auf 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 den Wert für jede Variable dem gerenderten Manifest 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 diese für diese untergeordneten Ziele und nicht für die Multi-Ziele.
Konfigurieren Sie das Kubernetes-Manifest oder die Cloud Run-Dienstdefinition mithilfe eines Parameters anstelle des Werts, den Sie zum Zeitpunkt 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
deployParameterseingeschlossen ist.Für jeden einzuschließenden Parameter geben Sie Folgendes an:
Der Schlüsselname. Dies ist der Name des Schlüssels (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 ist 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"
Wenn der Release erstellt wird, 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
Führen Sie die folgenden Schritte aus, um Parameter und Werte an den Release zu übergeben:
Konfigurieren Sie das Kubernetes-Manifest oder die Cloud Run-Dienstdefinition mithilfe eines Parameters anstelle des Werts, den Sie zum Zeitpunkt 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 ist das Commit-SHA als Variable namens
${git-sha}festgelegt. Ein Wert dafür wird beim Erstellen des Release mit der Option--deploy-parameters=übergeben, wie im nächsten Schritt dargestellt.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"
Beim Erstellen des Release, aber nach dem Rendern des Manifests, stellt Cloud Deploy die Werte für die gerenderten Manifeste bereit, sofern sie 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ähle auf der Seite Release-Details den Tab Artefakte aus.
Alle Bereitstellungsparameter, die für diesen Release festgelegt wurden, werden in einer Tabelle angezeigt. Der Variablenname und -wert wird in einer Spalte und das betroffene Ziel bzw. die betroffenen Ziele in der anderen Spalte angezeigt.
