Parameter an Ihr Deployment übergeben

Mit Cloud Deploy können Sie Parameter für Ihr Release übergeben. Diese Werte werden dem Manifest oder den Manifesten bereitgestellt, bevor diese Manifeste auf ihre jeweiligen Ziele angewendet werden. Diese Ersetzung erfolgt nachdem die Manifeste gerendert wurden, als letzter Schritt im Cloud Deploy-Rendervorgang. Werte werden für alle Manifeste bereitgestellt, die in Ihrer skaffold.yaml-Datei identifiziert wurden und die entsprechenden Platzhalter enthalten.

Sie müssen lediglich Platzhalter in Ihr Manifest einfügen und die Werte für diese Platzhalter entweder in der Cloud Deploy-Bereitstellungspipeline oder in der Zielkonfiguration oder beim Erstellen eines Release festlegen.

In diesem Artikel wird beschrieben, wie Sie das tun.

Warum Bereitstellungsparameter verwenden?

Ein typischer Anwendungsfall wäre, verschiedene Werte auf Manifeste für verschiedene Ziele in einer parallelen Bereitstellung anzuwenden. Sie können Bereitstellungsparameter aber für alles verwenden, bei dem nach dem Rendern eine Ersetzung von Schlüssel/Wert-Paaren in Ihrem Manifest erforderlich ist.

Funktionsweise

In den folgenden Schritten wird der allgemeine Prozess zum Konfigurieren von Bereitstellungsparametern und zum Bereitstellen von Werten beschrieben:

1. Sie konfigurieren die Bereitstellungsparameterisierung wie hier beschrieben .

   Der Support umfasst

   • Fügen Sie die Platzhalter in Ihr Manifest ein, einschließlich eines Standardwerts für jeden Platzhalter.

   • Fügen Sie Werte für diese Platzhalter hinzu.

     Es gibt drei Möglichkeiten, dies zu tun, die hier beschrieben werden.

2. Wenn Sie ein Release erstellen, wird Ihr Manifest gerendert.

   Wenn Sie mit einem Manifest auf Vorlagenbasis beginnen, werden jetzt Werte für Vorlagenvariablen angewendet. Wenn Sie mit einem Rohmanifest beginnen, bleibt es unverändert. Dieses Rendern wird von Skaffold ausgeführt.

   Sie können jedoch zusätzliche Variablen in Ihrem Manifest haben, für die beim Rendern keine Werte angewendet werden. Das sind die Bereitstellungsparameter, die in diesem Dokument beschrieben werden.

   Beim Erstellen des Release werden alle Bereitstellungsparameter in ein Dictionary kompiliert, das verwendet wird, um Werte zu ersetzen, bevor die Manifeste angewendet werden.

   Hinweis: Wenn einem bestimmten Bereitstellungsparameter (Schlüssel) mehr als ein Wert zugewiesen ist, schlägt das Release fehl.

3. Nach dem Rendern ersetzt Cloud Deploy die Werte für Bereitstellungsparameter.

   Das sind die Werte, die Sie im ersten Schritt konfiguriert haben.

   Beim Rendern wurden bereits Werte auf Manifestvorlagen angewendet, einige Werte wurden ersetzt und Cloud Deploy-spezifische Labels wurden hinzugefügt. Die Werte für diese Bereitstellungsparameter werden jedoch nach dem Rendern ersetzt. Die Unterschiede zwischen Manifestvorlagen und Bereitstellungsparametern werden hier beschrieben.

4. Das Manifest wird auf die Ziel-Laufzeitumgebung angewendet, um Ihre Anwendung bereitzustellen.

   Dazu gehören die Werte, die beim Rendern ersetzt wurden, und die Werte für alle Bereitstellungsparameter.

Verschiedene Möglichkeiten zum Übergeben von Werten

Sie können Parameter und Werte für diese Parameter auf drei Arten bereitstellen:

• In der Definition der Bereitstellungspipeline

  Sie geben den Parameter und seinen Wert in der Definition für eine Phase im Bereitstellungspipeline-Ablauf an. Der Parameter wird an das Ziel übergeben, das durch diese Phase dargestellt wird. 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 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.

