Cette page a été traduite par l'API Cloud Translation.

À propos des cibles personnalisées

Ce document décrit le fonctionnement des cibles personnalisées dans Cloud Deploy.

Cloud Deploy est compatible avec plusieurs environnements d'exécution en tant que cibles. Toutefois, la liste des types de cibles compatibles est limitée. Avec les cibles personnalisées, vous pouvez déployer sur d'autres systèmes que les environnements d'exécution compatibles.

Une cible personnalisée représente un environnement de sortie arbitraire autre qu'un environnement d'exécution compatible avec Cloud Deploy.

La page Créer une cible personnalisée décrit le processus de définition d'un type de cible personnalisée et de son implémentation en tant que cible dans un pipeline de diffusion.

Quelles sont les données d'une cible personnalisée ?

Chaque cible personnalisée se compose des composants suivants:

Actions personnalisées, définies dans skaffold.yaml

Ils sont similaires à la façon dont vous définissez les hooks de déploiement. Dans le fichier skaffold.yaml, vous définissez customActions, où chaque action personnalisée identifie une image de conteneur à utiliser et les commandes à exécuter sur ce conteneur.

Ainsi, la cible personnalisée n'est qu'une action ou un ensemble d'actions définies par l'utilisateur.

Pour chaque type de cible personnalisée, vous devez configurer une action de rendu personnalisée et une action de déploiement personnalisée. Ces actions consomment les valeurs fournies par Cloud Deploy et doivent répondre à un ensemble de sorties requises.

L'action d'affichage personnalisé est facultative, mais vous devez en créer une, sauf si votre cible personnalisée fonctionne correctement si elle est affichée par skaffold render, qui est l'option par défaut pour Cloud Deploy.
Une définition de type de cible personnalisée

CustomTargetType est une ressource Cloud Deploy qui identifie les actions personnalisées (définies séparément dans votre skaffold.yaml) que les cibles de ce type utilisent pour les activités de rendu de version et de déploiement de déploiement.
Une définition de cible

La définition de la cible pour une cible personnalisée est la même que pour tout type de cible, à l'exception qu'elle inclut la propriété customTarget, dont la valeur est le nom de l'CustomTargetType.

Une fois ces composants en place, vous pouvez utiliser la cible comme n'importe quelle cible, en la référençant à partir de la progression de votre pipeline de diffusion et en profitant pleinement des fonctionnalités de Cloud Deploy, telles que la promotion et les approbations, ainsi que les rollbacks.

Exemple

La procédure de démarrage rapide Définir et utiliser un type de cible personnalisé crée un type de cible personnalisé qui inclut des commandes simples à exécuter sur une image de conteneur : une commande pour le rendu et une pour le déploiement. Dans ce cas, les commandes ne font qu'ajouter du texte aux fichiers de sortie requis pour l'affichage et le déploiement.

Pour en savoir plus, consultez la section Exemples de cibles personnalisées.

Entrées et sorties requises

Tout type de cible personnalisée défini pour Cloud Deploy doit respecter les exigences d'entrée et de sortie, à la fois pour le rendu et le déploiement. Cette section liste les entrées et les sorties requises, ainsi que la manière dont elles sont fournies.

Cloud Deploy fournit les entrées requises, à la fois pour l'affichage et le déploiement, en tant que variables d'environnement. Les sections suivantes listent ces entrées, ainsi que les sorties que vos actions de rendu et de déploiement personnalisées doivent renvoyer.

Déployer des paramètres en tant que variables d'environnement

En plus des variables d'environnement listées dans cette section, Cloud Deploy peut transmettre à vos conteneurs personnalisés tous les paramètres de déploiement que vous avez définis.

Entrées pour les actions d'affichage

Pour les actions de rendu personnalisées, Cloud Deploy fournit les entrées requises suivantes en tant que variables d'environnement. Pour les déploiements en plusieurs phases (déploiements canari), Cloud Deploy fournit ces variables pour chaque phase.

CLOUD_DEPLOY_PROJECT

Projet Google Cloud dans lequel le type de cible personnalisée est créé.
CLOUD_DEPLOY_LOCATION

