Parameter an die Bereitstellung übergeben

Mit Cloud Deploy können Sie Parameter für Ihre Version übergeben. Diese Werte werden an das Manifest oder die Manifeste übergeben, bevor sie auf die jeweiligen Ziele angewendet werden. Dieser Vorgang erfolgt nach dem Rendering der Manifeste als letzter Schritt beim Cloud Deploy-Renderingvorgang. Werte werden allen Manifesten zugewiesen, die in der Datei skaffold.yaml mit den entsprechenden Platzhaltern gekennzeichnet sind.

Fügen Sie dazu einfach Platzhalter in Ihr Manifest ein und legen Sie die Werte für diese Platzhalter entweder in Ihrer Cloud Deploy-Auslieferungspipeline oder in der Zielkonfiguration oder beim Erstellen einer Version fest.

In diesem Artikel wird beschrieben, wie Sie das tun.

Vorteile von Bereitstellungsparametern

Ein typischer Anwendungsfall hierfür ist die Anwendung verschiedener Werte auf Manifeste für verschiedene Ziele bei einer parallelen Bereitstellung. Sie können Bereitstellungsparameter jedoch für alles verwenden, bei dem nach der Rendering-Phase ein Schlüssel/Wert-Paar in Ihrem Manifest ersetzt werden muss.

Funktionsweise

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

  1. Konfigurieren Sie die Bereitstellungsparametrierung wie hier beschrieben.

    Der Support umfasst

    • Fügen Sie Ihrem Manifest die Platzhalter hinzu.

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

      Dazu gibt es drei Möglichkeiten, die hier beschrieben werden.

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

    Wenn Sie mit einem Manifest mit Vorlage beginnen, werden jetzt Werte für Vorlagenvariablen angewendet. Wenn du mit einem Rohmanifest beginnst, bleibt es unverändert. Das Rendering wird von Skaffold ausgeführt.

    Sie können jedoch zusätzliche Variablen in Ihrem Manifest haben, für die die Werte nicht zum Zeitpunkt des Renderings angewendet werden. Das sind die in diesem Dokument beschriebenen Bereitstellungsparameter.

    Beim Erstellen der Version werden alle Bereitstellungsparameter in einem Dictionary kompiliert, mit dem Werte ersetzt werden, 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 wurden bereits Werte auf Manifestvorlagen angewendet, einige Werte ersetzt und Cloud Deploy-spezifische Labels 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 zum Zeitpunkt des Renderns 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 Ablauf der Bereitstellungspipeline an. Der Parameter wird an das Ziel übergeben, das durch diese Phase dargestellt wird. Wenn sich diese Phase auf ein Multi-Ziel bezieht, werden die hier festgelegten Werte für alle untergeordneten Ziele verwendet.

    Mit dieser Methode können Sie einen Wert für alle Releases innerhalb 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.

  • Über die Befehlszeile, wenn Sie einen Release erstellen

    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 beim Erstellen der Version ersetzen und ihn auf die Manifeste aller betroffenen Ziele anwenden.

Die Konfiguration dieser Funktionen 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 angeben. Das Ergebnis ist, 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.

Wie unterscheiden sich diese von Manifest-Vorlagen?

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

Technik Zeit der Auswechslung Gilt für
Manifestvorlage Rendering phase Bestimmte Version; 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 Ziel), nicht um vorlagebasierte Manifeste.

Beschränkungen

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

  • Ein untergeordnetes Ziel kann zusätzlich bis zu 25 Parameter von seinem übergeordneten Multi-Ziel übernehmen. Insgesamt können für die Ziele bis zu 100 Parameter festgelegt werden, einschließlich derer, die in der Pipelinephase festgelegt wurden.

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

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

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

  • Platzhalter für Bereitstellungsparameter können nicht für Helm-Konfigurationswerte verwendet werden, sondern müssen gemäß Konvention ü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 die Platzhalter hinzufügen, wie in diesem Abschnitt beschrieben.

Platzhalter in das Manifest einfügen

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

Syntax

Verwenden Sie für Releases, bei denen der Helm-Renderer nicht mit Skaffold verwendet wird, 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

    Dieser Wert wird verwendet, wenn für diese Property in der Befehlszeile oder in der Pipeline- oder Zielkonfiguration keine Werte angegeben wurden.

  • # from-param:

    Hier wird ein Kommentarzeichen verwendet, um die Cloud Deploy-deploy-parameters-Anweisung zu trennen. from-param: teilt Cloud Deploy mit, dass ein deploy-parameters-Platzhalter folgt.

  • ${VAR_NAME}

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

Parameter für Helm-Diagrammwerte