• In der Zieldefinition

  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 ein Release erstellen

  Sie fügen den Parameter und seinen Wert mit dem Flag --deploy-parameters im Befehl gcloud deploy releases create ein.

  Mit dieser Methode können Sie einen Wert beim Erstellen des Release ersetzen und diesen Wert auf die Manifeste aller betroffenen Ziele anwenden.

Die Konfiguration für diese wird hier ausführlicher erläutert hier.

Kann ich mehr als eine dieser Methoden verwenden?

Ja, Sie können Bereitstellungsparameter in der Pipelinephase, in der Zielkonfiguration und in der Befehlszeile einfügen. Alle Parameter werden akzeptiert und dem Dictionary hinzugefügt. 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.

Worin besteht der Unterschied zu Manifestvorlagen?

Bereitstellungsparameter, wie in diesem Artikel beschrieben, unterscheiden sich von Platzhaltern in einem Manifest auf Vorlagenbasis durch die Syntax. Wenn Sie sich jedoch fragen, warum Sie Bereitstellungsparameter benötigen, anstatt nur die Standardtechniken für Manifeste auf Vorlagenbasis zu verwenden, zeigt die folgende Tabelle die verschiedenen Zwecke:

Verfahren	Auswechslung	Gilt für
Manifestvorlage	Rendern	Bestimmtes Release; bestimmtes Ziel
In der Befehlszeile	Nach dem Rendern	Bestimmtes Release; alle Ziele
In der Bereitstellungspipeline	Nach dem Rendern	Alle Releases; bestimmte Ziele (nach Label)
Im Ziel	Nach dem Rendern	Alle Releases; bestimmtes Ziel

In diesem Dokument geht es nur um Bereitstellungsparameter (in der Befehlszeile, Pipeline und Ziel), nicht um Manifeste auf Vorlagenbasis.

Beschränkungen

• Für jeden Parametertyp können Sie maximal 50 Parameter erstellen.

• Ein untergeordnetes Ziel kann zusätzlich bis zu 50 Parameter von seinem übergeordneten Multi-Ziel übernehmen, bis zu maximal 200 Parameter für die Ziele, einschließlich der in der Pipelinephase festgelegten Parameter.

• Der Schlüsselname ist auf maximal 63 Zeichen begrenzt und muss dem folgenden regulären Ausdruck entsprechen:

  ^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$
  

  Eine Ausnahme besteht, wenn Sie einen Bereitstellungsparameter als Umgebungsvariable in einem benutzerdefinierten Ziel verwenden. In diesem Fall müssen Sie einen Schrägstrich zwischen dem Keyword customTarget und dem Variablennamen (customTarget/VAR_NAME) verwenden. 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.

• Auf dasselbe Ziel können nicht zwei Schlüssel mit demselben Namen angewendet werden.

• Der Wert kann leer sein, darf aber maximal 512 Zeichen lang sein.

• Platzhalter für Bereitstellungsparameter können nicht für Helm-Konfigurationswerte, aber müssen konventionell übergeben werden.

Bereitstellungsparameter konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie Werte für Bereitstellungsparameter 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 auch den oder die Platzhalter hinzufügen, wie in diesem Abschnitt beschrieben.

Platzhalter zum Manifest hinzufügen

In Ihrem Kubernetes-Manifest (für GKE) oder der Dienst-YAML-Datei (für Cloud Run) fügen Sie Platzhalter für alle Werte hinzu, die nach dem Rendern ersetzt werden sollen.

Syntax

Verwenden Sie für Releases, die nicht den Helm Renderer mit Skaffold verwenden, die folgende Syntax für Ihre Platzhalter:

[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}

In dieser Zeile...

• PROPERTY:

  Ist die Konfigurationseigenschaft in Ihrem Kubernetes-Manifest oder der Dienst-YAML-Datei von Cloud Run.

• DEFAULT_VALUE

  Ist ein Wert, der verwendet wird, wenn für diese Eigenschaft in der Befehlszeile oder in der Pipeline- oder Zielkonfiguration keine Werte angegeben sind. Der Standardwert ist erforderlich, kann aber ein leerer String ("") sein.

• # from-param:

  Verwendet ein Kommentarzeichen, um die Cloud Deploy-Anweisung deploy-parameters abzugrenzen. from-param: teilt Cloud Deploy mit, dass ein Platzhalter für deploy-parameters folgt.

