Transmettre des paramètres à votre déploiement

Avec Cloud Deploy, vous pouvez transmettre des paramètres pour votre version. Ces valeurs sont fournies au ou aux fichiers manifestes avant qu'ils ne soient appliqués à leurs cibles respectives. Cette substitution est effectuée après le rendered des fichiers manifestes, en tant que dernière étape de l'opération de rendu 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 déploiement Cloud Deploy ou dans la configuration cible, ou lorsque vous créez une version.

Cet article explique comment procéder.

Pourquoi utiliser des paramètres de déploiement ?

Une utilisation typique consiste à appliquer différentes valeurs aux fichiers manifestes pour différentes cibles dans un déploiement parallèle. Toutefois, vous pouvez utiliser des paramètres de déploiement pour tout ce qui nécessite une substitution de paire clé/valeur post-rendu dans votre fichier manifeste.

Fonctionnement

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

  1. Configurez la paramétrisation du déploiement, comme décrit ici.

    parmi lesquels :

    • Ajoutez les espaces réservés à votre fichier manifeste, y compris une valeur par défaut pour chacun d'eux.

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

      Il existe trois façons de procéder, décrites ici.

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

    Si vous commencez par un fichier manifeste basé sur un modèle, les valeurs sont appliquées maintenant pour les variables du modèle. Si vous commencez avec un fichier manifeste brut, il reste inchangé. Le rendu est effectué par Skaffold.

    Toutefois, vous pouvez ajouter des variables à votre fichier manifeste pour lesquelles aucune valeur n'est appliquée au moment du rendu. Il s'agit des paramètres de déploiement décrits dans ce document.

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

  3. Après le rendu, Cloud Deploy remplace les valeurs des paramètres de déploiement.

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

    Le processus de rendu a déjà appliqué des valeurs aux modèles de fichier manifeste, en remplaçant certaines valeurs et en ajoutant des libellés spécifiques à Cloud Deploy. Toutefois, les valeurs de ces paramètres de déploiement sont remplacé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 et les valeurs de tous les paramètres de déploiement.

Différentes façons de transmettre des valeurs

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

  • Dans la définition du pipeline de livraison

    Vous fournissez le paramètre et sa valeur dans la définition d'une étape de 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 à un groupe 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 pour cette étape doit avoir 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.

  • Sur 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 sur 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 dans la phase du pipeline, dans la configuration cible et sur la ligne de commande. Tous les paramètres sont donc 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 renvoie une erreur.

Différences avec les modèles de fichier manifeste

Les paramètres de déploiement, tels que décrits dans cet article, se distinguent des espaces réservés dans un fichier manifeste basé sur un modèle par leur syntaxe. Toutefois, si vous vous demandez pourquoi vous auriez besoin de paramètres de déploiement au lieu d'utiliser simplement les techniques standards pour les manifestes de modèles, le tableau suivant montre les différentes utilisations :

Technique Heure de remplacement Applicable à
Modèle de fichier manifeste Phase de rendu Version spécifique ; cible spécifique
Dans la ligne de commande Post-rendu Version spécifique ; toutes les cibles
Sur le pipeline de livraison Post-rendu Toutes les sorties ; cibles spécifiques (par label)
Dans la cible Post-rendu Toutes les versions ; cible spécifique

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

Limites

  • Pour chaque type de paramètre, vous pouvez créer jusqu'à 50 paramètres.

  • Une cible enfant peut également hériter de 50 paramètres maximum de son groupe multicible parent, jusqu'à un maximum de 200 paramètres sur les cibles, y compris ceux définis au niveau de l'étape du pipeline.

  • Le nom de la clé ne peut pas comporter plus de 63 caractères et doit respecter l'expression régulière suivante :

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

    Une exception à cette règle se produit lorsque vous utilisez un paramètre de déploiement comme variable d'variable d'environnement dans une cible personnalisée. Dans ce cas, vous devez utiliser une barre oblique entre le mot clé customTarget et le nom de la variable (customTarget/VAR_NAME). Pour connaître la syntaxe acceptée, consultez Entrées et sorties requises.

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

  • Vous ne pouvez pas appliquer deux clés portant le même nom à la même cible.

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

  • Les espaces réservés des paramètres de déploiement ne peuvent pas être utilisés pour les valeurs de configuration Helm, mais doivent ê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 appliquées à votre fichier manifeste Kubernetes, à votre service Cloud Run ou à votre modèle Helm.

En plus de configurer ces paires clé-valeur, vous devez ajouter le 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 votre fichier manifeste Kubernetes (pour GKE) ou YAML de service (pour Cloud Run), vous ajoutez des espaces réservés pour toutes les valeurs que vous souhaitez 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:

    Propriété de configuration dans votre fichier manifeste Kubernetes ou YAML de service Cloud Run.

  • DEFAULT_VALUE

    Valeur à utiliser si aucune valeur n'est fournie pour cette propriété dans la ligne de commande, le pipeline ou la configuration cible. La valeur par défaut est requise, mais elle peut être une chaîne vide ("").

  • # from-param:

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

  • ${VAR_NAME}

    Espace réservé à remplacer. Elle doit correspondre à la clé d'une paire clé-valeur fournie dans le pipeline de livraison ou la configuration cible, ou lors de la création de la version.

Vous pouvez également utiliser plusieurs paramètres sur une même ligne et les utiliser dans une chaîne plus longue, par exemple :

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

