Créez et ajoutez une action personnalisée dans CodePipeline - AWS CodePipeline

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Créez et ajoutez une action personnalisée dans CodePipeline

AWS CodePipeline inclut un certain nombre d'actions qui vous aident à configurer les ressources de création, de test et de déploiement pour votre processus de publication automatisé. Si votre processus de publication comprend des activités qui ne sont pas incluses dans les actions par défaut, par exemple un processus de génération développé en interne ou une suite de tests, vous pouvez créer une action personnalisée à ces fins et l'inclure dans votre pipeline. Vous pouvez utiliser le AWS CLI pour créer des actions personnalisées dans les pipelines associés à votre AWS compte.

Vous pouvez créer des actions personnalisées pour les catégories AWS CodePipeline d'actions suivantes :

  • Une action de génération personnalisée qui crée ou transforme les éléments

  • Une action de déploiement personnalisée qui déploie des éléments sur un ou plusieurs serveurs, sites web ou référentiels

  • Une action de test personnalisée qui configure et exécute les tests automatisés

  • Une action d'appel personnalisée qui exécute des fonctions

Lorsque vous créez une action personnalisée, vous devez également créer un assistant qui interrogera les demandes d'emploi CodePipeline pour cette action personnalisée, exécutera la tâche et renverra le résultat du statut à CodePipeline. Ce travailleur peut être localisé sur n'importe quel ordinateur ou ressource tant qu'il a accès au point de terminaison public pour CodePipeline. Pour gérer facilement l'accès et la sécurité, pensez à héberger votre collaborateur sur une instance Amazon EC2.

Le schéma suivant montre une vue globale d'un pipeline qui inclut une action de génération personnalisée :

Vue globale d'un pipeline qui inclut une action de génération personnalisée.

