Créer une cible personnalisée

Ce document explique comment créer un type de cible Cloud Deploy personnalisé et l'utiliser comme cible dans un pipeline de livraison Cloud Deploy.

Voici le processus général pour créer un type de cible personnalisée et l'utiliser dans votre pipeline de livraison:

Créez une application conteneurisée ou des applications qui incluent la fonctionnalité à déployer sur votre cible personnalisée et qui répondent aux exigences Cloud Deploy pour les types de cibles personnalisées.
Définissez une action personnalisée dans skaffold.yaml qui référence ce conteneur et spécifie la ou les commandes à exécuter.
Créez une définition CustomTargetType en référençant l'action personnalisée de l'étape précédente et enregistrez-la en tant que ressource Cloud Deploy.
Définissez une nouvelle cible avec une propriété customTarget qui identifie votre nouveau type de cible personnalisée.
Référencez cette cible dans la progression de votre pipeline de livraison.
Créez une version.

Chacune de ces étapes est décrite en détail dans la suite de ce document.

Créer vos applications conteneurisées

La fonctionnalité à déployer sur votre cible personnalisée est définie dans les applications conteneurisées que vous fournissez à Cloud Deploy en les référençant à partir de votre fichier skaffold.yaml. Lorsque votre pipeline de livraison inclut une cible qui utilise un type de cible personnalisé, Cloud Deploy appelle les conteneurs d'actions personnalisées définis pour ce type de cible personnalisé dans Skaffold afin d'exécuter les actions de rendu et de déploiement que vous avez définies.

C'est à vous de décider du comportement de vos applications. Cependant, il doit utiliser les variables d'environnement d'entrée fournies par Cloud Deploy et doit renvoyer les résultats requis.

Dans la plupart des cas, vous devez créer un conteneur pour votre action de rendu et un autre pour votre action de déploiement, pour chaque type de cible personnalisée que vous créez. L'action de rendu est facultative, mais si vous n'en fournissez pas, Cloud Deploy utilise la valeur par défaut skaffold render.

Définir vos actions personnalisées dans Skaffold

Une fois en place les images de conteneur d'action personnalisée, vous les référencez à partir de votre fichier de configuration skaffold.yaml.

Vous configurez chaque action personnalisée pour une cible personnalisée dans un bloc customActions. Pour tout type de cible personnalisée, vous créez une action personnalisée dans Skaffold pour le rendu et une autre pour le déploiement. La définition CustomTargetType identifie l'action personnalisée utilisée pour le rendu et celle utilisée pour le déploiement.

Voici la configuration pour les actions de rendu et de déploiement personnalisées dans skaffold.yaml:

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

Dans cette configuration Skaffold:

customActions.name

Nom arbitraire de l'action de rendu ou de déploiement personnalisé. La définition CustomTargetType fait référence à ce nom dans la propriété renderAction ou deployAction.
Le bloc containers inclut votre référence, ainsi que les commandes permettant d'exécuter ce conteneur.

Le bloc containers autorise plusieurs conteneurs, mais Google vous recommande de n'en utiliser qu'un seul.
customActions.containers.name

Nom arbitraire du conteneur spécifique que vous utilisez pour cette action. Il est recommandé de toujours utiliser ce nom de conteneur avec la qualification SHA.
image

est le chemin d'accès à l'image de conteneur ;
command

est la ou les commandes à exécuter sur le conteneur ;
args

est un ensemble d'arguments de l'command ;

Consultez la documentation de référence YAML de Skaffold pour obtenir une documentation détaillée sur les propriétés de configuration utilisées dans customActions.

Définir votre type de cible personnalisée

Pour définir une cible personnalisée, commencez par créer un type de cible personnalisée à l'aide de la configuration CustomTargetType. Vous pouvez créer le CustomTargetType dans le même fichier que la définition de votre pipeline de livraison, avec les définitions de cible ou dans un fichier distinct.

La définition de CustomTargetType est la suivante:

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

Où

CUSTOM_TARGET_TYPE_NAME

