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 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 ?
Par exemple, vous pouvez 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 élément nécessitant une substitution de paire clé-valeur après le 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:
Vous configurez la paramétrisation du déploiement, comme décrit 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 pouvez suivre l'une des trois méthodes décrites ici.
Lorsque vous créez une version, votre fichier manifeste est affiché.
Si vous commencez avec un fichier manifeste avec modèle, des valeurs sont désormais appliquées aux variables de modèle. Si vous commencez avec un fichier manifeste brut, il ne sera pas modifié. Ce rendu est effectué par Skaffold.
Toutefois, vous pouvez inclure des variables supplémentaires dans votre fichier manifeste pour lesquelles les valeurs ne sont pas appliquées au moment du rendu. Voici les 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.
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 à l'étape 1.
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 l'affichage. Les différences entre les modèles de fichier manifeste et les paramètres de déploiement sont décrites ici.
Le fichier manifeste est appliqué à l'environnement d'exécution cible pour déployer votre application.
Cela inclut les valeurs remplacées au moment de l'affichage 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 des valeurs pour ces paramètres de trois manières:
Dans la définition du pipeline de diffusion
Vous devez fournir le paramètre et sa valeur dans la définition d'une étape de la progression du pipeline de diffusion. 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 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.
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-parametersdans la commandegcloud 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 renvoie 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 de simplement utiliser les techniques standards pour les fichiers manifestes avec modèle, le tableau suivant indique les différents objectifs:
| Technique | Heure de remplacement | Applicable à |
|---|---|---|
| Modèle de fichier manifeste | Phase de rendu | Version spécifique ; cible spécifique |
| Sur la ligne de commande | Post-rendu | Version spécifique : toutes les cibles |
| Dans le pipeline de diffusion | 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.
Une cible enfant peut également hériter de 25 paramètres maximum de son groupe multicible parent, soit un maximum de 100 paramètres sur les cibles, y compris ceux définis à l'étape du pipeline.
Le nom de la clé est limité à 63 caractères maximum et à 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 est que lorsque vous utilisez un paramètre de déploiement en tant que variable d'variable d'environnement dans une cible personnalisée, vous devez utiliser une barre oblique entre le mot clé
customTargetet 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é.Vous ne pouvez pas appliquer deux clés du 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 de 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 de paramètre 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 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 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 l'affichage.
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-parametersde Cloud Deploy, etfrom-param:indique à Cloud Deploy qu'un espace réservédeploy-parameterssuit.${VAR_NAME}
Indique l'espace réservé à remplacer. Elle doit correspondre à la clé d'une paire clé-valeur fournie dans le pipeline de diffusion ou la configuration cible, ou lors de la création de la version.
Paramètres des valeurs du graphique 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 de l'affichage, sans aucune modification de votre skaffold.yaml.
Par exemple, si votre skaffold.yaml installe un graphique Helm qui utilise un paramètre de configuration de webserver.port pour spécifier le port à partir duquel le serveur Web démarre, et que vous souhaitez le définir de manière dynamique à partir d'un paramètre de déploiement, vous devez créer un paramètre de déploiement avec le nom webserver.port et 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 de variable Helm standard de {{ .Values.VAR_NAME }} dans vos modèles Helm.
Par exemple, si un paramètre de déploiement de webserver.port est configuré, vous pouvez 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 à l'étape du 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 distinguer les cibles enfants.
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: 80Configurez votre pipeline de diffusion pour inclure
deployParameterspour 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
deployParameterscomprend deuxvalues, chacun comportant 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 (facultatif) à faire correspondre 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.
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 à toutes les étiquettes définies dans la strophe
values.Si vous omettez
matchTargetLabels, lesvaluesque 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 publication é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 pour distinguer plusieurs cibles enfants, configurez-les sur ces cibles enfants, et non sur le groupe multicible.
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
envvar1est défini par défaut surexample1etenvvar2surexample2.Configurez vos cibles pour inclure
deployParameters.Pour chaque paramètre que vous incluez, vous devez indiquer 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 fichier YAML suivant correspond à la configuration de deux cibles. Chaque cible inclut une strophe
deployParametersdéfinissant une valeur. Chaque cible inclut également un libellé, à faire correspondre aux paramètres de déploiement configurés 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
Pour transmettre des paramètres et des valeurs à la version, procédez comme suit:
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.2Dans cet exemple, l'empreinte SHA du commit est définie en tant que variable appelée
${git-sha}. Une valeur est transmise 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
$, suivi du nom de la variable entre accolades. Dans cet exemple, il s'agit de${git-sha}.Lorsque vous créez une version, incluez l'option
--deploy-parametersdans la commandegcloud deploy releases create.--deploy-parametersaccepte une liste de paires clé-valeur séparées par une virgule, où la clé est 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"
Lorsque la version est créée, mais après le rendu du fichier manifeste, Cloud Deploy fournit les valeurs aux fichiers manifestes affichés 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 à être des entrées pour des 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 de déploiement. 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 de déploiement comme variable d'environnement dans les hooks de déploiement.
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).
Sur la page principale de Cloud Deploy, cliquez sur le pipeline de diffusion qui inclut la version que vous souhaitez afficher.
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.
Étape suivante
Suivez le guide de démarrage rapide: Utiliser des paramètres de déploiement.
Découvrez comment utiliser les déploiements en parallèle.