Cloud Deploy vous permet de 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, ce qui constitue la dernière étape de l'opération de rendu Cloud Deploy. Les valeurs sont fournies à tous les fichiers manifestes identifiés dans votre fichier skaffold.yaml
contenant 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 livraison Cloud Deploy ou dans votre configuration cible, ou lorsque vous créez une version.
Cet article vous explique comment procéder.
Pourquoi utiliser des paramètres de déploiement ?
Cela permet généralement d'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 pour configurer les paramètres de déploiement et fournir des valeurs:
Vous configurez le paramétrage 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 disposez de trois méthodes, décrites sur cette page.
Lorsque vous créez une version, votre fichier manifeste est affiché.
Si vous commencez avec un fichier manifeste modélisé, les valeurs sont maintenant appliquées aux variables de modèle. Si vous commencez avec un fichier manifeste brut, il reste inchangé. Ce rendu est effectué par Skaffold.
Toutefois, 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 d'une 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 le rendu, Cloud Deploy remplace les valeurs par les 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 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.
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 manières de transmettre des valeurs
Vous pouvez définir des paramètres et leurs valeurs de trois manières différentes:
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 à 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 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.
Dans la ligne de commande, lorsque vous créez une version
Incluez le paramètre et sa valeur à l'aide de l'option
--deploy-parameters
dans 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 méthodes, 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 de la cible et dans la ligne de commande. Résultat : 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.
Déployer des paramètres avec des cibles personnalisées
Vous pouvez utiliser n'importe quel paramètre de déploiement comme variables d'environnement dans les cibles personnalisées. Lors de cette opération, utilisez la syntax spécifiée pour les cibles personnalisées.
En quoi est-ce différent des modèles de fichier manifeste ?
Comme décrit dans cet article, les paramètres de déploiement se distinguent des espaces réservés dans un fichier manifeste modélisé par la syntax. Toutefois, si vous vous demandez pourquoi vous auriez besoin de paramètres de déploiement au lieu d'utiliser uniquement les techniques standards pour les fichiers manifestes modélisés, le tableau suivant présente les différents objectifs:
Technique | Heure de substitution | Applicable à |
---|---|---|
Modèle de fichier manifeste | Phase d'affichage | Version spécifique ; cible spécifique |
Sur la ligne de commande | Post-rendu | Version spécifique ; toutes les cibles |
Pipeline de livraison | Post-rendu | Toutes les versions ; cibles spécifiques (par libellé) |
Conforme à l'objectif | 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 fichiers manifestes modélisés.
Limites
Pour chaque type de paramètre, vous pouvez créer jusqu'à 25 paramètres.
Une cible enfant peut également hériter d'un maximum de 25 paramètres de son multicible parente, jusqu'à un maximum de 100 paramètres sur les cibles, y compris ceux définis à l'étape du pipeline.
Le nom de clé est limité à un maximum de 63 caractères, et l'expression régulière suivante:
^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$
La seule exception à cette règle est lorsque vous utilisez un paramètre de déploiement en tant que variable d'variable d'environnement dans une cible personnalisée. Vous devez insérer une barre oblique entre le mot clé
customTarget
et le nom de la variable (customTarget/VAR_NAME
). Consultez la section Entrées et sorties obligatoires pour connaître la syntaxe compatible.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 comporter plus de 512 caractères.
Les espaces réservés aux 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 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 votre fichier 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:
est la propriété de configuration dans votre fichier manifeste Kubernetes ou dans le fichier 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 la configuration du pipeline ou de la cible.
# from-param:
Utilise un caractère de commentaire pour déclencher l'instruction
deploy-parameters
de Cloud Deploy, etfrom-param:
indique à Cloud Deploy qu'un espace réservédeploy-parameters
suit.${VAR_NAME}
Il s'agit de l'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.
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, ces paramètres doivent avoir des noms correspondant 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. Aucune modification de votre skaffold.yaml
n'est requise.
Par exemple, si votre skaffold.yaml
installe un chart 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
et définir la valeur souhaitée pour le port du serveur Web.
Par conséquent, si vous faites non seulement référence à 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 nous avons configuré le paramètre de déploiement webserver.port
, nous pouvons 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 entre les cibles enfants.
Ajoutez les espaces réservés à votre fichier manifeste Kubernetes ou au 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
Configurez votre pipeline de livraison afin d'inclure
deployParameters
pour l'étape de pipeline applicable.Le fichier YAML suivant est la configuration d'une étape du pipeline dont la cible est une cible multicible qui, dans le cas présent, a 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, le bloc
deployParameters
inclut deuxvalues
, chacun présentant les éléments suivants:Le nom de la variable, qui est identique à celui de la variable que vous avez définie dans le fichier manifeste
Une valeur pour cette variable
Un ou plusieurs libellés (facultatif) à mettre en correspondance avec des libellés spécifiques à la cible
Si vous ne spécifiez pas de libellé, dans un bloc
matchTargetLabels
, cette valeur est utilisée pour toutes les cibles de l'espace de création.
Si vous avez inclus
matchTargetLabels
, vous devez également inclure des libellés sur les cibles pour les faire correspondre. De cette manière, vous identifiez 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 valeursvalues
que vous définissez dans le pipeline sont appliquées à 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 affiché, Cloud Deploy y ajoute la valeur de chaque variable.
Ajouter un paramètre à la configuration de la 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 cible multicible.
Configurez votre fichier manifeste Kubernetes ou votre définition de service Cloud Run à l'aide d'un paramètre au lieu 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 sur la valeur par défautexample1
, et le paramètreenvvar2
sur la valeur par défautexample2
.Configurez vos cibles pour inclure
deployParameters
.Pour chaque paramètre que vous incluez, vous identifiez les éléments suivants:
Le nom de la clé, qui est identique à celui de la clé (variable) que vous avez définie dans le fichier manifeste.
Une valeur pour 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 un strophe
deployParameters
qui définit une valeur. Chaque cible comprend également un libellé à associer aux paramètres de déploiement configurés au niveau d'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"
Lors de la création de la version, mais après le rendu des fichiers manifestes, Cloud Deploy ajoute ces valeurs aux fichiers manifestes affichés si elles incluent les clés associées.
Transmettre un paramètre lors de la création de la version
Procédez comme suit pour transmettre les paramètres et les valeurs à la version:
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 commit SHA est défini en tant que variable appelée
${git-sha}
. Une valeur correspondant à cet élément 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
$
plus le 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-parameters
dans la commandegcloud deploy releases create
.--deploy-parameters
accepte 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 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"
Lors de la création de la version, mais après le rendu du fichier manifeste, Cloud Deploy fournit les valeurs aux fichiers manifestes affichés si ceux-ci incluent les clés associées.
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 Cloud Deploy, cliquez sur le pipeline de livraison 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 définis pour cette version sont affichés dans un tableau. Le nom et la valeur de la variable se trouvent dans une colonne, et la ou les cibles concernées dans l'autre colonne.
Étapes suivantes
Consultez le guide de démarrage rapide: Utiliser des paramètres de déploiement.
Obtenez plus d'informations sur l'utilisation de déploiements en parallèle.