Creare e aggiungere un'azione personalizzata in CodePipeline

AWS CodePipeline include una serie di azioni che consentono di configurare, compilare, testare e distribuire risorse per il processo di rilascio automatizzato. Se il processo di rilascio comprende attività che non sono incluse nelle operazioni predefinite, ad esempio un processo di compilazione sviluppato internamente o una suite di test, puoi creare un'operazione personalizzata a tale scopo e includerla nella pipeline. Puoi utilizzare il AWS CLI per creare azioni personalizzate nelle pipeline associate al tuo AWS account.

Puoi creare azioni personalizzate per le seguenti categorie di AWS CodePipeline azioni:

• Un'operazione di compilazione personalizzata che consente di compilare o trasformare gli elementi

• Un'operazione di distribuzione personalizzata che consente di distribuire elementi in uno o più server, siti Web o repository

• Un'operazione di test personalizzata che consente di configurare ed eseguire test automatici

• Un'operazione di richiamo personalizzata che consente di eseguire funzioni

Quando si crea un'azione personalizzata, è necessario creare anche un job worker che elabori le richieste di lavoro CodePipeline per questa azione personalizzata, esegua il lavoro e restituisca il risultato dello stato a CodePipeline. Questo job worker può essere localizzato su qualsiasi computer o risorsa purché abbia accesso all'endpoint pubblico di. CodePipeline Per gestire facilmente l'accesso e la sicurezza, prendi in considerazione la possibilità di ospitare il tuo job worker su un'istanza Amazon EC2.

Il seguente diagramma mostra una visualizzazione generale di una pipeline che include un'operazione di compilazione personalizzata:

Quando una pipeline include un'azione personalizzata come parte di una fase, la pipeline creerà una richiesta di lavoro. Un esecutore del processo personalizzato rileva tale richiesta ed esegue il processo (in questo esempio, un processo personalizzato utilizzando un software di compilazione di terze parti). Al termine dell'operazione, l'esecutore del processo restituisce un esito positivo o negativo. Se viene ricevuto un risultato positivo, la pipeline fornirà la revisione e i relativi artefatti all'azione successiva. Se viene restituito un errore, la pipeline non fornirà la revisione all'azione successiva nella pipeline.

Nota

Queste istruzioni presuppongono che la procedura in Guida introduttiva con CodePipeline sia già stata completata.

Creazione di un'operazione personalizzata

Per creare un'azione personalizzata con AWS CLI

1. Apri un editor di testo e crea un file JSON per l'operazione personalizzata che include la categoria dell'operazione, il provider di operazioni e le eventuali impostazioni richieste dall'operazione personalizzata. Ad esempio, per creare un'operazione di compilazione personalizzata che richiede una sola proprietà, l'aspetto del file JSON potrebbe essere simile al seguente:

   {
       "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"
       }]
   }

   In questo esempio all’operazione personalizzata viene aggiunto del tagging includendo la chiave di tag Project e il valore ProjectA all’operazione personalizzata. Per ulteriori informazioni sull'aggiunta di tag alle risorse CodePipeline, consultaAssegnazione di tag alle risorse.

   Nel file JSON sono incluse due proprietà, entityUrlTemplate e executionUrlTemplate. Puoi fare riferimento a un nome nelle proprietà di configurazione dell'operazione personalizzata all'interno dei modelli URL seguendo il formato di {Config:name}, purché la proprietà di configurazione sia richiesta e non segreta. Ad esempio, nell'esempio precedente, il entityUrlTemplate valore si riferisce alla proprietà ProjectNamedi configurazione.

   • entityUrlTemplate: il collegamento statico che fornisce informazioni sul provider di servizi per l'operazione. Nell'esempio, il sistema di compilazione include un collegamento statico a ciascun progetto di compilazione. Il formato del collegamento varia a seconda del provider di compilazione (o, se stai creando un tipo di operazione diversa, ad esempio di test, altro provider di servizi). Quando viene aggiunta un'operazione personalizzata, questo formato di collegamento è necessario per consentire all'utente di scegliere tale collegamento per aprire un browser a una pagina del sito Web che fornisce le specifiche per il progetto di compilazione (o ambiente di test).

   • executionUrlTemplate: il collegamento dinamico che verrà aggiornato con le informazioni relative all'esecuzione corrente o più recente dell'operazione. Quando l'esecutore del processo personalizzato aggiorna lo stato di un processo (ad esempio, riuscito, non riuscito o in corso), fornirà anche un externalExecutionId che verrà utilizzato per completare il collegamento. Questo collegamento può essere utilizzato per fornire i dettagli relativi all'esecuzione di un'operazione.

   Ad esempio, quando visualizzi l'operazione nella pipeline, vengono mostrati i seguenti due collegamenti:

   

   Questo collegamento statico viene visualizzato dopo l'aggiunta di un'operazione personalizzata e punta all'indirizzo in entityUrlTemplate, che viene specificato quando si crea l'operazione personalizzata.

   Questo collegamento dinamico viene aggiornato dopo ogni esecuzione dell'operazione e punta all'indirizzo in executionUrlTemplate, che viene specificato quando si crea l'operazione personalizzata.

   Per ulteriori informazioni su questi tipi di link, nonché su RevisionURLTemplate eThirdPartyURL, consulta ActionTypeSettingse CreateCustomActionTypenell'CodePipeline API Reference. Per ulteriori informazioni sui requisiti della struttura dell'operazione e su come creare un'operazione, consulta CodePipeline riferimento alla struttura della tubazione.

