Intégrer Google Cloud Deploy à votre système CI

Ce document explique comment appeler votre pipeline de diffusion Google Cloud Deploy à partir de votre système d'intégration continue (CI).

Pour intégrer Google Cloud Deploy à votre système CI, il suffit d'ajouter un appel à la CLI Google Cloud Deploygcloud Cet appel a lieu au moment de votre pipeline CI où votre application est prête à être déployée.

Avant de commencer

Les instructions de cette page supposent que vous remplissez déjà les conditions suivantes:

Vous avez activé les API applicables.
Vous avez au moins un pipeline de livraison défini et enregistré auprès de Google Cloud Deploy.
Vous avez au moins une cible définie, et votre pipeline de livraison fait référence à cette cible.

Appeler Google Cloud Deploy à partir de votre pipeline CI

La commande suivante crée une version, appelant ainsi une instance de pipeline de livraison:

gcloud deploy releases create RELEASE_NAME \
  --delivery-pipeline=PIPELINE_NAME \
  --region=REGION
  --annotations=[KEY=VALUE,...]
  --images=[IMAGE_LIST]

Où...

RELEASE_NAME

est le nom que vous donnez à cette version. Veuillez indiquer une valeur.

Vous pouvez spécifier des noms de versions dynamiques en incluant '$DATE', '$TIME' ou les deux. Par exemple, si vous appelez cette commande à 15h07 UTC, 'rel-$TIME' renvoie rel-1507. '$DATE' et '$TIME' doivent être entre guillemets simples.
PIPELINE_NAME

est le nom du pipeline de livraison enregistré. Veuillez indiquer une valeur.
REGION

correspond à la région dans laquelle vous créez cette version. La région ne doit pas nécessairement être la même que celle dans laquelle vous déployez votre application.
[KEY=VALUE,...]

est une liste facultative d'une ou de plusieurs annotations à appliquer à la version, sous la forme de paires clé/valeur.

Vous pouvez utiliser des annotations pour suivre la provenance des versions, par exemple en transmettant une annotation telle que commitId=0065ca0. Toutes les annotations de la version sont renvoyées lorsque vous list ou get, et sont affichées avec la version dans Google Cloud Console. Vous pouvez donc également voir la provenance de la version.
[IMAGE_LIST]

correspond à une liste d'éléments de remplacement séparés par une virgule qui renvoient vers image-path-path. Exemple : --images=image1=path/to/image1:v1@sha256:45db24,image2=path/to/image2:v1@sha256:55xy18.

Cette valeur n'est pas obligatoire si vous transmettez --build-artifacts, qui identifie le fichier de sortie d'artefacts de compilation Skaffold.

Lorsque Google Cloud Deploy effectue le rendu du fichier manifeste, le nom de l'image dans le fichier manifeste non remplacé est remplacé par la référence complète de l'image dans le fichier manifeste. Autrement dit, image1, dans cet exemple, se trouve dans le fichier manifeste non affiché et est remplacé par path/to/image1:v1@sha256:45db24.

Exemple d'utilisation d'une référence d'image directe

La commande suivante crée une version en transmettant directement une référence d'image, plutôt qu'un fichier d'artefacts de compilation:

gcloud deploy releases create my-release \
  --delivery-pipeline=web-app \
  --region=us-central1
  --images=image1=path/to/image1:v1@sha256:45db24

Dans cet exemple, my-release est le nom de la version. Si vous souhaitez générer un nom de version en fonction de la date ou de l'heure, vous pouvez inclure '$DATE', 'TIME' ou les deux. L'heure correspond au temps UTC sur la machine sur laquelle vous appelez la commande. '$DATE' et '$TIME' doivent être entre guillemets simples.

Exemple :

gcloud deploy releases create rel-'$DATE'-'$TIME' \
  --delivery-pipeline=web-app \
  --region=us-central1
  --images=image1=path/to/image1:v1@sha256:45db24

