Transmettre des paramètres à votre déploiement

À l'aide de Cloud Deploy, vous pouvez transmettre des paramètres pour votre version, et ces sont fournies au ou aux fichiers manifestes avant que ces derniers ne soient à leurs cibles respectives. Cette substitution est effectuée après le rendu des fichiers manifestes, comme dernière étape de l'opération de rendu de Cloud Deploy. Des valeurs sont fournies à tous les fichiers manifestes identifiés dans votre fichier skaffold.yaml qui contiennent les espaces réservés correspondants.

Il vous suffit d'inclure des espaces réservés dans votre fichier manifeste et de définir les valeurs de ces espaces réservés dans votre pipeline de diffusion Cloud Deploy ou votre configuration cible, ou lorsque vous créez une version.

Cet article explique comment procéder.

Pourquoi utiliser des paramètres de déploiement ?

Un cas d'utilisation typique consisterait à appliquer différentes valeurs aux fichiers manifestes pour cibles dans un déploiement parallèle. Mais vous pouvez Utilisez des paramètres de déploiement pour tout ce qui nécessite une paire clé-valeur post-rendu dans votre fichier manifeste.

Fonctionnement

Les étapes suivantes décrivent le processus général de configuration du déploiement paramètres et fournir des valeurs:

  1. Vous configurez le paramétrage du déploiement, comme décrit cliquez ici.

    Éléments inclus :

    • Ajoutez les espaces réservés à votre fichier manifeste.

    • Ajoutez des valeurs pour ces espaces réservés.

      Pour ce faire, vous disposez de trois méthodes, décrites sur cette page.

  2. Lorsque vous créez une version, votre fichier manifeste est rendu.

    Si vous commencez avec un fichier manifeste créé à partir d'un modèle, les valeurs sont appliquées maintenant au modèle variables. Si vous commencez avec un fichier manifeste brut, il ne sera pas modifié. Ce rendu est effectué par Skaffold.

    Cependant, votre fichier manifeste peut contenir des variables supplémentaires pour lesquelles les valeurs ne sont pas appliquées au moment de l'affichage. Il s'agit des paramètres de déploiement décrits dans ce document.

    Lors de la création de la version, tous les paramètres de déploiement sont compilés dans un dictionnaire, qui permet de remplacer les valeurs avant l'application des fichiers manifestes.

  3. Après l'affichage, Cloud Deploy remplace les valeurs par des paramètres de déploiement.

    Il s'agit des valeurs que vous avez configurées à la première étape.

    Le processus de rendu a déjà appliqué des valeurs aux modèles de manifeste, en remplaçant certaines valeurs et en ajoutant des étiquettes spécifiques Cloud Deploy. Toutefois, les valeurs de ces paramètres de déploiement sont substituées après le rendu. Les différences entre les modèles de fichier manifeste et les paramètres de déploiement sont décrites ici.

  4. Le fichier manifeste est appliqué à l'environnement d'exécution cible pour déployer votre application.

    Cela inclut les valeurs substituées au moment du rendu, ainsi que les valeurs de toute paramètres de déploiement

Différentes manières de transmettre des valeurs

Vous pouvez fournir des paramètres et des valeurs pour ces paramètres de trois manières :

  • Dans la définition du pipeline de diffusion

    Vous indiquez le paramètre et sa valeur dans la définition d'une étape dans la progression du pipeline de livraison. Le paramètre est transmis à la cible représentée par cette étape. Si cette étape fait référence à une cible multicible, les valeurs définies ici sont utilisées pour toutes les cibles enfants.

    Cette méthode vous permet de remplacer une valeur pour toutes les versions d'un pipeline donné, pour toutes les cibles concernées. Les paramètres définis pour une étape identifient un libellé, et la cible correspondante de cette étape doit comporter un libellé correspondant.

  • Dans la définition de la cible

    Vous configurez le paramètre et sa valeur dans la définition de la cible elle-même. Cette méthode vous permet de remplacer une valeur pour cette cible pour toutes les versions.

  • Dans la ligne de commande, lorsque vous créez une version

    Vous incluez le paramètre et sa valeur à l'aide de l'option --deploy-parameters dans la commande gcloud deploy releases create.

    Cette méthode vous permet de remplacer une valeur au moment de la création de la version, en appliquant cette valeur aux fichiers manifestes de toutes les cibles concernées.

