Criar e adicionar uma ação personalizada no CodePipeline - AWS CodePipeline
Criar uma ação personalizadaCriar um operador de trabalho para a ação personalizadaAdicionar uma ação personalizada a um pipeline

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Criar e adicionar uma ação personalizada no CodePipeline

O AWS CodePipeline inclui uma variedade de ações que ajudam você a configurar a compilação, o teste e os recursos de implantação para seu processo automatizado de liberação. Se o processo de liberação tiver atividades que não estão incluídas nas ações padrão, como um processo de compilação desenvolvido internamente ou um conjunto de testes, você pode criar uma ação personalizada para essa finalidade e incluí-la no pipeline. Você pode usar a AWS CLI para criar ações personalizadas em pipelines associados à sua conta da AWS.

Você pode criar ações personalizadas para as seguintes categorias de ação do AWS CodePipeline:

  • Uma ação de compilação personalizada que cria ou transforma itens

  • Uma ação de implantação personalizada que implanta itens em um ou mais servidores, sites ou repositórios

  • Uma ação de teste personalizada que configura e executa testes automatizados

  • Uma ação de invocação personalizada que executa funções

Ao criar uma ação personalizada, você também deve criar um operador de trabalho que pesquise o CodePipeline em busca de solicitações de trabalho para essa ação personalizada, execute o trabalho e retorne o resultado do status ao CodePipeline. Esse operador de trabalho pode estar localizado em qualquer computador ou recurso, desde que tenha acesso ao endpoint público do CodePipeline. Para gerenciar facilmente o acesso e a segurança, é recomendável hospedar o operador de trabalho em uma instância do Amazon EC2.

O diagrama a seguir mostra uma exibição de alto nível de um pipeline que inclui uma ação personalizada de compilação:

Uma exibição de alto nível de um pipeline que inclui uma ação personalizada de compilação.

Quando um pipeline inclui uma ação personalizada como parte de um estágio, ele criará uma solicitação de trabalho. Um operador de trabalho personalizado detecta essa solicitação e executa o trabalho (neste exemplo, em um processo personalizado usando o software de compilação de terceiros). Quando a ação for concluída, o operador de trabalho retornará um resultado de êxito ou de falha. Se um resultado de êxito for recebido, o pipeline fornecerá a revisão e seus artefatos na próxima ação. Se uma falha for retornada, o pipeline não fornecerá a revisão na próxima ação no pipeline.

nota

Estas instruções supõem que você já tenha concluído as etapas em Conceitos básicos do CodePipeline.

Criar uma ação personalizada

