À propos des cibles personnalisées

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

Cloud Deploy est compatible avec différents environnements d'exécution en tant que cibles. Toutefois, la liste des types de cibles compatibles est limitée. Les cibles personnalisées vous permettent de déployer des applications sur d'autres systèmes que les runtimes 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é et de son implémentation en tant que cible dans un pipeline de livraison.

Qu'est-ce qu'une cible personnalisée ?

Chaque cible personnalisée se compose des éléments suivants :

  • Tâches qui définissent comment afficher et déployer votre type de cible personnalisé

    Vos implémentations du rendu personnalisé et du déploiement personnalisé consomment les valeurs fournies par Cloud Deploy et doivent répondre à un ensemble de sorties requises.

    Le rendu personnalisé est facultatif, mais vous devez en créer un, sauf si votre cible personnalisée fonctionne correctement si elle est affichée avec les rendus intégrés de Cloud Deploy.

  • Une définition de type de cible personnalisée

    CustomTargetType est une ressource Cloud Deploy qui identifie les tâches que les cibles de ce type utilisent pour les activités de rendu et de déploiement de versions.

  • Une définition de cible

    La définition de la cible pour une cible personnalisée est la même que pour n'importe quel type de cible, sauf qu'elle inclut la propriété customTarget, dont la valeur est le nom de CustomTargetType.

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

Exemple