Pour en savoir plus sur la configuration de ces éléments, cliquez ici.

Puis-je utiliser plusieurs de ces méthodes ?

Oui, vous pouvez inclure des paramètres de déploiement à l'étape du pipeline, dans la configuration cible et dans la ligne de commande. Par conséquent, tous les paramètres sont acceptés et ajoutés au dictionnaire. Toutefois, si un paramètre spécifique est transmis à plusieurs endroits, mais avec des valeurs différentes, la commande gcloud deploy releases create échoue et génère une erreur.

En quoi est-ce différent des modèles de fichier manifeste ?

Les paramètres de déploiement, comme décrit dans cet article, se distinguent des espaces réservés dans un fichier manifeste avec modèle par la syntaxe. Toutefois, si vous vous demandez pourquoi vous avez besoin de paramètres de déploiement au lieu d'utiliser techniques standards pour les fichiers manifestes modélisés, le tableau suivant montre les à différentes fins:

Technique Heure de remplacement Applicable à
Modèle de fichier manifeste Phase d'affichage Version spécifique ; cible spécifique
Dans la ligne de commande Post-rendu Version spécifique : toutes les cibles
Pipeline de livraison Post-rendu Tous les albums ; cibles spécifiques (par libellé)
Dans la cible Post-rendu Toutes les versions ; cible spécifique

Ce document concerne uniquement les paramètres de déploiement (sur la ligne de commande, le pipeline et la cible), et non les fichiers manifestes avec modèle.

Limites

  • Vous pouvez créer jusqu'à 25 paramètres pour chaque type de paramètre.

  • De plus, une cible enfant peut hériter de 25 paramètres maximum de son parent. avec un maximum de 100 paramètres sur les cibles, y compris à l'étape du pipeline.

  • Le nom de clé est limité à un maximum de 63 caractères et les caractères suivants Expression régulière:

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

    Une exception à cette règle est que lorsque vous utilisez un paramètre de déploiement en tant que variable d'environnement dans une cible personnalisée, vous devez utiliser une barre oblique entre le mot clé customTarget et le nom de la variable (customTarget/VAR_NAME). Consultez la section Données d'entrée et de sortie requises pour connaître la syntaxe acceptée.

  • Le préfixe CLOUD_DEPLOY_ est réservé et ne peut pas être utilisé pour un nom de clé.

  • Deux clés du même nom ne peuvent pas être appliquées à la même cible.

  • La valeur peut être vide, mais ne doit pas dépasser 512 caractères.

  • Les espaces réservés pour les paramètres de déploiement ne peuvent pas être utilisés pour Valeurs de configuration Helm mais doit être transmis par convention.

Configurer les paramètres de déploiement

Cette section explique comment configurer les valeurs des paramètres de déploiement qui seront à votre fichier manifeste Kubernetes, à votre service Cloud Run ou votre modèle Helm.

En plus de configurer ces paires clé-valeur, vous devez ajouter l'espace réservé ou les espaces réservés à votre fichier manifeste, comme décrit dans cette section.

Ajouter des espaces réservés à votre fichier manifeste

Dans le fichier manifeste Kubernetes (pour GKE) ou le fichier YAML du service (pour Cloud Run), ajoutez des espaces réservés pour les valeurs de votre choix. à remplacer après le rendu.

Syntaxe

Pour les versions qui n'utilisent pas le moteur de rendu Helm avec Skaffold, utilisez la syntaxe suivante pour vos espaces réservés :

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