2. Salva il file JSON e assegnagli un nome facile da ricordare (ad esempio, MyCustomAction.json).

3. Apri una sessione del terminale (Linux, OS X, Unix) o un prompt dei comandi (Windows) su un computer in cui hai installato AWS CLI.

4. Usa il AWS CLI per eseguire il aws codepipeline create-custom-action-type comando, specificando il nome del file JSON che hai appena creato.

   Ad esempio, per creare un'azione personalizzata di creazione:

   Importante

   Assicurarsi di includere file:// prima del nome del file. Questo è obbligatorio in questo comando.

   aws codepipeline create-custom-action-type --cli-input-json file://MyCustomAction.json

5. Questo comando restituisce l'intera struttura dell'operazione personalizzata creata, nonché la proprietà di configurazione dell'operazione JobList che viene aggiunta per l'utente. Quando aggiungi l'operazione personalizzata a una pipeline, puoi utilizzare JobList per specificare per quali progetti del provider è possibile eseguire il polling per processi. In mancanza di configurazione, tutti i processi disponibili verranno restituiti quando l'esecutore del processo personalizzato esegue il polling dei processi.

   Ad esempio, il comando precedente potrebbe restituire una struttura simile alla seguente:

   {
       "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}/"
           }
       }
   }

   Nota

   Come parte dell'output del create-custom-action-type comando, la id sezione include"owner": "Custom". CodePipeline assegna automaticamente Custom come proprietario i tipi di azione personalizzati. Questo valore non può essere assegnato o modificato quando utilizzi il comando create-custom-action-type o update-pipeline.

Creazione di un esecutore del processo per l'operazione personalizzata

Le azioni personalizzate richiedono un job worker che analizzi le richieste di lavoro CodePipeline relative all'azione personalizzata, esegua il lavoro e restituisca il risultato dello stato a. CodePipeline Il job worker può trovarsi su qualsiasi computer o risorsa purché abbia accesso all'endpoint pubblico per. CodePipeline

Esistono molti modi per designare l'esecutore del processo. Le sezioni seguenti forniscono alcune indicazioni pratiche per lo sviluppo del job worker personalizzato per CodePipeline.

Argomenti

• Scelta e configurazione di una strategia di gestione delle autorizzazioni per l'esecutore del processo
• Sviluppo di un esecutore del processo per l'operazione personalizzata
• Architettura dell'esecutore del processo personalizzato ed esempi

Scelta e configurazione di una strategia di gestione delle autorizzazioni per l'esecutore del processo

Per sviluppare un job worker personalizzato per le tue azioni personalizzate CodePipeline, avrai bisogno di una strategia per l'integrazione della gestione degli utenti e delle autorizzazioni.

La strategia più semplice consiste nell'aggiungere l'infrastruttura necessaria per il job worker personalizzato creando istanze Amazon EC2 con un ruolo di istanza IAM, che consentono di scalare facilmente le risorse necessarie per l'integrazione. Puoi utilizzare l'integrazione integrata con AWS per semplificare l'interazione tra il tuo job worker personalizzato e. CodePipeline

Per configurare istanze Amazon EC2

1. Scopri di più su Amazon EC2 e determina se è la scelta giusta per la tua integrazione. Per informazioni, consulta Amazon EC2 - Virtual Server Hosting.

