Parameter an die Bereitstellung übergeben

Mit Cloud Deploy können Sie Parameter für Ihre Release übergeben. Diese Werte werden dem Manifest oder den Manifesten bereitgestellt, bevor sie auf die jeweiligen Ziele angewendet werden. Diese Ersetzung erfolgt nach dem rendered von Manifesten als letzter Schritt des Cloud Deploy-Rendervorgangs. 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 Ihrer Cloud Deploy-Bereitstellungspipeline oder in der Zielkonfiguration oder beim Erstellen eines Releases festlegen.

In diesem Artikel wird beschrieben, wie Sie das tun.

Vorteile von Bereitstellungsparametern

Ein typischer Anwendungsfall ist das Zuweisen unterschiedlicher Werte zu Manifesten für verschiedene Ziele bei einer parallelen Bereitstellung. Sie können Bereitstellungsparameter jedoch für alles verwenden, was eine Schlüssel/Wert-Paar-Ersetzung nach dem Rendern im Manifest erfordert.

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 dem Manifest die Platzhalter hinzu und geben Sie für jeden einen Standardwert an.

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

      Dafür gibt es drei Möglichkeiten, die hier beschrieben werden.

  2. Wenn Sie einen Release erstellen, wird Ihr Manifest rendered.

    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. Das Rendern erfolgt durch Skaffold.

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

    Beim Erstellen eines Releases werden alle Bereitstellungsparameter in einem Dictionary kompiliert, das zum Ersetzen von Werten verwendet wird, bevor die Manifeste angewendet werden.

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

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

    Beim Rendering-Prozess 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 Ziellaufzeit angewendet, um Ihre Anwendung bereitzustellen.

    Dazu gehören die Werte, die zur Renderzeit ersetzt werden, und die Werte für alle Bereitstellungsparameter.

Verschiedene Möglichkeiten zum Übergeben von Werten

Sie haben drei Möglichkeiten, Parameter und Werte für diese Parameter anzugeben:

  • In der Definition der Bereitstellungspipeline

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

  • Über die Befehlszeile beim Erstellen eines Releases

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

    Mit dieser Methode können Sie einen Wert bei der Erstellung des Release ersetzen und ihn auf die Manifeste aller betroffenen Ziele anwenden.

Die Konfiguration wird hier ausführlicher beschrieben.

Kann ich mehrere dieser Methoden verwenden?

Ja, Sie können Bereitstellungsparameter in der Pipelinephase, in der Zielkonfiguration und in der Befehlszeile angeben. Das Ergebnis ist, dass alle Parameter akzeptiert und dem Dictionary 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.

Wie unterscheidet sich das von Manifestvorlagen?

Bereitstellungsparameter, wie in diesem Artikel beschrieben, unterscheiden sich von Platzhaltern in einem Manifest mit Vorlage durch die Syntax. Wenn Sie sich fragen, warum Sie Bereitstellungsparameter benötigen, anstatt nur die Standardtechniken für Manifeste mit Vorlagen zu verwenden, finden Sie in der folgenden Tabelle die verschiedenen Zwecke:

Verfahren Zeit der Auswechslung Gilt für
Manifestvorlage Rendering-Phase Bestimmter Release, bestimmtes Ziel
Über die Befehlszeile Nach dem Rendern Bestimmter Release; alle Ziele
In der Bereitstellungspipeline Nach dem Rendern Alle Veröffentlichungen; bestimmte Ziele (nach Label)
Im Zielbereich Nach dem Rendern Alle Releases; bestimmtes Ziel

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

Beschränkungen

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

  • Ein untergeordnetes Ziel kann zusätzlich bis zu 50 Parameter vom übergeordneten Multi-Ziel übernehmen. Die Ziele dürfen insgesamt maximal 200 Parameter haben, einschließlich der Parameter, die in der Pipelinephase festgelegt sind.

  • Der Schlüsselname darf maximal 63 Zeichen lang sein 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 Ein- und Ausgaben.

  • Das Präfix CLOUD_DEPLOY_ ist reserviert und kann nicht für einen Schlüsselnamen verwendet werden.

  • Es ist nicht möglich, zwei Schlüssel mit demselben Namen auf dasselbe Ziel anzuwenden.

  • Der Wert darf leer sein, hat aber eine maximale Länge von 512 Zeichen.

  • Platzhalter für Bereitstellungsparameter können nicht für Helm-Konfigurationswerte verwendet werden, müssen aber konventionsgemäß ü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 dem 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 in der YAML-Datei für den Dienst (für Cloud Run) fügen Sie Platzhalter für alle Werte ein, die nach dem Rendern ersetzt werden sollen.

Syntax