Dans cet exemple, la commande génère un nom de version avec le préfixe rel-, ainsi que la date et l'heure, par exemple : rel-20220131-1507.

Il est également courant d'utiliser le SHA SHA dans un nom de version. Consultez les exemples Cloud Build et Docker de ce document.

Artefacts de compilation et images

Sur la commande gcloud deploy releases create, vous pouvez transmettre un ensemble de références d'images ou de référence de fichier d'artefacts de compilation.

Utilisez --images=[NAME=TAG,...] pour faire référence à une ou plusieurs images de conteneurs individuelles.

Cette valeur est une référence à un ensemble de remplacements de nom d'image spécifique par un chemin complet d'image. Exemple :

gcloud deploy releases create my-release --images=image1=path/to/image1:v1@sha256:45db24
Utilisez --build-artifacts= pour pointer vers un fichier de sortie Skaffold.

Exemples Cloud Build, transmission d'un fichier d'artefacts de compilation

Exemple de compilation Docker

Le fichier YAML suivant illustre Cloud Build pour le déploiement d'image Docker build, puis crée une version Google Cloud Deploy.

Cet exemple crée et transfère une image vers un dépôt d'artefacts, puis construit une commande pour créer une version, avec un nom de version basé sur le SHA court du commit. Cet exemple doit être utilisé en tant que déclencheur Cloud Build SCM, car il repose sur la variable $COMMIT_SHA.

Cet exemple envoie une image à une étiquette Docker qui est identique au hachage de commit du dépôt source. Le même hachage de commit, quant à lui, est référencé à partir des arguments release-command.

steps:
# Build and tag using commit sha
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '.', '-t', 'REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}', '-f', 'Dockerfile']
# Push the container image
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}']
# Create release in Google Cloud Deploy
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args:
    [
      "deploy", "releases", "create", "rel-${SHORT_SHA}",
      "--delivery-pipeline", "PIPELINE_NAME",
      "--region", "us-central1",
      "--annotations", "commitId=${REVISION_ID}",
      "--images", "IMAGE_NAME=REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}"
    ]

Notez que le nom de l'image à la fin de cet exemple, "--images", "IMAGE_NAME=, est remplacé dans le fichier manifeste par la référence complète de l'image.

Exemple de configuration Cloud Build avec Skaffold

Le fichier YAML suivant est le contenu d'une configuration de compilation Cloud Build incluant un appel à Google Cloud Deploy pour créer une version, avec un nom de version basé sur la date. Cet exemple montre également Skaffold utilisé pour la compilation.

steps:
- name: gcr.io/k8s-skaffold/skaffold
  args:
    - skaffold
    - build
    - '--interactive=false'
    - '--file-output=/workspace/artifacts.json'
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args:
    [
      "deploy", "releases", "create", "rel-${SHORT_SHA}",
      "--delivery-pipeline", "PIPELINE_NAME",
      "--region", "us-central1",
      "--annotations", "commitId=${REVISION_ID}",
      "--build-artifacts", "/workspace/artifacts.json"
    ]

Utiliser les annotations pour suivre la provenance de l'album

L'option --annotations= vous permet d'appliquer une ou plusieurs paires clé/valeur arbitraires à la version créée par cette commande. Vous devez ajouter cette option à la commande gcloud deploy releases create.

Par exemple, vous pouvez utiliser les paires clé/valeur suivantes pour suivre la source de l'image à déployer.

Exemple :

gcloud deploy releases create web-app-1029rel \
  --delivery-pipeline=web-app \
  --region=us-central1
  --annotations=commitId=0065ca0,author=user@company.com
  --images=image1=path/to/image1:v1@sha256:45db24

Vous pouvez également créer une annotation dont la valeur est l'URL pointant vers la requête d'extraction, par exemple. Pour en savoir plus, consultez la page Utiliser des libellés et des annotations avec Google Cloud Deploy.