2. Inizia a creare le tue istanze Amazon EC2. Per informazioni, consulta Getting Started with Amazon EC2 Linux Instances.

Un'altra strategia da considerare consiste nell'utilizzare la federazione delle identità con IAM per integrare il sistema e le risorse esistenti del provider di identità. Questa strategia è particolarmente utile se disponi già di un provider delle identità aziendali o se le risorse sono già configurate per supportare gli utenti che utilizzano provider delle identità Web. La federazione delle identità consente di concedere un accesso sicuro alle AWS risorse CodePipeline, anche senza dover creare o gestire utenti IAM. Puoi utilizzare le caratteristiche e le policy per requisiti di sicurezza delle password e rotazione delle credenziali. Puoi utilizzare applicazioni di esempio come modelli per il tuo progetto.

Per configurare la federazione delle identità

1. Scopri di più sulla federazione delle identità IAM. Per informazioni, consulta Gestione della federazione.

2. Rivedi gli esempi negli Scenari per la concessione dell'accesso temporaneo per identificare lo scenario per l'accesso temporaneo più adatto alle esigenze dell'operazione personalizzata.

3. Rivedere gli esempi di codice della federazione delle identità rilevanti per l'infrastruttura, ad esempio:

   • Applicazione di esempio della federazione delle identità per un caso d'uso di Active Directory

4. Iniziare a configurare la federazione delle identità. Per informazioni, consulta la Guida per l'utente di Identity Providers and Federation in IAM.

Crea uno dei seguenti comandi da utilizzare in Job Worker per eseguire azioni personalizzate e job worker. Account AWS

Gli utenti necessitano dell'accesso programmatico se desiderano interagire con utenti AWS esterni a. AWS Management Console Il modo per concedere l'accesso programmatico dipende dal tipo di utente che accede. AWS

Per fornire agli utenti l'accesso programmatico, scegli una delle seguenti opzioni.

Quale utente necessita dell'accesso programmatico?	Per	Come
Identità della forza lavoro (Utenti gestiti nel centro identità IAM)	Utilizza credenziali temporanee per firmare le richieste programmatiche agli AWS CLI AWS SDK o alle API. AWS	Segui le istruzioni per l'interfaccia che desideri utilizzare. Per la AWS CLI, consulta Configurazione dell'uso AWS IAM Identity Center nella Guida AWS CLI per l'utente.AWS Command Line Interface Per AWS SDK, strumenti e AWS API, consulta l'autenticazione IAM Identity Center nella Guida di riferimento agli AWS SDK e agli strumenti.
IAM	Utilizza credenziali temporanee per firmare le richieste programmatiche agli SDK o alle API AWS CLI. AWS AWS	Segui le istruzioni in Uso delle credenziali temporanee con AWS risorse nella Guida per l'utente IAM.
IAM	(Non consigliato) Utilizza credenziali a lungo termine per firmare le richieste programmatiche agli AWS CLI AWS SDK o alle API. AWS	Segui le istruzioni per l'interfaccia che desideri utilizzare. Per la AWS CLI, consulta Autenticazione tramite credenziali utente IAM nella Guida per l'utente.AWS Command Line Interface Per gli AWS SDK e gli strumenti, consulta Autenticazione tramite credenziali a lungo termine nella Guida di riferimento agli SDK e agli AWS strumenti. Per le AWS API, consulta Gestione delle chiavi di accesso per gli utenti IAM nella Guida per l'utente IAM.

Di seguito è riportato una policy di esempio che puoi creare per l'utilizzo con l'esecutore del processo personalizzato. Questa policy è intesa solo come un esempio ed è fornita senza modifiche.

{
  "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/"  
      ]              
    }
  ]
}  

Nota

Prendi in considerazione l'utilizzo della policy gestita. AWSCodePipelineCustomActionAccess

Sviluppo di un esecutore del processo per l'operazione personalizzata

Dopo aver scelto la strategia di gestione delle autorizzazioni, dovresti considerare in che modo interagirà il tuo collaboratore. CodePipeline Il seguente diagramma di alto livello mostra il flusso di lavoro di un'azione personalizzata e di un job worker per un processo di compilazione.

1. Il tuo job worker effettua sondaggi CodePipeline per i lavori che utilizzanoPollForJobs.