Le démarrage rapide Définir et utiliser un type de cible personnalisé crée un type de cible personnalisé qui inclut des commandes à exécuter sur une image de conteneur (une commande 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 obtenir d'autres exemples, consultez Exemples de cibles personnalisées.

Entrées et sorties requises

Tout type de cible personnalisé 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 sorties requises, et explique comment les fournir.

Cloud Deploy fournit les entrées requises, pour le rendu et le déploiement, en tant que variables d'environnement. Les sections suivantes listent ces entrées, ainsi que les sorties que votre rendu et déploiement personnalisés 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.

En savoir plus

Entrées pour les rendus personnalisés

Pour les rendus personnalisés, Cloud Deploy fournit les entrées suivantes en tant que variables d'environnement. Pour les déploiements progressifs en plusieurs phases (déploiements Canary), Cloud Deploy fournit ces variables pour chaque phase.

  • CLOUD_DEPLOY_PROJECT

    Numéro du projet Google Cloud dans lequel la cible personnalisée est créée.

  • CLOUD_DEPLOY_PROJECT_ID

    ID du projet Google Cloud .

  • CLOUD_DEPLOY_LOCATION

    Région Google Cloud pour le 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ée.

  • CLOUD_DEPLOY_PHASE

    La phase de déploiement à laquelle correspond le rendu.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Pour le rendu personnalisé, cette valeur est toujours RENDER.

  • CLOUD_DEPLOY_FEATURES

    Liste de 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 ne prend pas en charge les fonctionnalités de cette liste, nous vous recommandons qu'elle échoue 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 rendu est appelé pour chaque phase du déploiement Canary. Le pourcentage de canary 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 rendu personnalisé est appelé pour chaque phase, et cette variable est définie sur le pourcentage de canary pour chaque phase. Pour les déploiements standards et les déploiements Canary qui ont atteint la phase stable, la valeur est 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Fournisseur de stockage. Toujours GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Chemin d'accès Cloud Storage de 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 les artefacts à utiliser pour le déploiement. Notez que le rendu doit importer un fichier nommé results.json contenant les résultats de cette opération de rendu. Pour en savoir plus, consultez Sorties du rendu personnalisé.

Sorties du rendu personnalisé

Votre rendu personnalisé doit fournir les informations décrites dans cette section. Ces informations doivent figurer dans le fichier de résultats nommé results.json, qui se trouve dans le bucket Cloud Storage fourni par Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

  • Fichier ou fichiers de configuration rendus

  • Un fichier results.json contenant les informations suivantes :

    • Indication de l'état de réussite ou d'échec du rendu personnalisé.

      Les valeurs valides sont SUCCEEDED et FAILED.

    • (Facultatif) tous les messages d'erreur générés par le rendu personnalisé.

    • 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 est l'URI complet. Vous le remplissez en partie à l'aide de la valeur fournie par Cloud Deploy pour CLOUD_DEPLOY_OUTPUT_GCS_PATH.

      Vous devez fournir le fichier de configuration rendu, même s'il est vide. Le contenu du fichier peut être n'importe quoi, dans n'importe quel format, tant qu'il est utilisable par votre déploiement personnalisé. Nous vous recommandons de faire en sorte que ce fichier soit lisible par un humain, afin que vous et les autres utilisateurs de votre organisation puissiez le consulter dans l'inspecteur de version.

    • (Facultatif) une carte 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 pour le débogage, vous pouvez trouver son URI Cloud Storage dans les journaux Cloud Build.

Exemple de fichier de résultats de rendu

Voici un exemple de fichier results.json généré par un rendu personnalisé :

{
  "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 les déploiements personnalisés

Pour les déploiements personnalisés, Cloud Deploy fournit les entrées suivantes en tant que variables d'environnement :

  • CLOUD_DEPLOY_PROJECT

    Numéro du projet Google Cloud dans lequel la cible personnalisée est créée.

  • CLOUD_DEPLOY_PROJECT_ID

    ID du projet Google Cloud .

  • CLOUD_DEPLOY_LOCATION

    Région Google Cloud pour le type de cible personnalisée.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Nom du pipeline de déploiement Cloud Deploy faisant référence à la cible qui utilise le type de cible personnalisée.

  • 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

    La phase de déploiement à laquelle correspond le déploiement.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Pour le déploiement personnalisé, cette valeur est toujours DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Liste de 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 ne prend pas en charge les fonctionnalités de cette liste, nous vous recommandons qu'elle échoue 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 déploiement est appelé pour chaque phase du déploiement Canary. Le pourcentage de canary 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 déploiement personnalisé est appelé pour chaque phase, et cette variable est définie sur le pourcentage de canary pour chaque phase. Votre 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 rendus.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Chemin d'accès Cloud Storage à la configuration Skaffold rendue. Si vous avez fourni une configuration Skaffold avec votre version.

  • 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é est censé importer les artefacts de déploiement. Pour en savoir plus, consultez Sorties du déploiement personnalisé.

Sorties du déploiement personnalisé

Votre déploiement personnalisé 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 l'état de réussite ou d'échec du déploiement personnalisé.

    Voici les états valides :

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Cela concerne les déploiements Canary pour lesquels les phases Canary sont ignorées afin de 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 fournie par Cloud Deploy pour CLOUD_DEPLOY_OUTPUT_GCS_PATH.

    Les fichiers listés ici sont renseignés dans les ressources d'exécution de job en tant qu'artefacts de déploiement.

  • (Facultatif) un message d'échec, si le déploiement personnalisé échoue (en renvoyant un état FAILED)

    Ce message est utilisé pour remplir le failure_message sur l'exécution du job pour ce déploiement.

  • (Facultatif) un message d'ignorance, pour fournir des informations supplémentaires si le déploiement renvoie un état SKIPPED.

  • (Facultatif) une carte 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 sur l'exécution du job et sur 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 son URI Cloud Storage dans les journaux Cloud Build.

Exemple de fichier de résultats de déploiement

Voici un exemple de fichier results.json généré par un déploiement personnalisé :

{
  "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 cibles personnalisées

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

Exécuter les tâches

Vos tâches 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 tâches pour qu'elles s'exécutent sur un cluster Google Kubernetes Engine.

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

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 déployeur personnalisés soient compatibles avec la fonctionnalité Canary.

Vous devez utiliser une configuration canary personnalisée. Les canaris automatiques et personnalisés ne sont pas compatibles avec les cibles personnalisé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 au niveau de l'étape du pipeline de diffusion, de la cible qui utilise un type de cible personnalisé ou de 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 un produit Google Cloud pris en charge 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