Dans cette ligne…

  • PROPERTY:

    Il s'agit de la propriété de configuration dans votre fichier manifeste Kubernetes ou YAML du service Cloud Run.

  • DEFAULT_VALUE

    Valeur à utiliser si aucune valeur n'est fournie pour cette propriété sur la ligne de commande, dans le pipeline ou dans la configuration de la cible.

  • # from-param:

    Utilise un caractère de commentaire pour définir la directive deploy-parameters de Cloud Deploy, et from-param: indique à Cloud Deploy qu'un espace réservé deploy-parameters suit.

  • ${VAR_NAME}

    Indique l'espace réservé à remplacer. Doit correspondre à la clé d'une paire clé-valeur fournies dans le pipeline de livraison ou la configuration cible, ou lors de la création de la version.

Paramètres pour les valeurs de chart Helm

Si vous affichez un graphique Helm qui accepte des valeurs de configuration et que vous souhaitez définir ces valeurs à l'aide de paramètres de déploiement, les noms des paramètres de déploiement doivent correspondre aux valeurs de configuration Helm que vous souhaitez définir. Tous les paramètres de déploiement sont transmis à Helm en tant qu'arguments --set au moment du rendu. sans avoir à modifier votre skaffold.yaml.

Par exemple, si votre skaffold.yaml installe un chart Helm qui prend un paramètre de configuration de webserver.port pour spécifier le port du serveur Web et que vous souhaitez le définir dynamiquement à partir d'un déploiement vous devez créer un paramètre "deploy" avec le paramètre webserver.port par la valeur que vous souhaitez pour le port du serveur Web.

Par conséquent, si vous ne faites pas seulement référence à des modèles Helm dans votre skaffold.yaml, mais aussi de les créer, vous pouvez utiliser syntaxe des variables Helm standard de {{ .Values.VAR_NAME }} dans vos modèles Helm.