Como criar uma ação personalizada com o AWS CLI

  1. Abra um editor de texto e crie um arquivo JSON para sua ação personalizada que inclua a categoria da ação, o provedor da ação e as configurações necessárias para sua ação personalizada. Por exemplo, para criar uma ação de construção personalizada que requeira apenas uma propriedade, seu arquivo JSON pode ter a seguinte aparência:

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

    Este exemplo adiciona tags à ação personalizada por meio da inclusão da chave de tag Project e o valor ProjectA na ação personalizada. Para obter mais informações sobre a marcação de recursos no CodePipeline, consulte Marcar recursos.

    Há duas propriedades incluídas no arquivo JSON, entityUrlTemplate e executionUrlTemplate. Você pode consultar um nome nas propriedades de configuração da ação personalizada dentro dos modelos de URL, seguindo o formato {Config:name}, desde que a propriedade de configuração seja necessária e não secreta. Por exemplo, no exemplo acima, o valor entityUrlTemplate refere-se à propriedade de configuração ProjectName.

    • entityUrlTemplate: o link estático que fornece informações sobre o provedor de serviços para a ação. No exemplo, o sistema de construção inclui um link estático para cada projeto de construção. O formato do link poderá variar, dependendo do seu provedor de construção (ou, se estiver criando um outro tipo de ação, como teste, outro provedor de serviços). Você deve fornecer este formato de link de forma que quando a ação personalizada for adicionada, o usuário possa escolher este link para abrir um navegador em uma página de seu site que forneça informações específicas para o projeto de criação (ou ambiente de teste).

    • executionUrlTemplate: o link dinâmico que será atualizado com informações sobre a execução atual ou mais recente da ação. Quando seu operador de trabalho personalizado atualiza o status de uma tarefa (por exemplo, sucesso, falha ou em andamento), ele também fornece uma externalExecutionId que será usada para completar o link. Este link pode ser usado para fornecer detalhes sobre a execução de uma ação.

    Por exemplo, quando você visualizar a ação no pipeline, você verá os dois links a seguir:

    Os links no console do CodePipeline levam a mais informações sobre a execução de um pipeline.

    Este link estático é exibido depois que você adicionar sua ação personalizada e aponta para o endereço no entityUrlTemplate, que você especifica ao criar sua ação personalizada.

    Este link dinâmico é atualizado após cada execução da ação e aponta para o endereço no executionUrlTemplate, que você especifica ao criar sua ação personalizada.

    Para obter mais informações sobre esses tipos de link, bem como RevisionURLTemplate e ThirdPartyURL, consulte ActionTypeSettings e CreateCustomActionType na Referência da API do CodePipeline. Para mais informações sobre os requisitos de estrutura de ação e como criar uma ação, consulte Referência da estrutura do pipeline do CodePipeline.

  2. Salve o arquivo JSON e atribua a ele um nome fácil de lembrar (por exemplo, MyCustomAction.json).

  3. Abra uma sessão de terminal (Linux, OS X, Unix) ou prompt de comando (Windows) em um computador onde você tenha instalado o AWS CLI.

  4. Use o AWS CLI para executar o comando aws codepipeline create-custom-action-type, especificando o nome do arquivo JSON que acabou de criar.

    Por exemplo, para criar uma ação personalizada de compilação:

    Importante

    Não se esqueça de incluir file:// antes do nome de arquivo. Ele é obrigatório nesse comando.

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

  5. Este comando retorna a estrutura inteira da ação personalizada que você criou, bem como a propriedade de configuração da ação JobList, que é adicionada para você. Quando você adiciona a ação personalizada a um pipeline, você pode usar JobList para especificar quais projetos do provedor você pode consultar para tarefas. Se você não configurar isso, todos as tarefas disponíveis serão retornadas quando o operador do trabalho personalizado efetuar uma consulta por tarefas.

    Por exemplo, o comando anterior pode retornar uma estrutura similar ao seguinte:

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

    Como parte da saída do comando create-custom-action-type, a seção id inclui "owner": "Custom". O CodePipeline atribui automaticamente Custom como proprietário dos tipos de ação personalizada. Esse valor não pode ser atribuído ou alterado quando você usar o comando create-custom-action-type ou o comando update-pipeline.

Criar um operador de trabalho para a ação personalizada

As ações personalizadas requerem um operador de trabalho que pesquisará o CodePipeline em busca de solicitações de trabalho para a ação personalizada, executará o trabalho e retornará o resultado do status ao CodePipeline. O operador de trabalho pode estar localizado em qualquer computador ou recurso desde que tenha acesso ao endpoint público do CodePipeline.

Há várias maneiras de criar o operador de trabalho. As seções a seguir fornecem algumas orientações práticas para o desenvolvimento do seu operador de trabalho personalizado para o CodePipeline.

Escolher e configurar uma estratégia de gerenciamento de permissões para o operador de trabalho

Para desenvolver um operador de trabalho personalizado para a ação personalizada no CodePipeline, será necessária uma estratégia para a integração de usuários e o gerenciamento de permissões.

A estratégia mais simples é adicionar a infraestrutura necessária para seu operador de trabalho personalizado criando instâncias do Amazon EC2 com um perfil de instância do IAM, que permite aumentar verticalmente a escala dos recursos necessários à integração com facilidade. Você pode usar a integração incorporada à AWS para simplificar a interação entre o operador de trabalho personalizado e o CodePipeline.