Région Google Cloud du type de cible personnalisée.
CLOUD_DEPLOY_DELIVERY_PIPELINE

Nom du pipeline de diffusion Cloud Deploy référençant le type de cible personnalisée.
CLOUD_DEPLOY_RELEASE

Nom de la version pour laquelle l'opération de rendu est appelée.
CLOUD_DEPLOY_TARGET

Nom de la cible Cloud Deploy qui utilise le type de cible personnalisée.
CLOUD_DEPLOY_PHASE

Phase de déploiement à laquelle le rendu correspond.
CLOUD_DEPLOY_REQUEST_TYPE

Pour l'action de rendu personnalisée, la valeur est toujours RENDER.
CLOUD_DEPLOY_FEATURES

Liste des fonctionnalités Cloud Deploy séparées par une virgule que le conteneur personnalisé doit prendre en charge. Cette variable est renseignée en fonction des fonctionnalités configurées dans votre pipeline de diffusion.

Si votre implémentation n'est pas compatible avec les fonctionnalités de cette liste, nous vous recommandons de l'arrêter lors du rendu.

Pour les déploiements standards, ce champ est vide. Pour les déploiements Canary, la valeur est CANARY. Si la valeur fournie par Cloud Deploy est CANARY, votre action de rendu est appelée pour chaque phase du canari. Le pourcentage de canari pour chaque phase est fourni dans la variable d'environnement CLOUD_DEPLOY_PERCENTAGE_DEPLOY.
CLOUD_DEPLOY_PERCENTAGE_DEPLOY

Pourcentage de déploiement associé à cette opération de rendu. Si la variable d'environnement CLOUD_DEPLOY_FEATURES est définie sur CANARY, votre action de rendu personnalisée est appelée pour chaque phase, et cette variable est définie sur le pourcentage de canari pour chaque phase. Pour les déploiements standards et les déploiements Canary ayant atteint la phase stable, il s'agit de 100.
CLOUD_DEPLOY_STORAGE_TYPE

Fournisseur de stockage. Toujours GCS.
CLOUD_DEPLOY_INPUT_GCS_PATH

Chemin d'accès Cloud Storage de l'archive de fichiers de rendu écrite lors de la création de la version.
CLOUD_DEPLOY_OUTPUT_GCS_PATH

Chemin d'accès Cloud Storage dans lequel le conteneur de rendu personnalisé doit importer les artefacts à utiliser pour le déploiement. Notez que l'action de rendu doit importer un fichier nommé results.json contenant les résultats de cette opération de rendu. Pour en savoir plus, consultez la section Sorties de l'action de rendu.

Sorties de l'action de rendu

Votre action de rendu personnalisée doit fournir les informations décrites dans cette section. Les informations doivent être incluses dans le fichier de résultats, nommé results.json, situé dans le bucket Cloud Storage fourni par Cloud Deploy.

Fichier ou fichiers de configuration affichés
Un fichier results.json contenant les informations suivantes:
- Indique l'état de réussite ou d'échec de l'action personnalisée.
  
  Les valeurs valides sont SUCCEEDED et FAILED.
- (Facultatif) Tous les messages d'erreur générés par l'action personnalisée.
- Chemin d'accès Cloud Storage du ou des fichiers de configuration générés.
  
  Le chemin d'accès de tous les fichiers de configuration affichés est l'URI complet. Vous le renseignez en partie à l'aide de la valeur de l'CLOUD_DEPLOY_OUTPUT_GCS_PATH fournie par Cloud Deploy.
  
  Vous devez fournir le fichier de configuration généré, même s'il est vide. Le contenu du fichier peut être n'importe quoi, dans n'importe quel format, tant qu'il peut être consommé par votre action de déploiement personnalisée. Nous vous recommandons de rendre ce fichier lisible par l'humain afin que vous et les autres utilisateurs de votre organisation puissiez l'afficher dans l'inspecteur de version.
- (Facultatif) une carte de toutes les métadonnées que vous souhaitez inclure
  
  Votre cible personnalisée crée ces métadonnées. Ces métadonnées sont stockées dans la version, dans le champ custom_metadata.