• ${VAR_NAME}

  Ist der Platzhalter, der ersetzt werden soll. Er muss mit dem Schlüssel eines Schlüssel/Wert-Paars übereinstimmen, das in der Bereitstellungspipeline- oder Zielkonfiguration oder beim Erstellen des Release angegeben wurde.

Sie können auch mehrere Parameter in einer einzelnen Zeile verwenden und die Parameter als Teil eines längeren Strings verwenden, z. B.:

image: my-image # from-param: ${artifactRegion}-docker.pkg.dev/my-project/my-repo/my-image@sha256:${imageSha}

Diese Parameter können aus mehreren Quellen stammen. Im vorherigen Beispiel würde ${artifactRegion} wahrscheinlich in der Ziel- oder Bereitstellungspipeline-Phase definiert, während ${imageSha} beim Erstellen des Release aus der Befehlszeile stammen würde.

Parameter für Helm-Diagrammwerte

Wenn Sie ein Helm-Diagramm rendern, das Konfigurationswerte akzeptiert, und Sie diese Werte mit Bereitstellungsparametern festlegen möchten, müssen die Bereitstellungsparameter Namen haben, die mit den Helm-Konfigurationswerten übereinstimmen, die Sie festlegen möchten. Alle Bereitstellungsparameter werden beim Rendern ohne Änderung Ihrer skaffold.yaml als --set Argumente an Helm übergeben,

Wenn in Ihrer skaffold.yaml-Datei beispielsweise ein Helm-Diagramm installiert wird, das einen Konfigurationsparameter webserver.port verwendet, um anzugeben, an welchem Port der Webserver gestartet werden soll, und Sie diesen dynamisch über einen Bereitstellungsparameter festlegen möchten, müssen Sie einen Bereitstellungsparameter mit dem Namen webserver.port und dem gewünschten Wert für den Webserverport erstellen.

Wenn Sie in Ihrer skaffold.yaml, also nicht nur auf Helm-Vorlagen verweisen, sondern sie auch erstellen, können Sie die Standard-Helm-Variablensyntax von {{ .Values.VAR_NAME }} in Ihren Helm-Vorlagen verwenden.

Wenn beispielsweise ein Bereitstellungsparameter webserver.port konfiguriert ist, können 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 im Bereitstellungspipeline-Ablauf Schlüssel/Wert-Paare hinzufügen. Das ist bei parallelen Bereitstellungen nützlich, um zwischen untergeordneten Zielen zu unterscheiden.

1. Fügen Sie die Platzhalter Ihrem Kubernetes-Manifest oder 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: 80
   

2. Konfigurieren Sie Ihre Bereitstellungspipeline so, dass sie deployParameters für die entsprechende Pipelinephase enthält.

   Das folgende YAML 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 der Abschnitt deployParameters zwei values, die jeweils Folgendes haben:

   • Den Variablennamen, der mit dem Namen der Variablen übereinstimmt, die Sie im Manifest festgelegt haben.

   • Einen Wert für diese Variable.

   • Ein oder mehrere Labels (optional), die mit zielspezifischen Labels übereinstimmen müssen.

     Wenn Sie in einem matchTargetLabels-Abschnitt kein Label angeben, wird dieser Wert für alle Ziele in der Phase verwendet.

3. Wenn Sie matchTargetLabels eingefügt haben , müssen Sie auch Labels für die Ziele einfügen, damit sie übereinstimmen. So legen Sie fest, welcher Wert welchem untergeordneten Ziel zugewiesen werden soll.

   Das Ziel muss mit allen Labels übereinstimmen, die im Abschnitt values festgelegt sind.

   Wenn Sie matchTargetLabels weglassen, werden die in der Pipeline festgelegten values auf alle untergeordneten Ziele angewendet. Wenn Sie jedoch mehr als einen Wert für denselben Parameter festlegen, schlägt das Release fehl.

Nachdem jedes Manifest gerendert wurde, fügt Cloud Deploy den Wert für jede Variable in das gerenderte Manifest ein.

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 das Multi-Ziel.

1. Konfigurieren Sie Ihr Kubernetes-Manifest oder Ihre 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 envvar1 standardmäßig auf example1 und envvar2 auf example2 festgelegt.