Wenn Sie ein Helm-Diagramm rendern, das Konfigurationswerte akzeptiert, und diese Werte mit Bereitstellungsparametern festlegen möchten, müssen die Namen der Bereitstellungsparameter mit den Werten der Helm-Konfiguration übereinstimmen, die Sie festlegen möchten. Alle Bereitstellungsparameter werden beim Rendern als --set-Argumente an Helm übergeben. Eine Änderung von skaffold.yaml ist nicht erforderlich.

Wenn Ihr skaffold.yaml beispielsweise ein Helm-Diagramm installiert, das einen Konfigurationsparameter webserver.port verwendet, um anzugeben, über welchen Port der Webserver gestartet werden soll, und Sie diesen Wert 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 Ihrem skaffold.yaml also nicht nur auf Helm-Vorlagen verweisen, sondern auch Vorlagen erstellen, können Sie die Standardsyntax für Helm-Variablen von {{ .Values.VAR_NAME }} in Ihren Helm-Vorlagen verwenden.

Wenn wir beispielsweise den Bereitstellungsparameter 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`.

Pipelinephase einen Parameter hinzufügen

Sie können einer Phase in der Bereitstellungspipeline Schlüssel/Wert-Paare hinzufügen. Das ist bei parallelen Bereitstellungen nützlich, um untergeordnete Ziele zu unterscheiden.

  1. Fügen Sie die Platzhalter wie hier beschrieben Ihrem Kubernetes-Manifest oder Cloud Run-Dienst 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: 80

  2. Konfigurieren Sie Ihre Bereitstellungspipeline so, dass deployParameters für die entsprechende Pipelinephase enthalten ist.

    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-Strophe zwei values, die jeweils Folgendes haben:

    • Der Variablenname, der mit dem Namen der Variablen im Manifest übereinstimmen muss

    • Einen Wert für diese Variable

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

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

  3. Wenn Sie matchTargetLabels eingeschlossen haben , müssen Sie auch Labels auf den Zielen angeben, damit eine Übereinstimmung erfolgen kann. So legen Sie fest, welcher Wert welchem untergeordneten Ziel zugewiesen werden soll.

    Das Ziel muss mit allen Labels übereinstimmen, die in der values-Strophe festgelegt sind.

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

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

Zielkonfiguration einen Parameter hinzufügen

Sie können einem Ziel Schlüssel/Wert-Paare hinzufügen. Wenn Sie Bereitstellungsparameter verwenden, um zwischen mehreren untergeordneten Zielen zu unterscheiden, müssen Sie sie für diese untergeordneten Ziele konfigurieren, 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 auf den Standardwert example1 und envvar2 auf den Standardwert example2 festgelegt.

  2. Konfigurieren Sie Ihre Zielgruppen so, dass sie deployParameters umfassen.

    Geben Sie für jeden Parameter Folgendes an:

    • Der Schlüsselname, der mit dem Schlüssel (Variable) ü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.

    Die folgende YAML-Datei ist die Konfiguration für zwei Ziele. Jedes Ziel enthält einen deployParameters-Abschnitt, in dem ein Wert festgelegt wird. Jedes Ziel enthält außerdem 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 die Version 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 bei der Erstellung des Release ü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 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 SHA des Commits 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 lautet $ gefolgt vom Variablennamen in geschweiften Klammern. In diesem Beispiel ist das ${git-sha}.

  2. Fügen Sie beim Erstellen einer Version die Option --deploy-parameters in den Befehl gcloud deploy releases create ein.

    --deploy-parameters nimmt eine durch Kommas getrennte Liste von Schlüssel/Wert-Paaren an, 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 Manifest-Rendering, stellt Cloud Deploy die Werte den gerenderten Manifesten zur Verfügung, sofern sie die zugehörigen Schlüssel enthalten.

Parameter mit benutzerdefinierten Zielen bereitstellen

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

Bereitstellungsparameter, die als Eingaben für benutzerdefinierte Ziele dienen, 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 mit CLOUD_DEPLOY_customTarget_vertexAIModel.

Bereitstellungsparameter mit Bereitstellungshooks

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

Bereitstellungsparameter mit Bereitstellungsüberprüfung bereitstellen

Sie können jeden Bereitstellungsparameter als Umgebungsvariable in der Bereitstellungsbestätigung verwenden.

Alle Parameter für einen Release ansehen

Sie können sich die Parameter ansehen, die für eine bestimmte Version 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 Cloud Deploy-Hauptseite auf die Bereitstellungspipeline, die das gewünschte Release enthält.

  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 und in der anderen Spalte die betroffenen Ziele aufgeführt.

Bereitstellungsparameter und ‑werte, die in der Google Cloud Console angezeigt werden

Nächste Schritte