Lorsqu'un pipeline inclut une action personnalisée dans le cadre d'une étape, il crée une demande de travail. Un exécutant de tâches personnalisé détecte cette demande et exécute la tâche (dans cet exemple, un processus personnalisé s'appuyant sur un logiciel tiers). Lorsque l'action est terminée, l'exécutant de tâches affiche un résultat de réussite ou d'échec. Si un résultat positif est reçu, le pipeline fournira la révision et ses artefacts à l'action suivante. Si un échec est renvoyé, le pipeline ne fournira pas la révision de l'action suivante du pipeline.

Note

Ces instructions supposent que vous avez déjà réalisé les étapes dans Commencer avec CodePipeline.

Création d'une action personnalisée

Pour créer une action personnalisée à l'aide du AWS CLI
  1. Ouvrez un éditeur de texte et créez un fichier JSON pour votre action personnalisée qui inclut la catégorie de l'action, le fournisseur de l'action et tous les paramètres requis par l'action personnalisée. Par exemple, pour créer une action de génération personnalisée qui ne nécessite qu'une seule propriété, votre fichier JSON devrait ressembler à ceci :

    { "category": "Build", "provider": "My-Build-Provider-Name", "version": "1", "settings": { "entityUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/", "executionUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/lastSuccessfulBuild/{ExternalExecutionId}/" }, "configurationProperties": [{ "name": "ProjectName", "required": true, "key": true, "secret": false, "queryable": false, "description": "The name of the build project must be provided when this action is added to the pipeline.", "type": "String" }], "inputArtifactDetails": { "maximumCount": integer, "minimumCount": integer }, "outputArtifactDetails": { "maximumCount": integer, "minimumCount": integer }, "tags": [{ "key": "Project", "value": "ProjectA" }] }

    Cet exemple ajoute le balisage à l'action personnalisée en incluant la clé de balise Project et la valeur ProjectA sur l'action personnalisée. Pour plus d'informations sur le balisage des ressources CodePipeline, consultezBalisage des ressources.

    Deux propriétés sont incluses dans le fichier JSON, entityUrlTemplate et executionUrlTemplate. Vous pouvez désigner un nom dans les propriétés de configuration de l'action personnalisée dans les modèles d'URL, en suivant le format de {Config:name}, tant que la propriété de configuration est à la fois obligatoire et non secrète. Par exemple, dans l'exemple ci-dessus, la entityUrlTemplate valeur fait référence à la propriété de configuration ProjectName.

    • entityUrlTemplate : le lien statique qui fournit des informations sur le fournisseur de services pour l'action. Dans cet exemple, le système de génération comprend un lien statique pour chaque projet de génération. Le format du lien varie en fonction de votre fournisseur de génération (ou, si vous créez un type d'action différent, comme un test, l'autre fournisseur de services). Vous devez fournir ce format de lien de sorte à ce que lorsque l'action personnalisée est ajoutée, l'utilisateur puisse choisir ce lien pour ouvrir un navigateur sur une page de votre site web qui fournit les détails concernant le projet de génération (ou l'environnement de test).

    • executionUrlTemplate : le lien dynamique qui sera mis à jour avec des informations sur l'exécution actuelle ou la plus récente de l'action. Lorsque votre assistant de tâches personnalisé met à jour l'état d'une tâche (par exemple, réussite, échec, ou en cours), il fournit également un externalExecutionId qui sera utilisé pour finaliser le lien. Ce lien peut être utilisé pour fournir les détails relatifs à l'exécution d'une action.

    Par exemple, lorsque vous consultez l'action dans le pipeline, vous voyez les deux liens suivants :

    Les liens de la CodePipeline console permettent d'obtenir plus d'informations sur le fonctionnement d'un pipeline.

    Ce lien statique s'affiche lorsque vous avez ajouté votre action personnalisée et pointe vers l'adresse dans entityUrlTemplate, que vous spécifiez lorsque vous créez votre action personnalisée.

    Ce lien dynamique est mis à jour après chaque exécution de l'action et pointe vers l'adresse dans executionUrlTemplate, que vous spécifiez lorsque vous créez votre action personnalisée.

    Pour plus d'informations sur ces types de liens, ainsi que sur RevisionURLTemplate etThirdPartyURL, consultez ActionTypeSettingset CreateCustomActionTypedans le Guide de référence de l'CodePipeline API. Pour plus d'informations sur les exigences en termes de structure de l'action et sur la manière de créer une action, consultez CodePipeline référence de structure de pipeline.

  2. Enregistrez le fichier JSON et donnez-lui un nom facilement mémorisable (par exemple, MyCustomAction.json).

  3. Ouvrez une session de terminal (Linux, OS X, Unix) ou une invite de commande (Windows) sur un ordinateur où vous avez installé l' AWS CLI.

  4. Utilisez le AWS CLI pour exécuter la aws codepipeline create-custom-action-type commande, en spécifiant le nom du fichier JSON que vous venez de créer.

    Par exemple, pour créer une action personnalisée :

    Important

    N'oubliez pas d'inclure file:// devant le nom du fichier. Il est nécessaire dans cette commande.

    aws codepipeline create-custom-action-type --cli-input-json file://MyCustomAction.json
  5. Cette commande affiche l'intégralité de la structure de l'action personnalisée que vous avez créée, ainsi que la JobList propriété de la configuration de l'action, qui est ajoutée automatiquement. Lorsque vous ajoutez l'action personnalisée à un pipeline, vous pouvez utiliser JobList pour spécifier les projets du fournisseur, que vous pouvez solliciter pour les tâches. Si vous ne configurez pas ce réglage, toutes les tâches disponibles s'afficheront lorsque vous rechercherez des tâches avec l'exécutant de tâches personnalisé.

    Par exemple, la commande précédente peut afficher une structure similaire à ce qui suit :

    { "actionType": { "inputArtifactDetails": { "maximumCount": 1, "minimumCount": 1 }, "actionConfigurationProperties": [ { "secret": false, "required": true, "name": "ProjectName", "key": true, "description": "The name of the build project must be provided when this action is added to the pipeline." } ], "outputArtifactDetails": { "maximumCount": 0, "minimumCount": 0 }, "id": { "category": "Build", "owner": "Custom", "version": "1", "provider": "My-Build-Provider-Name" }, "settings": { "entityUrlTemplate": "https://my-build-instance/job/{Config:ProjectName}/", "executionUrlTemplate": "https://my-build-instance/job/mybuildjob/lastSuccessfulBuild/{ExternalExecutionId}/" } } }
    Note

    Dans le cadre de la sortie de la create-custom-action-type commande, la id section inclut"owner": "Custom". CodePipeline désigne automatiquement Custom en tant que propriétaire des types d'actions personnalisés. Cette valeur ne peut pas être attribuée ou modifiée lorsque vous utilisez la commande create-custom-action-type ou la commande update-pipeline.