Si vous devez examiner le fichier results.json, par exemple pour le débogage, vous pouvez trouver l'URI Cloud Storage correspondant dans les journaux Cloud Build.

Exemple de fichier de résultats de rendu

Voici un exemple de sortie de fichier results.json à partir d'une action de rendu personnalisée:

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Entrées pour déployer des actions

Pour les actions de déploiement personnalisées, Cloud Deploy fournit les entrées requises suivantes, sous forme de variables d'environnement:

CLOUD_DEPLOY_PROJECT

Projet Google Cloud dans lequel la cible personnalisée est créée.
CLOUD_DEPLOY_LOCATION

Région Google Cloud du type de cible personnalisée.
CLOUD_DEPLOY_DELIVERY_PIPELINE

Nom du pipeline de diffusion Cloud Deploy référençant la cible qui utilise le type de cible personnalisé.
CLOUD_DEPLOY_RELEASE

Nom de la version pour laquelle l'opération de déploiement est appelée.
CLOUD_DEPLOY_ROLLOUT

Nom du déploiement Cloud Deploy auquel ce déploiement est destiné.
CLOUD_DEPLOY_TARGET

Nom de la cible Cloud Deploy qui utilise le type de cible personnalisée.
CLOUD_DEPLOY_PHASE

Phase de déploiement à laquelle le déploiement correspond.
CLOUD_DEPLOY_REQUEST_TYPE

Pour l'action de déploiement personnalisé, la valeur est toujours DEPLOY.
CLOUD_DEPLOY_FEATURES

Liste des fonctionnalités Cloud Deploy séparées par une virgule que le conteneur personnalisé doit prendre en charge. Cette variable est renseignée en fonction des fonctionnalités configurées dans votre pipeline de diffusion.

Si votre implémentation n'est pas compatible avec les fonctionnalités de cette liste, nous vous recommandons de l'arrêter lors du rendu.

Pour les déploiements standards, ce champ est vide. Pour les déploiements Canary, la valeur est CANARY. Si la valeur fournie par Cloud Deploy est CANARY, votre action de rendu est appelée pour chaque phase du canari. Le pourcentage de canari pour chaque phase est fourni dans la variable d'environnement CLOUD_DEPLOY_PERCENTAGE_DEPLOY.
CLOUD_DEPLOY_PERCENTAGE_DEPLOY

Pourcentage de déploiement associé à cette opération de déploiement. Si la variable d'environnement CLOUD_DEPLOY_FEATURES est définie sur CANARY, votre action de déploiement personnalisée est appelée pour chaque phase, et cette variable est définie sur le pourcentage de canari pour chaque phase. Votre action de déploiement doit s'exécuter pour chaque phase.
CLOUD_DEPLOY_STORAGE_TYPE

Fournisseur de stockage. Toujours GCS.
CLOUD_DEPLOY_INPUT_GCS_PATH

Chemin d'accès Cloud Storage où le moteur de rendu personnalisé a écrit les fichiers de configuration générés.
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

Chemin d'accès Cloud Storage vers la configuration Skaffold générée.
CLOUD_DEPLOY_MANIFEST_GCS_PATH

Chemin d'accès Cloud Storage au fichier manifeste généré.
CLOUD_DEPLOY_OUTPUT_GCS_PATH

Chemin d'accès au répertoire Cloud Storage dans lequel le conteneur de déploiement personnalisé doit importer les artefacts de déploiement. Pour en savoir plus, consultez la section Sorties de l'action de déploiement.

Sorties de l'action de déploiement

Votre action de déploiement personnalisée doit écrire un fichier de sortie results.json. Ce fichier doit se trouver dans le bucket Cloud Storage fourni par Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

Le fichier doit inclure les éléments suivants:

Indique l'état de réussite ou d'échec de l'action de déploiement personnalisée.

Voici les états valides:
- SUCCEEDED
- FAILED
- SKIPPED (pour les déploiements Canary où les phases Canary sont ignorées pour passer directement à stable.)
(Facultatif) Liste des fichiers d'artefact de déploiement, sous la forme de chemins d'accès Cloud Storage

