Ce document décrit le fonctionnement des cibles personnalisées dans Cloud Deploy.
Cloud Deploy est compatible avec divers environnements d'exécution en tant que cibles. Mais la liste des types de cibles compatibles est finie. Les cibles personnalisées vous permettent d'effectuer des déploiements sur des systèmes autres que les environnements d'exécution compatibles.
Une cible personnalisée est une cible qui 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 livraison.
À quoi correspond une cible personnalisée ?
Chaque cible personnalisée comprend les composants suivants:
Actions personnalisées, définies dans
skaffold.yaml
Ils sont semblables à la façon dont vous définissez des hooks de déploiement. Dans le fichier
skaffold.yaml
, définissezcustomActions
, où chaque action personnalisée identifie une image de conteneur à utiliser et les commandes à exécuter sur ce conteneur.De cette manière, la cible personnalisée est simplement une action ou un ensemble d'actions personnalisés.
Pour tout type de cible personnalisée, vous configurez 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 exécuter un ensemble de résultats requis.
L'action de rendu personnalisée est facultative, mais vous devez en créer une, sauf si votre cible personnalisée fonctionnera correctement si elle est affichée par
skaffold render
(paramètre par défaut pour Cloud Deploy).Une définition du type de cible personnalisée
CustomTargetType
est une ressource Cloud Deploy qui identifie les actions personnalisées (définies séparément dans votre fichierskaffold.yaml
) qui ciblent ce type d'utilisation pour les activités de rendu de version et de déploiement.-
La définition de la cible d'une cible personnalisée est la même que pour tout type de cible, sauf qu'elle inclut la propriété
customTarget
, dont la valeur est le nom deCustomTargetType
.
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 livraison et en utilisant pleinement les fonctionnalités de Cloud Deploy, telles que la promotion et les approbations, ainsi que les rollbacks.
Exemple
Dans le guide de démarrage rapide, Définir et utiliser un type de cible personnalisée crée un type de cible personnalisée comprenant des commandes simples à exécuter sur une image de conteneur (une pour le rendu et une pour le déploiement). Dans ce cas, les commandes ajoutent simplement du texte aux fichiers de sortie requis pour le rendu et le déploiement.
Pour plus d'exemples, consultez Exemples de cibles personnalisées.
Entrées et sorties requises
Tout type de cible personnalisée défini pour Cloud Deploy doit répondre aux exigences d'entrée et de sortie, pour le rendu et le déploiement. Cette section liste les entrées et les sorties requises, et la manière dont elles sont fournies.
Cloud Deploy fournit les entrées requises, pour le rendu et le déploiement, en tant que variables d'environnement. Les sections suivantes répertorient ces entrées, ainsi que les sorties que vos actions de rendu et de déploiement personnalisées doivent renvoyer.
Déployer les paramètres en tant que variables d'environnement
Outre les variables d'environnement répertoriées dans cette section, Cloud Deploy peut transmettre à vos conteneurs personnalisés tous les paramètres de déploiement que vous avez définis.
Les paramètres de déploiement prévus en tant qu'entrées pour les cibles personnalisées doivent commencer par customTarget/
(par exemple, customTarget/vertexAIModel
). Lorsque vous référencez un paramètre de déploiement en tant que variable d'environnement, utilisez la syntaxe suivante:
CLOUD_DEPLOY_customTarget_[VAR_NAME]
Où VAR_NAME
est le nom situé après la barre oblique dans le nom du paramètre de déploiement. Par exemple, si vous définissez un paramètre de déploiement nommé customTarget/vertexAIModel
, référencez-le en tant que CLOUD_DEPLOY_customTarget_vertexAIModel
.
Entrées pour l'affichage des actions
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 Canary), 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 livraison Cloud Deploy faisant référence au 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é.
CLOUD_DEPLOY_PHASE
Phase de déploiement à laquelle le rendu correspond.
CLOUD_DEPLOY_REQUEST_TYPE
Pour l'action de rendu personnalisé, la valeur correspond toujours à
RENDER
.CLOUD_DEPLOY_FEATURES
Liste des fonctionnalités Cloud Deploy que le conteneur personnalisé doit accepter, séparées par une virgule. Cette variable est renseignée en fonction des fonctionnalités configurées dans votre pipeline de livraison.
Si votre implémentation n'est pas compatible avec les fonctionnalités de cette liste, nous vous recommandons de faire échouer l'affichage lors de l'affichage.
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 estCANARY
, votre action de rendu est appelée pour chaque phase de la version Canary. Le pourcentage Canary pour chaque phase est fourni dans la variable d'environnementCLOUD_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 surCANARY
, votre action de rendu personnalisée est appelée pour chaque phase, et cette variable est définie sur le pourcentage Canary pour chaque phase. Pour les déploiements standards et pour les déploiements Canary qui ont atteint la phasestable
, il s'agit de100
.CLOUD_DEPLOY_STORAGE_TYPE
Fournisseur de stockage Toujours
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
Chemin d'accès Cloud Storage à l'archive du fichier de rendu écrite lors de la création de la version.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
Chemin d'accès Cloud Storage où le conteneur de rendu personnalisé doit importer des 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.
Le ou les fichiers de configuration affichés
Un fichier
results.json
contenant les informations suivantes:Indication de la réussite ou de l'échec de l'action personnalisée.
Les valeurs valides sont
SUCCEEDED
etFAILED
.(Facultatif) Tout message d'erreur généré par l'action personnalisée.
Chemin d'accès Cloud Storage pour le ou les fichiers de configuration rendus.
Le chemin d'accès à tous les fichiers de configuration affichés correspond à l'URI complet. Vous le remplissez en partie à l'aide de la valeur du champ
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fourni par Cloud Deploy.Vous devez fournir le fichier de configuration affiché, même s'il est vide. Le fichier peut comporter n'importe quel format et n'importe quel format, à condition qu'il puisse être utilisé par votre action de déploiement personnalisée. Nous vous recommandons de rendre ce fichier lisible afin que vous et les autres utilisateurs de votre organisation puissiez le consulter dans l'inspecteur de version.
(Facultatif) Un mappage des 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 à des fins de débogage, vous trouverez son URI Cloud Storage 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é, 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 livraison Cloud Deploy faisant référence à 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é.
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 correspond toujours à
DEPLOY
.CLOUD_DEPLOY_FEATURES
Liste des fonctionnalités Cloud Deploy que le conteneur personnalisé doit accepter, séparées par une virgule. Cette variable est renseignée en fonction des fonctionnalités configurées dans votre pipeline de livraison.
Si votre implémentation n'est pas compatible avec les fonctionnalités de cette liste, nous vous recommandons de faire échouer l'affichage lors de l'affichage.
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 estCANARY
, votre action de rendu est appelée pour chaque phase de la version Canary. Le pourcentage Canary pour chaque phase est fourni dans la variable d'environnementCLOUD_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 surCANARY
, votre action de déploiement personnalisée est appelée pour chaque phase, et cette variable est définie sur le pourcentage Canary pour chaque phase. Votre action de déploiement doit être exécutée pour chaque phase.CLOUD_DEPLOY_STORAGE_TYPE
Fournisseur de stockage Toujours
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
Chemin d'accès Cloud Storage dans lequel le moteur de rendu personnalisé a écrit les fichiers de configuration rendus.
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH
Chemin d'accès Cloud Storage à la configuration Skaffold affichée.
CLOUD_DEPLOY_MANIFEST_GCS_PATH
Chemin d'accès Cloud Storage au fichier manifeste rendu.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
Chemin d'accès au répertoire Cloud Storage dans lequel le conteneur de déploiement personnalisé doit importer des artefacts de déploiement. Pour en savoir plus, consultez la section Résultats de l'action de déploiement.
Résultats 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:
Indication de la réussite ou de l'échec de l'action de déploiement personnalisé.
Les états valides sont les suivants:
SUCCEEDED
FAILED
SKIPPED
(pour les déploiements Canary où les phases Canary sont ignorées, pour passer directement àstable
)
(Facultatif) Une 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 du champ
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fourni par Cloud Deploy.Les fichiers répertoriés ici sont insérés dans les ressources d'exécution de tâches en tant qu'artefacts de déploiement.
(Facultatif) Un message d'échec s'affiche si l'action de déploiement personnalisée échoue (renvoi d'un état
FAILED
).Ce message permet de renseigner le champ
failure_message
lors de l'exécution de la tâche pour cette action de déploiement.(Facultatif) Un message d'omission pour fournir des informations supplémentaires si l'action renvoie un état
SKIPPED
.(Facultatif) Un mappage des 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 le champ
custom_metadata
lors de l'exécution de la tâche et lors du déploiement.
Si vous devez examiner le fichier results.json
, par exemple à des fins de débogage, vous trouverez l'URI Cloud Storage correspondant 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 éléments à garder à l'esprit lorsque vous configurez et utilisez des types de cibles personnalisés.
Exécuter les actions personnalisées
Votre rendu personnalisé et vos actions de déploiement 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 distantes réutilisables
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. Toutefois, vous pouvez également stocker les configurations Skaffold dans un dépôt Git ou dans un bucket Cloud Storage, et les référencer à partir de votre définition de type de cible personnalisée.
Cela vous permet d'utiliser des actions personnalisées définies et stockées dans un emplacement unique et partagé, au lieu de les inclure dans 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 personnalisé et le déployeur soient compatibles avec la fonctionnalité Canary.
Vous devez utiliser une configuration Canary personnalisée. Les versions Canary automatisées et personnalisées ne sont pas acceptées.
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 livraison, sur la cible qui utilise un type de cible personnalisé ou sur la version.
Les paramètres de déploiement sont transmis à votre rendu personnalisé et les conteneurs de déploiement, 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 font pas partie 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.
Étapes suivantes
Maintenant que vous en savez plus sur les cibles personnalisées, découvrez comment les configurer et les utiliser.
Consultez 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.