Para configurar as instâncias do Amazon EC2

  1. Saiba mais sobre o Amazon EC2 e determine se esta é a escolha certa para sua integração. Para obter mais informações, consulte Amazon EC2 - Hospedagem de servidor virtual.

  2. Comece a criar suas instâncias do Amazon EC2. Para obter informações, consulte Conceitos básicos das instâncias do Amazon EC2 Linux.

Outra estratégia a ser considerada é usar a federação de identidades com o IAM para integrar seu sistema e recursos existentes do provedor de identidades. Essa estratégia é especialmente útil se você já tiver um provedor de identidades corporativas ou já estiver configurado para oferecer suporte aos usuários usando provedores de identidades da web. A federação de identidades permite que você conceda acesso seguro aos recursos da AWS, incluindo o CodePipeline, sem precisar criar ou gerenciar usuários do IAM. É possível usar recursos e políticas para requisitos de segurança de senhas e rotação de credenciais. Você pode usar aplicações de exemplo como modelos para seu próprio design.

Para configurar a federação de identidades

  1. Saiba mais sobre a federação de identidades do IAM. Para mais informações, consulte Gerenciar federação.

  2. Analise os exemplos em Situações de concessão de acesso temporário para identificar o cenário para acesso temporário que melhor atenda às necessidades de sua ação personalizada.

  3. Revise os exemplos de código de federação de identidades relevantes para sua infraestrutura, como:

  4. Comece a configuração da federação de identidades. Para obter informações, consulte Provedores e federação de identidades no Guia do usuário do IAM.

Crie um dos itens a seguir para usar na Conta da AWS ao executar a ação personalizada e o operador de trabalho.

Os usuários precisam de acesso programático se quiserem interagir com a AWS de fora do AWS Management Console. A forma de conceder acesso programático depende do tipo de usuário que está acessando a AWS.

Para conceder acesso programático aos usuários, escolha uma das seguintes opções:

Qual usuário precisa de acesso programático? Para Por

Identificação da força de trabalho

(Usuários gerenciados no Centro de Identidade do IAM)

 Use credenciais temporárias para assinar solicitações programáticas para a AWS CLI, os SDKs da AWS ou as APIs da AWS.

Siga as instruções da interface que deseja utilizar.
IAM Use credenciais temporárias para assinar solicitações programáticas para a AWS CLI, os SDKs da AWS ou as APIs da AWS. Siga as instruções em Como usar credenciais temporárias com recursos da AWS no Guia do usuário do IAM.
IAM

(Não recomendado)

Use credenciais de longo prazo para assinar solicitações programáticas para a AWS CLI, os SDKs da AWS ou as APIs da AWS.

Siga as instruções da interface que deseja utilizar.

Veja a seguir uma política de exemplo que você pode criar para usar com o operador de trabalho personalizado. Essa política serve somente como exemplo e é fornecida no estado em que encontra.

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

É recomendável usar a política gerenciada AWSCodePipelineCustomActionAccess.

Desenvolver um operador de trabalho para a ação personalizada

Após escolher sua estratégia de gerenciamento de permissões, você deve considerar como será a interação do operador de trabalho com o CodePipeline. O diagrama de alto nível a seguir mostra o fluxo de trabalho de uma ação personalizada e do operador de trabalho em um processo de compilação.