Le chemin d'accès correspond à l'URI complet. Vous le remplissez en partie à l'aide de la valeur de l'CLOUD_DEPLOY_OUTPUT_GCS_PATH fournie par Cloud Deploy.

Les fichiers listés ici sont renseignés dans les ressources d'exécution de tâche en tant qu'artefacts de déploiement.
(Facultatif) Un message d'échec, si l'action de déploiement personnalisée échoue (en renvoyant un état FAILED)

Ce message permet de renseigner failure_message sur l'exécution de la tâche pour cette action de déploiement.
(Facultatif) Un message de saut, pour fournir des informations supplémentaires si l'action renvoie un état SKIPPED.
(Facultatif) une carte de toutes les métadonnées que vous souhaitez inclure

Votre cible personnalisée crée ces métadonnées. Ces métadonnées sont stockées dans l'exécution de la tâche et dans le déploiement, dans le champ custom_metadata.

Si vous devez examiner le fichier results.json, par exemple pour le débogage, vous pouvez trouver l'URI Cloud Storage dans les journaux de rendu de la version Cloud Build.

Exemple de fichier de résultats de déploiement

Voici un exemple de sortie de fichier results.json à partir d'une action de déploiement personnalisée:

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

En savoir plus sur les actions personnalisées

Voici quelques points à prendre en compte lorsque vous configurez et utilisez des types de cibles personnalisés.

Exécuter les actions personnalisées

Vos actions de rendu et de déploiement personnalisées s'exécutent dans l'environnement d'exécution Cloud Deploy. Vous ne pouvez pas configurer vos actions personnalisées pour qu'elles s'exécutent sur un cluster Google Kubernetes Engine.

Utiliser des configurations Skaffold réutilisables et à distance

Comme décrit dans ce document, vous configurez votre action personnalisée dans le fichier skaffold.yaml fourni lors de la création de la version. Vous pouvez également stocker des configurations Skaffold dans un dépôt Git ou dans un bucket Cloud Storage, et les faire référence à partir de votre définition de type de cible personnalisée. Vous pouvez ainsi utiliser des actions personnalisées définies et stockées dans un seul emplacement partagé, au lieu d'inclure les actions personnalisées avec le fichier skaffold.yaml de chaque version.

Cibles personnalisées et stratégies de déploiement

Les cibles personnalisées sont entièrement compatibles avec les déploiements standards.

Cloud Deploy est compatible avec les déploiements Canary, à condition que le moteur de rendu et le programme de déploiement personnalisés soient compatibles avec la fonctionnalité Canary.

Vous devez utiliser une configuration personnalisée du canari. Les canaris automatisés et personnalisés ne sont pas acceptés.

Cibles personnalisées et paramètres de déploiement

Vous pouvez utiliser des paramètres de déploiement avec des cibles personnalisées. Vous pouvez les définir à l'étape du pipeline de diffusion, sur la cible qui utilise un type de cible personnalisée ou sur la version.

Les paramètres de déploiement sont transmis à vos conteneurs de rendu et de déploiement personnalisés, en tant que variables d'environnement, en plus de ceux déjà fournis.

Exemples de cibles personnalisées

Le dépôt cloud-deploy-samples contient un ensemble d'exemples d'implémentations de cibles personnalisées. Les exemples suivants sont disponibles:

GitOps
Vertex AI
Terraform
Infrastructure Manager
Helm

Chaque exemple inclut un guide de démarrage rapide.

Ces exemples ne sont pas des produits Google Cloud compatibles et ne sont pas couverts par un contrat d'assistance Google Cloud. Pour signaler des bugs ou demander des fonctionnalités dans un produit Google Cloud, contactez l'assistance Google Cloud.

Étape suivante

Maintenant que vous savez ce que sont les cibles personnalisées, découvrez comment les configurer et les utiliser.
Suivez le guide de démarrage rapide: Définir et utiliser un type de cible personnalisé.
Découvrez comment configurer des cibles Cloud Deploy.
Découvrez les environnements d'exécution de Cloud Deploy.