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é et l'utiliser dans votre pipeline de diffusion:

  1. Créez une application conteneurisée ou des applications qui incluent la fonctionnalité de déploiement sur votre cible personnalisée et qui répondent aux exigences de Cloud Deploy pour les types de cibles personnalisés.

  2. Définissez une action personnalisée dans skaffold.yaml qui fait référence à ce conteneur et spécifie la ou les commandes à exécuter dessus.

  3. Créez une définition CustomTargetType référençant l'action personnalisée de l'étape précédente, puis enregistrez-la en tant que ressource Cloud Deploy.

  4. Définissez une nouvelle cible avec une propriété customTarget qui identifie votre nouveau type de cible personnalisée.

  5. Référez-vous à cette cible dans la progression de votre pipeline de diffusion.

  6. Créez une version.

Chacune de ces étapes est décrite en détail dans le reste de ce document.

Créer vos applications conteneurisées

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

C'est vous qui choisissez le comportement de vos applications. Toutefois, il doit consommer les variables d'environnement d'entrée fournies par Cloud Deploy et renvoyer les sorties requises.

Dans la plupart des cas, vous créerez un conteneur pour votre action de rendu et un 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 skaffold render par défaut.

Définir vos actions personnalisées dans Skaffold

Une fois votre ou vos images de conteneur d'action personnalisées en place, 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 une strophe customActions. Pour chaque type de cible personnalisée, vous devez créer une action personnalisée, dans Skaffold, pour le rendu et une pour le déploiement. La définition CustomTargetType identifie l'action personnalisée utilisée pour l'affichage et celle utilisée pour le déploiement.

Voici la configuration des 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

    Il s'agit d'un nom arbitraire pour l'action de rendu ou de déploiement personnalisée. La définition de CustomTargetType fait référence à ce nom, dans la propriété renderAction ou la propriété deployAction.

  • La strophe containers inclut votre référence, ainsi que les commandes permettant d'exécuter ce conteneur.

    La strophe containers autorise plusieurs conteneurs, mais Google vous recommande de n'en utiliser qu'un seul.

  • customActions.containers.name

    Il s'agit d'un nom arbitraire pour le conteneur spécifique que vous utilisez pour cette action. Il est recommandé que ce nom de conteneur soit toujours qualifié par SHA.

  • image

    Indique le chemin d'accès à l'image du conteneur.

  • command

    Il s'agit de la ou des commandes à exécuter sur le conteneur.

  • args

    Il s'agit d'un ensemble d'arguments pour command.

Consultez la documentation de référence YAML de Skaffold pour obtenir des informations détaillées 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 la CustomTargetType dans le même fichier que la définition de votre pipeline de diffusion, avec des définitions de cibles 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ée que vous définissez.

  • RENDER_ACTION_NAME

    Nom de l'action de rendu personnalisée. Cette valeur correspond à l'customAction.name définie dans skaffold.yaml pour l'action rendu.

  • DEPLOY_ACTION_NAME

    Nom de l'action de déploiement personnalisée. Cette valeur correspond à l'customAction.name définie dans skaffold.yaml pour l'action deploy.

  • includeSkaffoldModules

    Il s'agit d'une strophe facultative à utiliser si vous utilisez des configurations Skaffold distantes. Les propriétés de cette strophe sont présentées dans la section Utiliser des configurations Skaffold distantes.

Utiliser des configurations Skaffold à distance

Vous pouvez stocker des configurations Skaffold dans un dépôt Git public, un bucket Cloud Storage ou un dépôt Cloud Build de deuxième génération, et référencer ces configurations à partir de votre définition de type de cible personnalisée.

L'utilisation de configurations Skaffold distantes signifie que les actions personnalisées n'ont pas besoin d'être définies pour le skaffold.yaml que vous fournissez au moment de la publication. Cela permet de partager des actions personnalisées dans l'ensemble de votre organisation.