Création d'un exécutant de tâches pour l'action personnalisée

Les actions personnalisées nécessitent un assistant qui interrogera CodePipeline les demandes de travail pour l'action personnalisée, exécutera la tâche et renverra le résultat du statut à CodePipeline. Le travailleur peut être localisé sur n'importe quel ordinateur ou ressource tant qu'il a accès au point de terminaison public pour CodePipeline.

Il existe plusieurs façons de concevoir votre exécutant de tâches. Les sections suivantes fournissent des conseils pratiques pour développer votre job worker personnalisé pour CodePipeline.

Choix et configuration d'une stratégie de gestion des autorisations pour votre exécutant de tâches

Pour développer un assistant personnalisé pour votre action personnalisée CodePipeline, vous aurez besoin d'une stratégie d'intégration de la gestion des utilisateurs et des autorisations.

La stratégie la plus simple consiste à ajouter l'infrastructure dont vous avez besoin pour votre assistant personnalisé en créant des instances Amazon EC2 avec un rôle d'instance IAM, ce qui vous permet d'augmenter facilement les ressources dont vous avez besoin pour votre intégration. Vous pouvez utiliser l'intégration intégrée AWS pour simplifier l'interaction entre votre travailleur personnalisé et CodePipeline.

Pour configurer des instances Amazon EC2
  1. Apprenez-en davantage sur Amazon EC2 et déterminez s'il s'agit du bon choix pour votre intégration. Pour plus d'informations, consultez Amazon EC2 - Hébergement de serveurs virtuels.

  2. Commencez à créer vos instances Amazon EC2. Pour plus d'informations, consultez Getting Started with Amazon EC2 Linux Instances.

Une autre stratégie à envisager consiste à utiliser la fédération d'identité avec IAM pour intégrer le système et les ressources de votre fournisseur d'identité existants. Cette stratégie est particulièrement utile si vous disposez déjà d'un fournisseur d'identité d'entreprise ou d'une configuration permettant de prendre en charge les utilisateurs à l'aide de fournisseurs d'identité web. La fédération d'identité vous permet d'accorder un accès sécurisé aux AWS ressources CodePipeline, notamment sans avoir à créer ou à gérer des utilisateurs IAM. Vous pouvez utiliser ces fonctionnalités et ces stratégies pour mettre en place des mots de passe à des fins de sécurité et pour créer une rotation des informations d'identification. Vous pouvez vous appuyer sur des modèles d'application pour créer votre propre modèle.

Mise en place de la fédération d'identité
  1. En savoir plus sur la fédération d'identité IAM. Pour plus d'informations, consultez Gestion de fédération.

  2. Passez en revue les exemples fournis dans Scénarios d'attribution d'accès temporaire afin d'identifier le scénario d'accès temporaire qui correspond le mieux aux besoins de votre action personnalisée.

  3. Passez en revue les exemples de code de fédération d'identité appropriés à votre infrastructure, tels que :

  4. Commencez à configurer la fédération d'identité. Pour plus d'informations, consultez la section Fournisseurs d'identité et fédération dans le guide de l'utilisateur IAM.

Créez l'une des options suivantes à utiliser sous votre nom Compte AWS lors de l'exécution de votre action personnalisée et de votre assistant de travail.