O fluxo de trabalho de uma ação personalizada e do operador de trabalho em um processo de compilação.

  1. O operador de trabalho pesquisa o CodePipeline em busca de trabalhos usando PollForJobs.

  2. Quando um pipeline é acionado por uma alteração em seu estágio de origem (por exemplo, quando um desenvolvedor confirma uma alteração), o processo automatizado de liberação é iniciado. O processo continuará até que o estágio em sua ação personalizada seja configurado. Quando a ação nessa etapa for alcançada, o CodePipeline colocará um trabalho na fila. Esse trabalho aparecerá se o operador de trabalho chamar PollForJobs novamente para obter o status. Pegue os detalhes do trabalho e de PollForJobs e passe-os de volta ao operador de trabalho.

  3. O operador de trabalho chama AcknowledgeJob para enviar ao CodePipeline uma confirmação de trabalho. O CodePipeline retorna uma confirmação que indica que o operador de trabalho continuará o trabalho (InProgress) ou, se houver mais de um operador de trabalho procurando trabalhos e outro operador já tiver reivindicado o trabalho, uma resposta de erro InvalidNonceException será retornada. Após a confirmação de InProgress, o CodePipeline aguardará o retorno dos resultados.

  4. O operador de trabalho inicia sua ação personalizada na revisão e, em seguida, a ação é executada. Juntamente com outras ações, sua ação personalizada retornará um resultado ao operador de trabalho. No exemplo de uma ação de compilação personalizada, a ação efetua o pull de artefatos do bucket do Amazon S3, compila-os e envia por push os artefatos compilados de volta ao bucket do Amazon S3.

  5. Quando a ação está em execução, o operador de trabalho pode chamar PutJobSuccessResult com um token de continuação (a serialização do estado do trabalho gerado pelo operador de trabalho, por exemplo, um identificador de compilação em formato JSON ou uma chave de objeto do Amazon S3), bem como as informações ExternalExecutionId que serão usadas para preencher o link em executionUrlTemplate. Isso atualizará a exibição do console do pipeline com um link funcional para os detalhes específicos da ação enquanto ela estiver em andamento. Embora não seja necessário, é uma melhor prática, porque permite que os usuários visualizem o status da ação personalizada durante sua execução.

    Assim que PutJobSuccessResult for chamada , o trabalho é considerado como concluído. Um novo trabalho é criado no CodePipeline que inclui o token de continuação. Esse trabalho aparecerá se o operador de trabalho chamar PollForJobs novamente. Esse novo trabalho pode ser usado para verificar o estado da ação e retornará com um token de continuação ou retornará sem um token de continuação assim que a ação estiver concluída.

    nota

    Se o operador de trabalho executa todo o trabalho para uma ação personalizada, você deve considerar quebrar o processamento do operador de trabalho em pelo menos em duas etapas. A primeira etapa estabelece a página de detalhes para a ação. Assim que tiver criado a página de detalhes, você pode serializar o estado do operador de trabalho e retorná-lo como um token de continuação, sujeito a limites de tamanho (consulte Cotas no AWS CodePipeline). Por exemplo, você pode gravar o estado da ação na string que usar como o token de continuação. A segunda etapa (e as etapas subsequentes) do processamento do operador de trabalho desempenha o trabalho real da ação. A etapa final retorna o resultado de êxito ou falha ao CodePipeline, sem nenhum token de continuação na etapa final.

    Para obter mais informações sobre como usar o token de continuação, consulte as especificações de PutJobSuccessResult na Referência da API do CodePipeline.

  6. Após a conclusão da ação personalizada, o operador de trabalho retornará o resultado da ação personalizada ao CodePipeline chamando uma de duas APIs:

    • PutJobSuccessResult sem um token de continuação, indicando que a ação personalizada foi executada com êxito

    • PutJobFailureResult, indicando que a ação personalizada não foi executada com êxito

    Dependendo do resultado, o pipeline prosseguirá para a ação seguinte (êxito) ou parará (falha).

Arquitetura e exemplos de operadores de trabalho personalizados