2. Quando una pipeline viene attivata da una modifica nella sua fase di origine (ad esempio, quando uno sviluppatore esegue il commit di una modifica), viene avviato il processo di rilascio automatico. Il processo continua fino alla fase in cui l'azione personalizzata è stata configurata. Quando raggiunge l'obiettivo dell'utente in questa fase, mette in CodePipeline coda un lavoro. Questo processo verrà visualizzato se l'esecutore del processo chiama nuovamente PollForJobs per ottenere lo stato. Acquisisce i dettagli del processo da PollForJobs e li restituisce all'esecutore del processo.

3. L'impiegato chiama AcknowledgeJob per inviare CodePipeline un riconoscimento di lavoro. CodePipeline restituisce un riconoscimento che indica che il lavoratore deve continuare il lavoro (InProgress) oppure, se più di un lavoratore sta effettuando sondaggi per le offerte di lavoro e un altro lavoratore ha già richiesto il lavoro, verrà restituita una risposta di InvalidNonceException errore. Dopo il InProgress riconoscimento, CodePipeline attende la restituzione dei risultati.

4. Il job worker avvia l'azione personalizzata sulla revisione, quindi l'azione viene eseguita. Oltre a qualsiasi altra azione, l'azione personalizzata restituisce un risultato al job worker. Nell'esempio di un'azione di creazione personalizzata, l'azione estrae gli artefatti dal bucket Amazon S3, li crea e riporta gli artefatti creati correttamente nel bucket Amazon S3.

5. Durante l'esecuzione dell'azione, il job worker può effettuare la chiamata PutJobSuccessResult con un token di continuazione (la serializzazione dello stato del job generato dal job worker, ad esempio un identificatore di build in formato JSON o una chiave oggetto Amazon S3), oltre alle ExternalExecutionId informazioni che verranno utilizzate per compilare il link. executionUrlTemplate Ciò aggiornerà la visualizzazione della pipeline sulla console con un collegamento funzionante ai dettagli specifici dell'azione mentre è in corso. Anche se non richiesto, si tratta di una best practice perché consente agli utenti di visualizzare lo stato dell'operazione personalizzata mentre è in esecuzione.

   Una volta chiamato PutJobSuccessResult, il processo è considerato completato. Viene creato un nuovo lavoro CodePipeline che include il token di continuazione. Questo processo verrà visualizzato se l'esecutore del processo chiama nuovamente PollForJobs. Questo nuovo processo può essere utilizzato per controllare lo stato dell'operazione. Al termine dell'operazione, viene restituito un token di continuazione oppure non viene restituito un token di continuazione.

   Nota

   Se l'esecutore del processo esegue tutto il lavoro per un'operazione personalizzata, valuta se suddividere l'elaborazione dell'esecutore del processo in almeno due fasi. La prima fase stabilisce la pagina dei dettagli dell'operazione. Una volta creata la pagina dei dettagli, puoi serializzare lo stato dell'esecutore del processo e restituirlo come un token di continuazione, soggetto a limiti delle dimensioni (consulta Quote in AWS CodePipeline). Ad esempio, puoi scrivere lo stato dell'operazione nella stringa utilizzata come il token di continuazione. La seconda fase (e le fasi successive) dell'elaborazione dell'esecutore del processo eseguono il lavoro effettivo dell'operazione. Il passaggio finale restituisce l'esito positivo o negativo CodePipeline, senza alcun token di continuazione nel passaggio finale.

   Per ulteriori informazioni sull'utilizzo del token di continuazione, consulta le specifiche riportate PutJobSuccessResult nell'CodePipeline API Reference.

6. Una volta completata l'azione personalizzata, il job worker restituisce il risultato dell'azione personalizzata CodePipeline chiamando una delle due API:

   • PutJobSuccessResultsenza un token di continuazione, che indica che l'azione personalizzata è stata eseguita correttamente

   • PutJobFailureResult, che indica che l'azione personalizzata non è stata eseguita correttamente

   A seconda del risultato, la pipeline continua nell'operazione successiva (esito positivo) o si interrompe (esito negativo).

Architettura dell'esecutore del processo personalizzato ed esempi

Dopo aver mappato il flusso di lavoro di alto livello, puoi creare l'esecutore del processo. Anche se le specifiche dell'operazione personalizzata determinano alla fine ciò che è richiesto per l'esecutore del processo, la maggior parte degli esecutori del processo includono le seguenti funzionalità:

• Ricerca di offerte di lavoro relative all' CodePipeline utilizzoPollForJobs.