Les utilisateurs ont besoin d'un accès programmatique s'ils souhaitent interagir avec AWS l'extérieur du AWS Management Console. La manière d'accorder un accès programmatique dépend du type d'utilisateur qui y accède AWS.

Pour accorder aux utilisateurs un accès programmatique, choisissez l’une des options suivantes.

Quel utilisateur a besoin d’un accès programmatique ? Pour Par

Identité de la main-d’œuvre

(Utilisateurs gérés dans IAM Identity Center)

Utilisez des informations d'identification temporaires pour signer les demandes programmatiques adressées aux AWS CLI AWS SDK ou AWS aux API.

Suivez les instructions de l’interface que vous souhaitez utiliser.

IAM Utilisez des informations d'identification temporaires pour signer les demandes programmatiques adressées aux AWS CLI AWS SDK ou AWS aux API. Suivez les instructions de la section Utilisation d'informations d'identification temporaires avec AWS les ressources du Guide de l'utilisateur IAM.
IAM

(Non recommandé)

Utilisez des informations d'identification à long terme pour signer les AWS CLI demandes programmatiques adressées aux AWS SDK ou AWS aux API.

Suivez les instructions de l’interface que vous souhaitez utiliser.

Voici un exemple de stratégie que vous pouvez créer afin de l'utiliser avec votre exécutant de tâches personnalisé. Cette stratégie n'est fournie qu'à titre d'exemple, et « telle quelle ».

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codepipeline:PollForJobs", "codepipeline:AcknowledgeJob", "codepipeline:GetJobDetails", "codepipeline:PutJobSuccessResult", "codepipeline:PutJobFailureResult" ], "Resource": [ "arn:aws:codepipeline:us-east-2::actionType:custom/Build/MyBuildProject/1/" ] } ] }
Note

Envisagez d'utiliser la politique AWSCodePipelineCustomActionAccess gérée.

Développement d'un exécutant de tâches pour votre action personnalisée

Après avoir choisi votre stratégie de gestion des autorisations, vous devez réfléchir à la manière dont votre collaborateur va interagir avec lui CodePipeline. Le diagramme de haut niveau suivant montre le flux de travail d'une action personnalisée et d'un job worker pour un processus de création.