Nom arbitraire que vous attribuez à cette définition de type de cible personnalisée. Ce nom est référencé dans la définition de la cible pour toute cible qui utilise le type de cible personnalisé que vous définissez.
RENDER_ACTION_NAME

est le nom de l'action de rendu personnalisé. Cette valeur correspond au customAction.name défini dans skaffold.yaml pour l'action de rendu.
DEPLOY_ACTION_NAME

est le nom de l'action de déploiement personnalisé. Cette valeur correspond au customAction.name défini dans skaffold.yaml pour l'action deploy.
includeSkaffoldModules

stanza facultatif à utiliser si vous employez des configurations Skaffold distantes ; Les propriétés de ce bloc sont présentées dans la section Utiliser des configurations Skaffold distantes.

Utiliser des configurations Skaffold distantes

Vous pouvez stocker les configurations Skaffold dans un dépôt Git public ou dans un bucket Cloud Storage, puis référencer ces configurations à partir de votre définition de type de cible personnalisée.

Si vous utilisez des configurations Skaffold distantes, il n'est pas nécessaire que les actions personnalisées soient définies pour le skaffold.yaml que vous fournissez au moment du lancement. Cela permet de partager des actions personnalisées au sein de votre organisation.

Pour utiliser les configurations Skaffold distantes:

Créer une configuration Skaffold avec une ou plusieurs actions personnalisées
Stockez la configuration dans un dépôt Git ou dans un bucket Cloud Storage.
Dans la définition du type de cible personnalisée, ajoutez un stanza customActions.includeSkaffoldModules.
Sous includeSkaffoldModules, spécifiez les éléments suivants:
- Un ou plusieurs éléments configs (facultatif) :
  
  - configs: ["name1", "name2"]
  
  La valeur de configs est une liste de chaînes correspondant à la propriété metadata.name de chaque configuration Skaffold à inclure. Si cette valeur est omise, Cloud Deploy accepte toutes les configurations du chemin d'accès spécifié.
- stanza googleCloudStorage ou git.
  
  Pour Cloud Storage:
```
googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME
```
  Pour Git:
```
git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME
```
  Où :
  
  PATH_TO_GCS_BUCKET est le chemin d'accès à un répertoire Cloud Storage, qui se termine par /*, où sont stockées les configurations Skaffold. Skaffold télécharge tous les fichiers de ce répertoire, puis recherche le fichier Skaffold approprié avec les configurations, en fonction du chemin d'accès relatif configuré.
  
  FILENAME est le nom du fichier qui inclut les configurations Skaffold. Cette propriété path: est facultative. Si vous ne la spécifiez pas, Cloud Deploy suppose la valeur skaffold.yaml. En l'absence de skaffold.yaml ou si le nom de fichier que vous spécifiez ne s'affiche pas, la création de la version échoue.
  
  REPO_URL est l'URL du dépôt Git.
  
  PATH_TO_FILE est le chemin d'accès au fichier contenant les configurations Skaffold dans ce dépôt.
  
  BRANCH_NAME est le nom de la branche (par exemple, main) à partir de laquelle extraire les configurations Skaffold.

Exemple

Le fichier YAML de type cible personnalisé suivant est un stanza customActions avec un stanza includeSkaffoldModules, pointant vers des configurations Skaffold stockées dans un bucket Cloud Storage:

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

Le fichier YAML suivant est une configuration Skaffold, référencée par l'action personnalisée illustrée:

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

Enregistrer votre type de cible personnalisée

Après avoir configuré CustomTargetType, exécutez la commande gcloud deploy apply pour enregistrer la ressource CustomTargetType dans un projet Google Cloud:

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

Où :

FILE est le nom du fichier dans lequel vous avez défini ce type de cible personnalisée.

PROJECT est le projet Google Cloud dans lequel créer cette ressource. L'élément CustomTargetType doit se trouver dans le même projet que la ressource Target qui le référence. Vous n'avez pas besoin de spécifier le projet si vous l'avez défini comme projet par défaut pour la Google Cloud CLI.