2. Konfigurieren Sie Ihre Ziele so, dass sie deployParameters enthalten.

   Für jeden Parameter, den Sie einfügen, geben Sie Folgendes an:

   • Den Schlüsselnamen, der mit dem Namen des Schlüssels (der Variablen) übereinstimmt, den Sie im Manifest festgelegt haben.

   • Einen Wert für diesen Schlüssel. Wenn Sie keinen Wert angeben, wird der im Manifest festgelegte Standardwert verwendet.

   Das folgende YAML ist die Konfiguration für zwei Ziele. Jedes Ziel enthält einen deployParameters-Abschnitt, in dem ein Wert festgelegt wird. Jedes Ziel enthält auch ein Label, das mit Bereitstellungsparametern übereinstimmen muss, 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 das Release erstellt wird, aber nachdem die Manifeste gerendert wurden, fügt Cloud Deploy diese Werte den gerenderten Manifesten hinzu, wenn sie die zugehörigen Schlüssel enthalten.

Parameter beim Erstellen des Release übergeben

So übergeben Sie Parameter und Werte an das Release:

1. Konfigurieren Sie Ihr Kubernetes-Manifest oder Ihre 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.2
   

   In diesem Beispiel wird die Commit-SHA als Variable mit dem Namen ${git-sha} festgelegt. Ein Wert dafür wird beim Erstellen des Release mit der Option --deploy-parameters= übergeben, wie im nächsten Schritt zu sehen.

   Die Syntax für diese Variable ist $ plus der Variablenname in geschweiften Klammern. In diesem Beispiel ist es ${git-sha}.

2. Wenn Sie ein Release erstellen, fügen Sie die Option --deploy-parameters im Befehl gcloud deploy releases create ein.

   --deploy-parameters verwendet 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 das Release erstellt wird, aber nach dem Rendern des Manifests, stellt Cloud Deploy die Werte für die gerenderten Manifeste bereit, wenn sie die zugehörigen Schlüssel enthalten.

Bereitstellungsparameter mit benutzerdefinierten Zielen

Sie können jeden Bereitstellungsparameter als Umgebungsvariable in benutzerdefinierten Zielen verwenden. Verwenden Sie dabei die Syntax für benutzerdefinierte Ziele.

Bereitstellungsparameter, die als Eingaben für benutzerdefinierte Ziele vorgesehen sind, können mit customTarget/ beginnen, z. B. customTarget/vertexAIModel. Wenn Sie dieses Präfix verwenden, verwenden Sie die folgende Syntax, wenn Sie auf einen Bereitstellungsparameter als Umgebungsvariable verweisen:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Dabei ist VAR_NAME der Name nach dem Schrägstrich im Namen des Bereitstellungsparameters. Wenn Sie beispielsweise einen Bereitstellungsparameter mit dem Namen customTarget/vertexAIModel definieren, verweisen Sie darauf als CLOUD_DEPLOY_customTarget_vertexAIModel.

Bereitstellungsparameter mit Bereitstellungshooks

Sie können jeden Bereitstellungsparameter als Umgebungsvariable in Bereitstellungshooksverwenden.

Bereitstellungsparameter mit Bereitstellungsprüfung

Sie können jeden Bereitstellungsparameter als Umgebungsvariable in der Bereitstellungsprüfung verwenden.

Alle Parameter für ein Release ansehen

Sie können die Parameter ansehen, die für ein bestimmtes Release festgelegt wurden. Sie werden in einer Tabelle auf der Seite Releasedetails und in der Befehlszeile (gcloud deploy releases describe) angezeigt.

1. Klicken Sie auf der Hauptseite von Cloud Deploy auf die Bereitstellungspipeline, die das gewünschte Release enthält.

2. Wählen Sie auf der Seite Releasedetails den Tab Artefakte aus.

Alle für dieses Release festgelegten Bereitstellungsparameter werden in einer Tabelle angezeigt, wobei der Variablenname und der Wert in einer Spalte und das betroffene Ziel oder die betroffenen Ziele in der anderen Spalte stehen.

Nächste Schritte

• Kurzanleitung: Bereitstellungsparameter verwenden

• Weitere Informationen zu parallelen Bereitstellungen