Par exemple, si le paramètre de déploiement webserver.port est configuré, nous pourrions l'utiliser comme ceci:

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`.

Ajouter un paramètre à l'étape du pipeline

Vous pouvez ajouter des paires clé-valeur à une étape de la progression du pipeline de livraison. Cela est utile pour les déploiements parallèles, afin de distinguer les cibles enfants.

  1. Ajoutez les espaces réservés à votre fichier manifeste Kubernetes ou à votre service Cloud Run, comme décrit ici.

    Exemple :

    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. Configurez votre pipeline de diffusion pour inclure deployParameters pour l'étape de pipeline applicable.

    Le fichier YAML suivant correspond à la configuration d'une étape de pipeline dont la cible est un groupe multicible, qui comporte dans ce cas deux cibles enfants :

    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"

    Dans cette configuration de pipeline de diffusion, la strophe deployParameters comprend deux values, chacun comportant les éléments suivants :

    • Le nom de la variable, qui est le même que celui de la variable que vous avez définie dans le fichier manifeste

    • Une valeur pour cette variable

    • Un ou plusieurs libellés (facultatif) à faire correspondre aux libellés spécifiques à la cible

      Si vous ne spécifiez pas de libellé, dans une section matchTargetLabels, cette valeur est utilisé pour toutes les cibles de l'étape.

  3. Si vous avez inclus matchTargetLabels, vous devez également inclure des libellés sur les cibles pour les faire correspondre. Vous pouvez ainsi identifier la valeur à attribuer à chaque cible enfant.

    La cible doit correspondre à tous les libellés définis dans le stanza values.

    Si vous omettez matchTargetLabels, les values que vous définissez dans le pipeline sont appliqué à toutes les cibles enfants. Mais si vous définissez plusieurs valeurs pour une même valeur, , la version échouera.

Une fois chaque fichier manifeste affiché, Cloud Deploy ajoute la valeur de chaque variable dans le fichier manifeste affiché.

Ajouter un paramètre à la configuration cible

Vous pouvez ajouter des paires clé-valeur à une cible. Si vous utilisez des paramètres de déploiement distinguer plusieurs cibles enfants, les configurer sur celles-ci, en dehors du multicible.

  1. Configurez votre fichier manifeste Kubernetes ou la définition de votre service Cloud Run à l'aide d'un paramètre à la place de la valeur que vous souhaitez définir au moment du déploiement.

    Exemple :

    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}

    Dans ce fichier manifeste, le paramètre envvar1 est défini par défaut sur example1 et envvar2 sur example2.

  2. Configurez vos cibles pour inclure deployParameters.

    Pour chaque paramètre que vous incluez, vous identifiez les éléments suivants:

    • Nom de la clé, qui est identique à celui de la clé (variable) que vous avez définie dans le fichier manifeste.

    • Valeur de cette clé. Si vous n'indiquez aucune valeur, la valeur par défaut du fichier manifeste.

    Le fichier YAML suivant correspond à la configuration de deux cibles. Chaque cible comprend un bloc deployParameters définissant une valeur. Chaque cible comprend également étiquette, à associer aux paramètres de déploiement configurées sur une étape de pipeline.

    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"

Lorsque la version est créée, mais après l'affichage des fichiers manifestes, Cloud Deploy ajoute ces valeurs aux fichiers manifestes affichés s'ils incluent les clés associées.

Transmettre un paramètre lors de la création d'une version

Procédez comme suit pour transmettre les paramètres et les valeurs à la version:

  1. Configurez votre fichier manifeste Kubernetes ou la définition de votre service Cloud Run à l'aide d'un paramètre à la place de la valeur que vous souhaitez définir au moment du déploiement.

    Exemple :

    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

    Dans cet exemple, l'empreinte SHA du commit est définie en tant que variable appelée ${git-sha}. Une valeur pour cet élément est transmise lors de la création de la version à l'aide de la méthode --deploy-parameters=, comme vu à l'étape suivante.

    La syntaxe de cette variable est $, suivi du nom de la variable entre accolades. Dans cet exemple, il s'agit de ${git-sha}.

  2. Lorsque vous créez une version, incluez l'option --deploy-parameters dans la commande gcloud deploy releases create.

    --deploy-parameters accepte une liste de paires clé-valeur séparées par une virgule, où la clé correspond à l'espace réservé que vous avez ajouté au fichier manifeste.

    La commande se présente comme suit :

    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"

Lors de la création de la version, mais après l'affichage du fichier manifeste, Cloud Deploy fournit les valeurs aux fichiers manifestes affichés si elles inclure les clés associées.

Déployer des paramètres avec des cibles personnalisées

Vous pouvez utiliser n'importe quel paramètre de déploiement comme variable d'environnement dans les cibles personnalisées. Dans ce cas, utilisez la syntaxe spécifiée pour les cibles personnalisées.

Les paramètres de déploiement destinés à être utilisés comme entrées pour les cibles personnalisées peuvent commencer par customTarget/, par exemple customTarget/vertexAIModel. Si vous utilisez utilisez la syntaxe suivante lorsque vous référencez un paramètre "deploy" en tant que d'variable d'environnement:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Où VAR_NAME est le nom situé après la barre oblique dans nom du paramètre "deploy". Par exemple, si vous définissez un paramètre de déploiement nommé customTarget/vertexAIModel, référencez-le sous le nom CLOUD_DEPLOY_customTarget_vertexAIModel.

Paramètres de déploiement avec des hooks de déploiement

Vous pouvez utiliser n'importe quel paramètre "deploy" en tant que variable d'environnement dans de déploiement des hooks.

Paramètres de déploiement avec validation du déploiement

Vous pouvez utiliser n'importe quel paramètre de déploiement comme variable d'environnement lors de la validation du déploiement.

Afficher tous les paramètres d'une version

Vous pouvez afficher les paramètres définis pour une version donnée. Ils sont affichés dans un tableau sur la page Détails de la version et dans la ligne de commande (gcloud deploy releases describe).

  1. Sur la page principale Cloud Deploy, cliquez sur le pipeline de livraison inclut la version que vous voulez voir.

  2. Sur la page Détails de la version, sélectionnez l'onglet Artefacts.

Tous les paramètres de déploiement qui ont été définis pour cette version sont affichés dans un tableau, avec le nom et la valeur de la variable dans une colonne, et la ou les cibles concernées dans l'autre colonne.

paramètres et valeurs de déploiement affichés dans la console Google Cloud

Étape suivante