Le flux de travail d'une action personnalisée et d'un assistant pour un processus de création.
  1. Votre travailleur recherche des offres CodePipeline d'emploi en utilisantPollForJobs.

  2. Lorsqu'un pipeline est déclenché suite à une modification apportée à son étape source (par exemple, lorsqu'un développeur valide une modification), le processus de publication automatique commence. Le processus se poursuit jusqu'au stade où votre action personnalisée a été configurée. À ce stade, une tâche est mise en CodePipeline file d'attente lorsqu'elle atteint votre action. Cette tâche apparaît si votre exécutant de tâches interroge à nouveau PollForJobs pour obtenir l'état. Recueillez les détails de la tâche sur PollForJobs et communiquez-les à votre exécutant de tâches.

  3. Le travailleur appelle AcknowledgeJob pour envoyer CodePipeline un accusé de réception. CodePipeline renvoie un accusé de réception indiquant que le travailleur doit continuer le travail (InProgress), ou, si plusieurs travailleurs demandent des offres d'emploi et qu'un autre a déjà réclamé le poste, une réponse InvalidNonceException d'erreur sera renvoyée. Après l'InProgressaccusé de réception, CodePipeline attend que les résultats soient renvoyés.

  4. Le job worker lance votre action personnalisée sur la révision, puis votre action est exécutée. Avec toutes les autres actions, votre action personnalisée renvoie un résultat au travailleur. Dans l'exemple d'une action de création personnalisée, l'action extrait les artefacts du compartiment Amazon S3, les construit et renvoie les artefacts créés avec succès vers le compartiment Amazon S3.

  5. Pendant l'exécution de l'action, le travailleur peut appeler PutJobSuccessResult avec un jeton de continuation (la sérialisation de l'état de la tâche générée par le travailleur, par exemple un identifiant de build au format JSON ou une clé d'objet Amazon S3), ainsi que les ExternalExecutionId informations qui seront utilisées pour renseigner le lien. executionUrlTemplate Cette opération mettra à jour la vue de la console du pipeline, qui contiendra ainsi un lien valide redirigeant vers les détails de l'action en cours. Bien que cela ne soit pas obligatoire, il s'agit d'une bonne pratique car cela permet aux utilisateurs de voir l'état de votre action personnalisée pendant son exécution.

    Une fois que PutJobSuccessResult est sollicité, la tâche est considérée comme étant terminée. Une nouvelle tâche est créée CodePipeline qui inclut le jeton de continuation. Cette tâche apparaît si votre exécutant de tâches sollicite à nouveau PollForJobs. Cette nouvelle tâche permet notamment de vérifier l'état de l'action. Une fois celle-ci terminée, la tâche affiche un résultat avec ou sans jeton de poursuite.

    Note

    Si votre exécutant de tâches effectue toutes les tâches associées à une action personnalisée, envisagez de diviser le traitement de votre exécutant de tâches en deux étapes minimum. La première étape consiste à établir la page des détails de votre action. Une fois que vous aurez créé la page des détails, vous pourrez sérialiser l'état de l'exécutant de tâches et le renvoyer sous la forme d'un jeton de poursuite en tenant compte des restrictions de taille (voir Quotas dans AWS CodePipeline). Par exemple, vous pouvez écrire l'état de l'action dans la chaîne que vous utilisez comme jeton de poursuite. La seconde étape (et les étapes suivantes) du traitement de votre exécutant de tâches réalise la tâche réelle de l'action. La dernière étape renvoie le succès ou l'échec à CodePipeline, sans jeton de continuation à l'étape finale.

    Pour plus d'informations sur l'utilisation du jeton de continuation, consultez les spécifications de PutJobSuccessResult la référence de l'CodePipeline API.

  6. Une fois l'action personnalisée terminée, le job worker renvoie le résultat de l'action personnalisée CodePipeline en appelant l'une des deux API suivantes :

    • PutJobSuccessResultsans jeton de continuation, ce qui indique que l'action personnalisée a été exécutée avec succès

    • PutJobFailureResult, ce qui indique que l'action personnalisée n'a pas été exécutée correctement

    Selon le résultat, le pipeline passera à l'action suivante (réussite) ou s'interrompra (échec).

Architecture d'exécutant de tâches personnalisé et exemples

Une fois que vous avez cartographié votre workflow général, vous pouvez créer votre exécutant de tâches. Bien que les détails de l'action personnalisée détermineront en dernier lieu ce qui est nécessaire pour votre exécutant de tâches, la plupart des exécutants de tâches des actions personnalisées incluent les fonctionnalités suivantes :

  • Solliciter des offres d'emploi CodePipeline en utilisantPollForJobs.

  • Reconnaître les emplois et donner des résultats à CodePipeline l'utilisation AcknowledgeJobPutJobSuccessResult, etPutJobFailureResult.

  • Extraction d'artefacts et/ou placement d'artefacts dans le compartiment Amazon S3 pour le pipeline. Pour télécharger des artefacts depuis le compartiment Amazon S3, vous devez créer un client Amazon S3 qui utilise la signature Signature Version 4 (Sig V4). Sig V4 est requis pour AWS KMS.

    Pour télécharger des artefacts dans le compartiment Amazon S3, vous devez également configurer la PutObject demande Amazon S3 pour utiliser le chiffrement. Actuellement, seul le service de gestion des AWS clés (AWS KMS) est pris en charge pour le chiffrement. AWS KMS utilise AWS KMS keys. Afin de savoir s'il convient d'utiliser une clé gérée par le client Clé gérée par AWS ou une clé gérée par le client pour télécharger des artefacts, votre assistant personnalisé doit examiner les données du travail et vérifier la propriété de la clé de chiffrement. Si la propriété est définie, vous devez utiliser cet ID de clé géré par le client lors de la configuration AWS KMS. Si la propriété clé est nulle, vous utilisez le Clé gérée par AWS. CodePipeline utilise le, Clé gérée par AWS sauf configuration contraire.

    Pour un exemple qui montre comment créer les AWS KMS paramètres en Java ou .NET, consultez Spécifier les AWS Key Management Service dans Amazon S3 à l'aide AWS des SDK. Pour plus d'informations sur le compartiment Amazon S3 pour CodePipeline, consultezCodePipeline concepts .