Depois que tiver mapeado seu fluxo de trabalho de alto nível, você pode criar o operador de trabalho. Embora as especificidades de sua ação personalizada basicamente determinem o que é necessário para seu operador de trabalho, a maioria dos operadores de trabalho para ações personalizadas incluem a seguinte funcionalidade:

  • Pesquisa de trabalhos no CodePipeline usando PollForJobs.

  • Confirmação de trabalhos e retorno de resultados ao CodePipeline por meio de AcknowledgeJob, PutJobSuccessResult e PutJobFailureResult.

  • Recuperação de artefatos e/ou colocação de artefatos em um bucket do Amazon S3 para o pipeline. Para fazer download dos artefatos do bucket do Amazon S3, é necessário criar um cliente do Amazon S3 que use a assinatura do Signature versão 4 (Sig V4). O Sig V4 é necessário para o AWS KMS.

    Para fazer upload dos artefatos no bucket do Amazon S3, você deve configurar a solicitação do Amazon S3 PutObject para usar criptografia. Atualmente, somente o AWS Key Management Service (AWS KMS) é compatível com criptografia. O AWS KMS usa as AWS KMS keys. Para saber se deve ser usada uma Chave gerenciada pela AWS ou uma chave gerenciada pelo cliente para fazer upload dos artefatos, seu operador de trabalho personalizado deve analisar os dados do trabalho e verificar a propriedade da chave de criptografia. Se a propriedade estiver definida, você deverá usar esse ID de chave gerenciada pelo cliente ao configurar o AWS KMS. Se a propriedade da chave for nula, você usará a Chave gerenciada pela AWS. O CodePipeline usa a Chave gerenciada pela AWS, a menos que seja configurado de outra forma.

    Para ver um exemplo que mostra como criar os parâmetros do AWS KMS em Java ou .NET, consulte Como especificar o AWS Key Management Service no Amazon S3 usando os SDKs da AWS. Para obter mais informações sobre o bucket do Amazon S3 para CodePipeline, consulte CodePipeline conceitos .

Um exemplo mais complexo de operador de trabalho personalizado está disponível no GitHub. Esse exemplo é de código aberto e fornecido no estado que se encontra.

Adicionar uma ação personalizada a um pipeline

Quando você tiver um operador de trabalho, poderá adicionar a ação personalizada a um pipeline criando uma nova e escolhendo-a quando usar o assistente de criação de pipeline, editando um pipeline existente e adicionando a ação personalizada ou utilizando a AWS CLI, os SDKs ou as APIs.

nota

Você pode criar um pipeline no assistente de criação de pipeline que inclua uma ação personalizada se for uma ação de criação ou implantação. Se a ação personalizada estiver na categoria de teste , você deve adicioná-la ao editar um pipeline existente.

Adicionar uma ação personalizada a um pipeline existente (CLI)

Você pode usar a AWS CLI para adicionar uma ação personalizada a um pipeline existente.

  1. Abra uma sessão de terminal (Linux, macOS ou Unix) ou prompt de comando (Windows) e execute o comando get-pipeline para copiar a estrutura do pipeline a ser editada para um arquivo JSON. Por exemplo, para um pipeline chamado MyFirstPipeline, você deve digitar o seguinte comando: 

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

    Este comando retorna nada, mas o arquivo que você criou deve aparecer no diretório onde você executou o comando.

  2. Abra o arquivo JSON em qualquer editor de texto e modifique a estrutura do arquivo para adicionar sua ação personalizada a um estágio existente.

    nota

    Se você deseja que a sua ação seja executada em paralelo com outra ação naquele estágio, certifique-se de atribuir-lhe o mesmo valor runOrder da ação.

    Por exemplo, para modificar a estrutura de um pipeline para adicionar um estágio chamado construção e adicionar uma ação de construção personalizada para esse estágio, você deve modificar o JSON para adicionar o estágio Construção antes de um estágio de implantação, conforme a seguir:

    ,
    {
      "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. Para aplicar suas alterações, execute o comando update-pipeline, especificando o pipeline do arquivo JSON, de modo semelhante ao seguinte:

    Importante

    Não se esqueça de incluir file:// antes do nome de arquivo. Ele é obrigatório nesse comando.

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

    Este comando retorna toda a estrutura do pipeline editado.

  4. Abra o console do CodePipeline e escolha o nome do pipeline que você acabou de editar.

    O pipeline exibirá suas alterações. Na próxima vez que você alterar a localização de origem, o pipeline executará a revisão através da estrutura revisada do pipeline.