Ces paramètres peuvent provenir de plusieurs sources. Dans l'exemple précédent, ${artifactRegion} serait probablement défini au niveau de la cible ou de l'étape du pipeline de diffusion, tandis que ${imageSha} proviendrait de la ligne de commande au moment de la création de la version.

Paramètres pour les valeurs du chart Helm

Si vous affichez un graphique Helm qui accepte les valeurs de configuration et que vous souhaitez définir ces valeurs à l'aide de paramètres de déploiement, les paramètres de déploiement doivent avoir des noms qui correspondent 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 qu'il soit nécessaire de modifier votre skaffold.yaml.

Par exemple, si votre skaffold.yaml installe un graphique Helm qui utilise un paramètre de configuration webserver.port pour spécifier le port sur lequel le serveur Web doit démarrer, et que vous souhaitez définir ce paramètre de manière dynamique à partir d'un paramètre de déploiement, vous devez créer un paramètre de déploiement nommé webserver.port avec la valeur souhaitée pour le port du serveur Web.

Par conséquent, si vous ne faites pas que référencer des modèles Helm dans votre skaffold.yaml, mais que vous les créez également, vous pouvez utiliser la syntaxe standard des variables Helm de {{ .Values.VAR_NAME }} dans vos modèles Helm.

Par exemple, si nous avons configuré un paramètre de déploiement webserver.port, nous pouvons l'utiliser comme suit :

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 à la phase de pipeline

Vous pouvez ajouter des paires clé-valeur à une étape de la progression du pipeline de diffusion. Cela est utile pour les déploiements parallèles, afin de faire la distinction entre 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 livraison pour inclure deployParameters pour l'étape de pipeline applicable.

    Le code YAML suivant correspond à la configuration d'une étape de pipeline dont la cible est une cible multicible, qui dans ce cas comporte 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 livraison, la strophe deployParameters inclut deux values, chacun ayant les éléments suivants :

    • Nom de la variable, qui est identique à celui que vous avez défini dans le fichier manifeste

    • une valeur pour cette variable.

    • Un ou plusieurs libellés (facultatifs) à comparer aux libellés spécifiques à la cible

      Si vous ne spécifiez pas de libellé dans une strophe matchTargetLabels, cette valeur est utilisée 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 identifiez ainsi la valeur à attribuer à chaque cible enfant.

    La cible doit correspondre à toutes les étiquettes définies dans la section values.

    Si vous omettez matchTargetLabels, les values que vous définissez sur le pipeline sont appliqués à toutes les cibles enfants. Toutefois, si vous définissez plusieurs valeurs pour le même paramètre, la version échouera.

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

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 pour distinguer plusieurs cibles enfants, configurez-les sur ces cibles enfants, et non sur la multicible.

  1. Configurez votre fichier manifeste Kubernetes ou votre définition de 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 devez identifier 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 ne fournissez pas de valeur, la valeur par défaut définie dans le fichier manifeste est utilisée.

    Le code YAML suivant correspond à la configuration de deux cibles. Chaque cible inclut une strophe deployParameters définissant une valeur. Chaque cible inclut également un libellé à associer aux paramètres de déploiement configurés sur une étape du 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 le rendu des fichiers manifestes, Cloud Deploy ajoute ces valeurs aux fichiers manifestes rendus s'ils incluent les clés associées.

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

Pour transmettre des paramètres et des valeurs à la version, procédez comme suit :

  1. Configurez votre fichier manifeste Kubernetes ou votre définition de 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, le SHA du commit est défini comme variable appelée ${git-sha}. Une valeur est transmise pour cette option lors de la création de la version, à l'aide de l'option --deploy-parameters=, comme indiqué à l'étape suivante.

    La syntaxe de cette variable est $, plus le nom de la variable entre accolades. Dans cet exemple, la valeur est 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 au code de substitution que vous avez ajouté au fichier manifeste.

    La commande doit ressembler à ceci :

    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"

Lorsque la version est créée, mais après le rendu du fichier manifeste, Cloud Deploy fournit les valeurs aux fichiers manifestes rendus s'ils incluent 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 à servir d'entrées pour les cibles personnalisées peuvent commencer par customTarget/, par exemple customTarget/vertexAIModel. Si vous utilisez ce préfixe, utilisez la syntaxe suivante lorsque vous référencez un paramètre de déploiement en tant que variable d'environnement :

CLOUD_DEPLOY_customTarget_[VAR_NAME]

où VAR_NAME correspond au nom qui suit la barre oblique dans le nom du paramètre deploy. Par exemple, si vous définissez un paramètre de déploiement nommé customTarget/vertexAIModel, référencez-le comme CLOUD_DEPLOY_customTarget_vertexAIModel.

Déployer des paramètres avec des hooks de déploiement

Vous pouvez utiliser n'importe quel paramètre de déploiement comme variable d'environnement dans les crochets de déploiement.

Déployer des paramètres avec validation du déploiement

Vous pouvez utiliser n'importe quel paramètre de déploiement comme variable d'environnement dans 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 sur la ligne de commande (gcloud deploy releases describe).

  1. Sur la page principale de Cloud Deploy, cliquez sur le pipeline de diffusion qui inclut la version que vous souhaitez afficher.

  2. Sur la page Informations sur la version, sélectionnez l'onglet Artefacts.

Tous les paramètres de déploiement 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

Étapes suivantes