Für Releases, bei denen nicht der Helm-Renderer mit Skaffold verwendet wird, verwenden Sie 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 in der YAML-Datei des Cloud Run-Dienstes.

  • DEFAULT_VALUE

    Ein Wert, der verwendet werden soll, wenn für dieses Attribut 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: weist Cloud Deploy darauf hin, dass ein deploy-parameters-Platzhalter folgt.

  • ${VAR_NAME}

    Ist der zu ersetzende Platzhalter. Dieser Wert muss mit dem Schlüssel eines Schlüssel/Wert-Paars übereinstimmen, das in der Bereitstellungspipeline oder Zielkonfiguration oder beim Erstellen der Version angegeben wird.

Sie können auch mehrere Parameter in einer einzelnen Zeile verwenden und die Parameter als Teil eines längeren Strings einsetzen, 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 Bereitstellungspipelinephase 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 zur Renderzeit als --set-Argumente an Helm übergeben. Eine Änderung Ihrer skaffold.yaml ist nicht erforderlich.

Wenn Sie beispielsweise mit skaffold.yaml ein Helm-Diagramm installieren, für das ein Konfigurationsparameter webserver.port erforderlich ist, um den Port anzugeben, auf dem der Webserver gestartet wird, 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 also nicht nur auf Helm-Vorlagen in Ihrem skaffold.yaml verweisen, sondern sie auch erstellen, können Sie die Standard-Helm-Variablensyntax von {{ .Values.VAR_NAME }} in Ihren Helm-Vorlagen verwenden.

Wenn wir beispielsweise einen Bereitstellungsparameter vom Typ webserver.port konfiguriert haben, könnten wir 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 Fortschritt der Bereitstellungspipeline Schlüssel/Wert-Paare hinzufügen. Dies 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 deployParameters für die entsprechende Pipelinestufe enthalten ist.

    Das folgende YAML ist die Konfiguration für eine Pipeline-Phase, 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 deployParameters-Abschnitt zwei values-Abschnitte, die jeweils Folgendes enthalten:

    • Der Variablenname, der mit dem Namen der Variable übereinstimmt, die Sie im Manifest festgelegt haben

    • Ein Wert für diese Variable

    • Ein oder mehrere Labels (optional), die mit zielgruppenspezifischen Labels abgeglichen werden sollen

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

  3. Wenn Sie matchTargetLabels angegeben haben , müssen Sie auch Labels für die Ziele angeben, damit sie zugeordnet werden können. So können Sie ermitteln, welchem untergeordneten Zielvorhaben welcher Wert zugewiesen werden soll.

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

    Wenn Sie matchTargetLabels weglassen, wird die values, die Sie für die Pipeline festlegen, 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 zur Bereitstellungszeit 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 standardmäßig auf example2 festgelegt.

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

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

    • Der Schlüsselname, der mit dem Namen des Schlüssels (der Variablen) übereinstimmt, 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.

    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 den Bereitstellungsparametern einer Pipelinephase abgeglichen werden muss.

    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, sofern sie die zugehörigen Schlüssel enthalten.

Parameter beim Erstellen eines Releases übergeben

So übergeben Sie Parameter und Werte an die Version:

  1. Konfigurieren Sie Ihr Kubernetes-Manifest oder Ihre Cloud Run-Dienstdefinition mit einem Parameter anstelle des Werts, den Sie zur Bereitstellungszeit 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 der Commit-SHA als Variable namens ${git-sha} festgelegt. Ein Wert dafür wird beim Erstellen der Version mit der Option --deploy-parameters= übergeben, wie im nächsten Schritt zu sehen ist.

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

  2. Wenn Sie eine Version erstellen, fügen Sie dem Befehl gcloud deploy releases create die Option --deploy-parameters hinzu.

    --deploy-parameters enthält 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.

Parameter mit benutzerdefinierten Zielen bereitstellen

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

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

CLOUD_DEPLOY_customTarget_[VAR_NAME]

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

Bereitstellungsparameter mit Bereitstellungshooks bereitstellen

Sie können jeden Bereitstellungsparameter als Umgebungsvariable in Bereitstellungshooks verwenden.

Parameter mit Bereitstellungsüberprüfung bereitstellen

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

Alle Parameter für einen Release ansehen

Sie können die Parameter aufrufen, die für eine bestimmte Veröffentlichung festgelegt wurden. Sie werden in einer Tabelle auf der Seite Release-Details und in der Befehlszeile (gcloud deploy releases describe) angezeigt.

  1. Klicken Sie auf der Hauptseite von Cloud Deploy auf die Lieferpipeline, die das Release enthält, das Sie aufrufen möchten.

  2. Wählen Sie auf der Seite Release-Details den Tab Artefakte aus.

Alle für diese Version festgelegten Bereitstellungsparameter werden in einer Tabelle angezeigt. In einer Spalte sind der Variablenname und der Wert aufgeführt, in der anderen das oder die betroffenen Ziele.

Parameter und Werte bereitstellen, die in der Google Cloud Console angezeigt werden

Nächste Schritte