• Riconoscimento delle offerte di lavoro e restituzione dei risultati all' CodePipeline utilizzo di AcknowledgeJobPutJobSuccessResult, e. PutJobFailureResult

• Recupero e/o inserimento di artefatti nel bucket Amazon S3 per la pipeline. Per scaricare elementi dal bucket Amazon S3, devi creare un client Amazon S3 che utilizzi la firma Signature Version 4 (Sig V4). Sig V4 è richiesto per. AWS KMS

  Per caricare artefatti nel bucket Amazon S3, devi inoltre configurare la richiesta Amazon S3 per utilizzare la crittografia. PutObject Attualmente solo AWS Key Management Service (AWS KMS) è supportato per la crittografia. AWS KMS usi AWS KMS keys. Per sapere se utilizzare una chiave gestita dal cliente Chiave gestita da AWS o una chiave gestita dal cliente per caricare gli artefatti, il job worker personalizzato deve esaminare i dati del lavoro e verificare la proprietà della chiave di crittografia. Se la proprietà è impostata, è necessario utilizzare l'ID della chiave gestita dal cliente durante la configurazione. AWS KMS Se la proprietà della chiave è nulla, si utilizza la. Chiave gestita da AWS CodePipeline utilizza il, Chiave gestita da AWS a meno che non sia configurato diversamente.

  Per un esempio che mostra come creare i AWS KMS parametri in Java o.NET, consulta Specificare AWS Key Management Service in Amazon S3 l'uso AWS degli SDK. Per ulteriori informazioni sul bucket Amazon S3 per CodePipeline, consulta. CodePipeline concetti

Un esempio più complesso di job worker personalizzato è disponibile su. GitHub Questo esempio è open source e viene fornito senza alcuna modifica.

• Job Worker di esempio per CodePipeline: scarica l'esempio dal GitHub repository.

Aggiunta di un'operazione personalizzata a una pipeline

Dopo aver creato un job worker, puoi aggiungere un'azione personalizzata a una pipeline creandone una nuova e selezionandola quando usi la procedura guidata Crea pipeline, modificando una pipeline esistente e aggiungendo l'azione personalizzata oppure utilizzando gli SDK o le AWS CLI API.

Nota

Nella procedura guidata Create Pipeline (Crea pipeline), puoi creare una pipeline che include un'operazione personalizzata se si tratta di un'operazione di compilazione o di distribuzione . Se l'operazione personalizzata appartiene alla categoria di test, occorre aggiungerla modificando una pipeline esistente.

Argomenti

• Aggiunta di un'operazione personalizzata a una pipeline esistente (CLI)

Aggiunta di un'operazione personalizzata a una pipeline esistente (CLI)

Puoi utilizzare il AWS CLI per aggiungere un'azione personalizzata a una pipeline esistente.

1. Apri una sessione terminale (Linux, macOS o Unix) o un prompt dei comandi (Windows) ed esegui il get-pipeline comando per copiare la struttura della pipeline che desideri modificare in un file JSON. Ad esempio, per una pipeline denominata MyFirstPipeline, digitare il comando seguente:

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

   Questo comando non restituisce alcun valore, ma nella directory in cui è stato eseguito dovrebbe comparire il file creato.

2. Aprire il file JSON in qualsiasi editor di testo e modificare la struttura del file per aggiungere l'operazione personalizzata a una fase esistente.

   Nota

   Se si desidera eseguire l'operazione in parallelo con un'altra operazione in tale fase, assicurarsi di assegnargli lo stesso valore runOrder di tale operazione.

   Ad esempio, per modificare la struttura di una pipeline per aggiungere una fase denominata Compila e per aggiungere un'operazione di compilazione personalizzata a tale fase, modificare il file JSON per aggiungere una fase Compila prima di una fase di distribuzione come segue:

   ,
       {
         "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. Per applicare le modifiche, eseguire il comando update-pipeline, specificando il file JSON della pipeline, in modo analogo al seguente:

   Importante

   Assicurarsi di includere file:// prima del nome del file. Questo è obbligatorio in questo comando.

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

   Questo comando restituisce l'intera struttura della pipeline modificata.

4. Apri la CodePipeline console e scegli il nome della pipeline che hai appena modificato.

   La pipeline mostra le modifiche. La prossima volta che si modifica la sorgente originale, la pipeline eseguirà tale versione attraverso la struttura modificata delle pipeline stessa.