REGION est la région (par exemple, us-centra1) dans laquelle créer cette ressource. Le CustomTargetType doit se trouver dans la même région que la ressource Target qui le référence. Vous n'avez pas besoin de spécifier la région si vous l'avez définie comme région par défaut pour la gcloud CLI.

Maintenant que la CustomTargetType est créée en tant que ressource Cloud Deploy, vous pouvez l'utiliser dans une définition Target pour créer votre cible personnalisée.

Pour en savoir plus sur la définition de CustomTargetType, consultez la documentation de référence sur le schéma de configuration de Cloud Deploy.

Définir votre cible

La seule différence entre une définition de cible pour un type de cible compatible et une définition de cible personnalisée est que la définition de la cible personnalisée inclut un stanza customTarget. La syntaxe d'un élément customTarget est la suivante:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Où CUSTOM_TARGET_TYPE_NAME est la valeur de la propriété name définie dans la configuration du type de cible personnalisée.

Ajouter votre cible au pipeline de livraison

Vous pouvez utiliser une cible personnalisée dans un pipeline de livraison exactement comme vous utiliseriez un type de cible compatible. Autrement dit, il n'y a aucune différence dans la progression du pipeline de livraison entre les cibles d'un type de cible compatible et les cibles personnalisées.

Toutes les cibles d'un pipeline de livraison doivent utiliser le même type de cible. Par exemple, vous ne pouvez pas disposer d'un pipeline de livraison avec certaines cibles déployées sur Google Kubernetes Engine et d'autres cibles personnalisées.

Comme pour les types de cibles compatibles, vous pouvez inclure des paramètres de déploiement à l'étape du pipeline.

Créer une version

Maintenant que votre type de cible personnalisée est entièrement défini et qu'une cible a été créée pour l'utiliser, vous pouvez maintenant créer une version selon la procédure habituelle:

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

Lors de la création de la version, votre action de rendu personnalisée est exécutée pour chaque cible de votre pipeline de livraison, y compris le traitement des paramètres de déploiement configurés sur la version, les cibles ou le pipeline de livraison. Cloud Deploy fournit les paramètres de déploiement en tant qu'entrée dans le conteneur de rendu personnalisé.

Afficher les résultats de vos cibles personnalisées

Si votre action personnalisée répond aux exigences concernant les cibles personnalisées, vous pouvez utiliser la console Google Cloud pour afficher les artefacts affichés.

Pour afficher le résultat de votre action d'affichage personnalisé, procédez comme suit :

Dans la console Google Cloud, accédez à la page Pipelines de livraison de Cloud Deploy pour afficher votre pipeline de livraison.

Ouvrir la page Pipelines de diffusion
Cliquez sur le nom de votre pipeline de livraison.

La visualisation du pipeline affiche l'état de déploiement de l'application, et votre version est répertoriée dans l'onglet Releases (Versions) sous Delivery pipeline details (Détails du pipeline de livraison).
Cliquez sur le nom de la version.

La page Détails de la release s'affiche.
Cliquez sur l'onglet Artefacts.
Sous Artefacts cibles, cliquez sur la flèche à côté de Afficher les artefacts.

Les artefacts de rendu sont répertoriés, y compris l'skaffold.yaml et le fichier manifeste générés par le moteur de rendu personnalisé. Vous pouvez également cliquer sur le lien Emplacement de stockage à côté de chacun d'eux pour accéder au bucket Cloud Storage et afficher ces fichiers.

Vous pouvez également cliquer sur le lien Afficher les artefacts pour afficher ces fichiers par version, par cible ou par phase, à l'aide de l'inspecteur de versions.

Étapes suivantes

Consultez le guide de démarrage rapide: définir et utiliser un type de cible personnalisé.
Consultez les exemples de types de cibles personnalisées disponibles.
Créez un pipeline de livraison et des cibles.
Découvrez comment configurer des cibles Cloud Deploy.