Pour utiliser des configurations Skaffold à distance:

  1. Créez une configuration Skaffold avec votre ou vos actions personnalisées.

  2. Stockez la configuration dans un dépôt Git ou dans un bucket Cloud Storage.

  3. Dans la définition de votre type de cible personnalisée, ajoutez un stanza customActions.includeSkaffoldModules.

  4. Sous includeSkaffoldModules, spécifiez les éléments suivants:

    • Vous pouvez éventuellement ajouter un ou plusieurs éléments configs:

      - configs: ["name1", "name2"]

      La valeur de configs est une liste de chaînes qui correspondent à la propriété metadata.name de chaque configuration Skaffold à inclure. Si cet élément est omis, Cloud Deploy récupère toutes les configurations du chemin d'accès spécifié.

    • Une strophe googleCloudStorage, git ou googleCloudBuildRepo.

      Pour Cloud Storage:

      googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME

      Pour Git:

      git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      Pour les dépôts Cloud Build (2e génération):

       googleCloudBuildRepo:
  repository: PATH_TO_GCB_REPO
  path: PATH_TO_FILE
  ref: BRANCH_NAME

      Où :

      PATH_TO_GCS_BUCKET correspond au chemin d'accès à un répertoire Cloud Storage, se terminant par /*, dans lequel les configurations Skaffold sont stockées. Skaffold télécharge tous les fichiers de ce répertoire, puis trouve le fichier Skaffold approprié avec les configurations, en fonction du chemin relatif configuré.

      PATH_TO_GCB_REPO correspond au chemin d'accès au dépôt Cloud Build 2e génération dans lequel sont stockées les configurations Skaffold. Le chemin d'accès se présente sous la forme suivante : projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}. Skaffold télécharge tous les fichiers de ce répertoire, puis trouve le fichier Skaffold 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 skaffold.yaml. Si aucun skaffold.yaml n'est défini ou si le nom de fichier que vous spécifiez n'y figure 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 dans ce dépôt au fichier contenant les configurations Skaffold.

      BRANCH_NAME est le nom de la branche (par exemple, main) à partir de laquelle prendre les configurations Skaffold.

Exemple

Le fichier YAML de type de cible personnalisé suivant est une strophe customActions avec une strophe includeSkaffoldModules, qui pointe 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, que l'action personnalisée affichée fait référence:

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. Le 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. CustomTargetType doit se trouver dans la même région que la ressource Target qui la 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 CustomTargetType a été créé 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 du schéma de configuration 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 cible personnalisée inclut une strophe customTarget. La syntaxe d'un customTarget est la suivante:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Où CUSTOM_TARGET_TYPE_NAME correspond à la valeur de la propriété name définie dans votre configuration de type de cible personnalisée.

Ajouter votre cible au pipeline de diffusion

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

Toutes les cibles d'un pipeline de diffusion doivent utiliser le même type de cible. Par exemple, vous ne pouvez pas avoir de pipeline de livraison avec des 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

Une fois votre type de cible personnalisée entièrement défini et une cible créée pour utiliser ce type, vous pouvez créer une version de la manière 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 diffusion, y compris le traitement des paramètres de déploiement configurés sur la version, les cibles ou le pipeline de diffusion. Cloud Deploy fournit les paramètres de déploiement en entrée au conteneur de rendu personnalisé.

Afficher le résultat de vos cibles personnalisées

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

Pour afficher la sortie de votre action de rendu personnalisée, procédez comme suit :

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

    Ouvrir la page Pipelines de diffusion

  2. Cliquez sur le nom de votre pipeline de diffusion.

    La visualisation du pipeline indique l'état de déploiement de l'application, et votre version est listée dans l'onglet Versions sous Détails du pipeline de diffusion.

  3. Cliquez sur le nom de la version.

    La page Détails de la version s'affiche.

  4. Cliquez sur l'onglet Artefacts.

  5. Sous Artefacts cibles, cliquez sur la flèche à côté de Afficher les artefacts.

    Les artefacts affichés sont listés, y compris le fichier skaffold.yaml affiché et le fichier manifeste affiché généré 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 version.

Étape suivante