Un exemple plus complexe de travailleur personnalisé est disponible sur GitHub. Ce modèle est en open source et est fourni tel quel.

Ajout d'une action personnalisée à un pipeline

Une fois que vous avez un travailleur, vous pouvez ajouter votre action personnalisée à un pipeline en en créant un nouveau et en le choisissant lorsque vous utilisez l'assistant de création de pipeline, en modifiant un pipeline existant et en ajoutant l'action personnalisée AWS CLI, ou en utilisant les SDK ou les API.

Note

Vous pouvez créer un pipeline dans l'assistant Create Pipeline qui inclut une action personnalisée s'il s'agit d'une action de génération ou de déploiement. Si votre action personnalisée est dans la catégorie test, vous devez l'ajouter en modifiant un pipeline existant.

Ajout d'une action personnalisée à un pipeline existant (interface de ligne de commande)

Vous pouvez utiliser le AWS CLI pour ajouter une action personnalisée à un pipeline existant.

  1. Ouvrez une session de terminal (Linux, macOS ou Unix) ou une invite de commande (Windows) et exécutez la get-pipeline commande pour copier la structure de pipeline que vous souhaitez modifier dans un fichier JSON. Par exemple, pour un pipeline nommé MyFirstPipeline, saisissez la commande suivante :

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json

    Cette commande ne renvoie rien, mais le fichier que vous avez créé doit apparaître dans le répertoire où vous avez exécuté la commande.

  2. Ouvrez le fichier JSON dans un éditeur de texte et modifiez la structure du fichier pour ajouter votre action personnalisée à une étape existante.

    Note

    Si vous souhaitez que votre action soit exécutée en parallèle d'une autre action de l'étape, assurez-vous que vous lui attribuez la même valeur runOrder que cette action.

    Par exemple, pour modifier la structure d'un pipeline afin d'ajouter une étape nommée Génération et ajouter ensuite une action personnalisée de génération à cette même étape, vous pouvez modifier le JSON pour ajouter l'étape Génération avant une étape de déploiement, en procédant comme suit :

    , { "name": "MyBuildStage", "actions": [ { "inputArtifacts": [ { "name": "MyApp" } ], "name": "MyBuildCustomAction", "actionTypeId": { "category": "Build", "owner": "Custom", "version": "1", "provider": "My-Build-Provider-Name" }, "outputArtifacts": [ { "name": "MyBuiltApp" } ], "configuration": { "ProjectName": "MyBuildProject" }, "runOrder": 1 } ] }, { "name": "Staging", "actions": [ { "inputArtifacts": [ { "name": "MyBuiltApp" } ], "name": "Deploy-CodeDeploy-Application", "actionTypeId": { "category": "Deploy", "owner": "AWS", "version": "1", "provider": "CodeDeploy" }, "outputArtifacts": [], "configuration": { "ApplicationName": "CodePipelineDemoApplication", "DeploymentGroupName": "CodePipelineDemoFleet" }, "runOrder": 1 } ] } ] }
  3. Pour appliquer les modifications, exécutez la commande update-pipeline en spécifiant le fichier JSON du pipeline d'une manière similaire à l'exemple suivant :

    Important

    N'oubliez pas d'inclure file:// devant le nom du fichier. Il est nécessaire dans cette commande.

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json

    Cette commande affiche toute la structure du pipeline mise à jour.

  4. Ouvrez la CodePipeline console et choisissez le nom du pipeline que vous venez de modifier.

    Le pipeline affiche vos modifications. La prochaine fois que vous apporterez une modification à l'emplacement source, le pipeline exécutera cette modification via sa structure révisée.