Referência da estrutura do pipeline do Code - AWS CodePipeline

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á.

Referência da estrutura do pipeline do Code

Por padrão, todo pipeline criado com êxito no AWS CodePipeline tem uma estrutura válida. No entanto, se um arquivo JSON for criado ou editado manualmente para criar ou atualizar um pipeline do AWS CLI, você poderá criar inadvertidamente uma estrutura inválida. A referência a seguir pode ajudar a entender melhor os requisitos da estrutura do pipeline e como solucionar problemas. Consulte as restrições em Cotas noAWSCodePipeline, que se aplicam a todos os pipelines.

Tipos de ação e fornecedores válidos no CodePipeline

O formato da estrutura de pipeline é usado para compilar ações e estágios em um pipeline. Um tipo de ação é composto por uma categoria de ação e um tipo de provedor.

Veja a seguir as categorias de ação válidas no CodePipeline:

  • Origem

  • Compilação

  • Teste

  • Implante

  • Aprovação

  • Invoke

Cada categoria de ação tem um conjunto designado de provedores. Cada provedor de ação, como o Amazon S3, tem um nome de provedor, comoS3, que deve ser usado noProviderna categoria de ação em sua estrutura de pipeline.

Há três valores válidos para o campo Owner na seção da categoria de ação na estrutura do pipeline: AWS, ThirdParty e Custom.

Para localizar o nome do provedor e as informações do proprietário do provedor de ação, consulte Referência da estrutura da ação ou Número de artefatos de entrada e saída para cada tipo de ação.

Essa tabela lista os provedores válidos por tipo de ação.

nota

Para ações do Bitbucket, GitHub ou GitHub Enterprise Server, consulte oCodeStarSourceConnection para ações do Bitbucket, GitHub e GitHub Enterprise Servertópico de referência da ação.

Provedores de ação válidos por tipo de ação
Categoria de ação Provedores de ação válidos Referência da ação
Origem Amazon S3 Amazon S3
Amazon ECR Amazon ECR
CodeCommit CodeCommit
CodeStarSourceConnection (para ações do Bitbucket, GitHub, GitHub Enterprise Server) CodeStarSourceConnection para ações do Bitbucket, GitHub e GitHub Enterprise Server
Compilação CodeBuild AWS CodeBuild
CloudBees personalizado Número de artefatos de entrada e saída para cada tipo de ação
Jenkins personalizado Número de artefatos de entrada e saída para cada tipo de ação
TeamCity personalizado Número de artefatos de entrada e saída para cada tipo de ação
Teste CodeBuild AWS CodeBuild
AWS Device Farm Número de artefatos de entrada e saída para cada tipo de ação
BlazeMeter personalizado Número de artefatos de entrada e saída para cada tipo de ação
ThirdParty GhostInspector Número de artefatos de entrada e saída para cada tipo de ação
Jenkins personalizado Número de artefatos de entrada e saída para cada tipo de ação
ThirdParty Micro Focus StormRunner Load Número de artefatos de entrada e saída para cada tipo de ação
ThirdParty Nouvola Número de artefatos de entrada e saída para cada tipo de ação
ThirdParty Runscope Número de artefatos de entrada e saída para cada tipo de ação
Implante Amazon S3 Número de artefatos de entrada e saída para cada tipo de ação
AWS CloudFormation AWS CloudFormation
CodeDeploy Número de artefatos de entrada e saída para cada tipo de ação
Amazon ECS Número de artefatos de entrada e saída para cada tipo de ação
Amazon ECS (Azul/Verde) (esta é a ação CodeDeployToECS) Número de artefatos de entrada e saída para cada tipo de ação
Elastic Beanstalk Número de artefatos de entrada e saída para cada tipo de ação
AWS AppConfig AWSAppConfig
AWS OpsWorks Número de artefatos de entrada e saída para cada tipo de ação
AWS Service Catalog Número de artefatos de entrada e saída para cada tipo de ação
Amazon Alexa Número de artefatos de entrada e saída para cada tipo de ação
Custom XebiaLabs Número de artefatos de entrada e saída para cada tipo de ação
Aprovação Manual Número de artefatos de entrada e saída para cada tipo de ação
Invoke AWS Lambda AWS Lambda
AWS Step Functions AWS Step Functions

Alguns tipos de ação no CodePipeline estão disponíveis noAWSSomente regiões. É possível que um tipo de ação esteja disponível em umAWSRegião, mas umAWSpara esse tipo de ação não está disponível.

Para obter mais informações sobre cada provedor de ações, consulte Integrações ao CodePipeline.

As seções a seguir fornecem exemplos para informações de provedores e propriedades de configuração para cada tipo de ação.

Requisitos de estrutura de estágios e pipelines no CodePipeline

Um pipeline com dois estágios tem a seguinte estrutura básica:

{ "roleArn": "An IAM ARN for a service role, such as arn:aws:iam::80398EXAMPLE:role/CodePipeline_Service_Role", "stages": [ { "name": "SourceStageName", "actions": [ ... See Requisitos da estrutura de ação no CodePipeline ... ] }, { "name": "NextStageName", "actions": [ ... See Requisitos da estrutura de ação no CodePipeline ... ] } ], "artifactStore": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated for you the first time you create a pipeline using the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose" }, "name": "YourPipelineName", "version": 1 }

A estrutura do pipeline tem estes requisitos:

  • Um pipeline deve ter pelo menos dois estágios.

  • O primeiro estágio de um pipeline deve ter pelo menos uma ação de origem. Só pode conter ações de origem.

  • Somente o primeiro estágio de um pipeline pode ter ações de origem.

  • Pelo menos um estágio em cada pipeline deve ter uma ação que não seja uma ação de origem.

  • Os nomes de todos os estágios de um pipeline devem ser exclusivos.

  • Os nomes dos estágios não podem ser editados no console do CodePipeline Se você editar o nome de um estágio usando a AWS CLI e o estágio tiver uma ação com um ou mais parâmetros secretos, como um token OAuth, o valor desses parâmetros secretos não será mantido. É necessário inserir manualmente o valor dos parâmetros (que são mascarados por quatro asteriscos no JSON devolvido pela AWS CLI) e incluí-los na estrutura JSON.

  • OartifactStoreO campo contém o tipo e local do bucket de artefatos para um pipeline com todas as ações no mesmoAWSRegião : Se você adicionar ações em uma região diferente do seu pipeline, oartifactStoresO mapeamento é utilizado para listar o bucket de artefatos para cadaAWSRegião onde as ações são executadas. Ao criar ou editar um pipeline, é necessário ter um bucket de artefato na região do pipeline e ter um bucket de artefato por região em que planeja executar uma ação.

    O exemplo a seguir mostra a estrutura básica de um pipeline com ações entre regiões que usa o parâmetro artifactStores:

    "pipeline": { "name": "YourPipelineName", "roleArn": "CodePipeline_Service_Role", "artifactStores": { "us-east-1": { "type": "S3", "location": "S3 artifact bucket name, such as codepipeline-us-east-1-1234567890" }, "us-west-2": { "type": "S3", "location": "S3 artifact bucket name, such as codepipeline-us-west-2-1234567890" } }, "stages": [ { ...
  • Os campos de metadados de pipeline são diferentes da estrutura do pipeline e não podem ser editados. Quando você atualiza um pipeline, a data no campo de metadados updated é alterada automaticamente.

  • Quando você edita ou atualiza um pipeline, o nome do pipeline não pode ser alterado.

    nota

    Se você deseja renomear um pipeline existente, pode usar o comando get-pipeline da CLI para criar um arquivo JSON que contenha a estrutura do pipeline. Depois, você pode usar o comando create-pipeline da CLI para criar um pipeline com essa estrutura e dar a ele um novo nome.

O número de versão de um pipeline é gerado e atualizado automaticamente sempre que o pipeline é atualizado.

Requisitos da estrutura de ação no CodePipeline

Uma ação tem a seguinte estrutura de nível elevado:

[ { "inputArtifacts": [ An input artifact structure, if supported for the action category ], "name": "ActionName", "region": "Region", "namespace": "source_namespace", "actionTypeId": { "category": "An action category", "owner": "AWS", "version": "1" "provider": "A provider type for the action category", }, "outputArtifacts": [ An output artifact structure, if supported for the action category ], "configuration": { Configuration details appropriate to the provider type }, "runOrder": A positive integer that indicates the run order within the stage, } ]

Para obter uma lista de exemplos de detalhes de configuration adequados para o tipo de provedor, consulte Detalhes de configuração por tipo de provedor.

A estrutura de ação tem estes requisitos:

  • Os nomes de todas as ações em um estágio devem ser exclusivos.

  • O artefato de entrada de uma ação deve ser exatamente igual ao artefato de saída declarado em uma ação precedente. Por exemplo, se uma ação anterior inclui a seguinte declaração:

    "outputArtifacts": [ { "MyApp" } ],

    e não há outros artefatos de saída, o artefato de entrada de uma ação seguinte deve ser:

    "inputArtifacts": [ { "MyApp" } ],

    Isso ocorre com todas as ações, não importa se estão no mesmo estágio ou em estágios seguintes. No entanto, o artefato de entrada não precisa ser a próxima ação na sequência rígida da ação que forneceu o artefato de saída. Ações em paralelo podem declarar pacotes de artefatos de saída diferentes, que, por sua vez, são usados por ações seguintes diferentes.

    A ilustração a seguir mostra um exemplo de artefatos de saída e de entrada em ações em um pipeline:

    
                        Um exemplo de artefatos de saída e de entrada em ações em um pipeline.
  • Os nomes dos artefatos de saída devem ser exclusivos em um pipeline. Por exemplo, um pipeline pode incluir uma ação que tenha um artefato de saída com o nome "MyApp" e outra ação que tenha um artefato de saída com o nome "MyBuiltApp". Mas um pipeline não pode incluir duas ações que tenham um artefato de saída com o nome "MyApp".

  • As ações entre regiões usam oRegionpara designar o campoAWSRegião em que as ações devem ser criadas. OAWSOs recursos gerados para essa ação devem ser gerados na mesma região fornecida noregioncampo. Não é possível criar ações entre regiões para os seguintes tipos de ação:

    • Ações de origem

    • Ações por provedores de terceiros

    • Ações por provedores personalizados

  • As ações podem ser configuradas com variáveis. Use o campo namespace para definir as informações de namespace e de variáveis para as variáveis de execução. Para obter informações de referência sobre variáveis de execução e variáveis de saída de ação, consulte Variables.

  • Para todos os tipos de ação compatíveis no momento, a única série de proprietário válida é "AWS", "ThirdParty" ou "Custom". Para obter mais informações, consulte o .Referência do CodePipeline.

  • O valor runOrder padrão de uma ação é 1. O valor deve ser um inteiro positivo (número natural). Não é permitido usar frações, números decimais ou negativos ou o número zero. Para especificar uma sequência de ações em série, use o menor número para a primeira ação e os maiores números para cada uma das ações em sequência restantes. Para especificar ações paralelas, use o mesmo número inteiro para cada ação que deseja executar em paralelo. No console, você pode especificar uma seqüência serial para uma ação escolhendoAdicionar grupo de açãono nível no estágio em que você deseja que ele seja executado, ou você pode especificar uma sequência paralela escolhendoAdicionar ação. Grupo de açõesrefere-se a uma ordem de execução de uma ou mais ações no mesmo nível.

    Por exemplo, se você deseja que três ações sejam executadas em sequência em um estágio, você daria o valor runOrder de 1 para a primeira ação, o valor runOrder de 2 para a segunda ação e o valor runOrder de 3 para a terceira ação. No entanto, se você deseja que a segunda ação e a terceira ação sejam executadas em paralelo, você daria o valor runOrder de 1 para a primeira ação e o valor runOrder de 2 para a segunda e a terceira.

    nota

    A numeração das ações em série não precisa estar em uma sequência rígida. Por exemplo, se você tem três ações em uma sequência e decide remover a segunda ação, você não precisa numerar novamente o valor runOrder da terceira ação. Como o valor runOrder dessa ação (3) é superior ao valor runOrder da primeira ação (1), ele será executado em série após a primeira ação no estágio.

  • Quando você usa um bucket do Amazon S3 como um local de implantação, também especifica uma chave de objeto. Uma chave de objeto pode ser um nome de arquivo (objeto) ou uma combinação de um prefixo (caminho da pasta) e um nome de arquivo. Você pode usar variáveis para especificar o nome do local que deseja que o pipeline use. As ações de implantação do Amazon S3 são compatíveis com o uso das variáveis nas chaves de objeto do Amazon S3 a seguir.

    Uso de variáveis no Amazon S3
    Variável Exemplo de entrada do console Saída
    datetime js-application/{datetime}.zip Carimbo de data/hora UTC neste formato: <YYYY>-<MM>-DD>_<HH>-<MM>-<SS>

    Exemplo:

    js-application/2019-01-10_07-39-57.zip

    uuid js-application/{uuid}.zip O UUID é um identificador globalmente exclusivo com garantia de diferenciação de qualquer outro identificador. O UUID está neste formato (todos os dígitos no formato hexadecimal): <8 dígitos>-<4 dígitos>-4 dígitos>-<4 dígitos>-<12 dígitos>

    Exemplo:

    js-application/54a60075-b96a-4bf3-9013-db3a9EXAMPLE.zip

  • Esses são osactionTypeIdcategorias para CodePipeline:

    • Source

    • Build

    • Approval

    • Deploy

    • Test

    • Invoke

    Alguns tipos de provedores e opções de configuração são fornecidos aqui.

  • Os tipos válidos de provedor de uma categoria de ação dependem da categoria. Por exemplo, para um tipo de ação de origem, um tipo de provedor válido é S3, GitHub, CodeCommit ou Amazon ECR. Esse exemplo mostra a estrutura para uma ação de origem com um provedor S3:

    "actionTypeId": { "category": "Source", "owner": "AWS", "version": "1", "provider": "S3"},
  • Toda ação deve ter uma configuração válida de ação, que depende do tipo de provedor para a ação em questão. A tabela a seguir mostra os elementos de configuração de ação necessários para cada tipo de provedor válido:

    Propriedades de configuração de ação para tipos de provedor
    Nome do provedor Nome do provedor no tipo de ação Propriedades de configuração A propriedade é necessária?
    Amazon S3 (provedor de ação de implantação) S3 BucketName Obrigatório
    Extract Obrigatório
    ObjectKey Obrigatório se Extract = falso
    KMSEncryptionKeyARN1 Optional
    CannedACL2 Optional
    CacheControl3 Optional
    Amazon ECR Para obter mais informações, incluindo exemplos relacionados a parâmetros do Amazon ECR, consulteAmazon ECR.
    CodeCommit Para obter mais informações, incluindo exemplos relacionados a parâmetros do CodeCommit, consulteCodeCommit.
    GitHub Para obter mais informações, incluindo exemplos relacionados a parâmetros do GitHub, consulte Referência da estrutura de ação de origem do GitHub versão 1.
    Amazon S3 (provedor de ação de origem) Para obter mais informações, incluindo exemplos relacionados a parâmetros de ação de origem do Amazon S3, consulteAmazon S3.
    AWS CloudFormation Para obter mais informações, incluindo exemplos relacionados a parâmetros do AWS CloudFormation, consulte AWS CloudFormation.
    CodeBuild Para obter mais descrição e exemplos relacionados a parâmetros do CodeBuild, consulteAWS CodeBuild.
    CodeDeploy Para obter mais descrição e exemplos relacionados a parâmetros do CodeDeploy, consulteAWS CodeDeploy.
    AWS Device Farm Para obter mais descrição e exemplos relacionados a parâmetros do AWS Device Farm, consulte AWS Device Farm.
    AWS Elastic Beanstalk ElasticBeanstalk ApplicationName Obrigatório
    EnvironmentName Obrigatório
    AWS Lambda Para obter mais informações, incluindo exemplos relacionados a parâmetros do AWS Lambda, consulte AWS Lambda.
    AWS OpsWorks Stacks OpsWorks Stack Obrigatório
    Layer Optional
    App Obrigatório
    Amazon ECS Para obter mais descrição e exemplos relacionados a parâmetros do Amazon ECS, consulteAmazon Elastic Container Service.
    Amazon ECS e CodeDeploy (azul/verde) Para obter mais descrição e exemplos relacionados a parâmetros azul/verde do Amazon ECS e CodeDeploy, consulteAmazon Elastic Container Service e CodeDeploy azul-verde.
    AWS Service Catalog ServiceCatalog TemplateFilePath Obrigatório
    ProductVersionName Obrigatório
    ProductType Obrigatório
    ProductVersionDescription Optional
    ProductId Obrigatório
    Alexa Skills Kit AlexaSkillsKit ClientId Obrigatório
    ClientSecret Obrigatório
    RefreshToken Obrigatório
    SkillId Obrigatório
    Jenkins O nome da ação que você forneceu no plug-in do CodePipeline para Jenkins (por exemplo,MyJenkinsProviderName) ProjectName Obrigatório
    Aprovação manual Manual CustomData Optional
    ExternalEntityLink Optional
    NotificationArn Optional

    1OKMSEncryptionKeyARNO parâmetro criptografa os artefatos carregados com oAWS KMS key. Para um Chave do KMS, você pode usar o ID da chave, o ARN da chave ou o ARN do alias.

    nota

    Os aliases são reconhecidos apenas na conta que criou a chave KMS. Para ações entre contas, você só pode usar o ID ou o ARN da chave para identificar a chave.

    Importante

    O CodePipeline suporta apenas chaves KMS simétricas. Não use uma chave KMS assimétrica para criptografar os dados no bucket do S3.

    2OCannedACLaplica o parâmetro especificadoACL enlatadaPara objetos implantados no Amazon S3. Isso substitui todas as ACLs existentes que foram aplicadas ao objeto.

    3O parâmetro CacheControl controla o comportamento do armazenamento em cache de solicitações/respostas de objetos no bucket. Para obter uma lista de valores válidos, consulte o campo de cabeçalho Cache-Control para operações HTTP. Para inserir vários valores em CacheControl, use uma vírgula entre cada valor. É possível adicionar um espaço após cada vírgula (opcional), conforme mostrado neste exemplo para a CLI:

    "CacheControl": "public, max-age=0, no-transform"

Número de artefatos de entrada e saída para cada tipo de ação

Dependendo do tipo de ação, você poderá ter o seguinte número de artefatos de entrada e de saída:

Limitações dos tipos de ação dos artefatos
Proprietário Tipo de ação Provedor Número válido de artefatos de entrada Número válido de artefatos de saída
AWS Origem Amazon S3 0 1
AWS Origem CodeCommit 0 1
AWS Origem Amazon ECR 0 1
Terceiro Origem GitHub 0 1
AWS Compilação CodeBuild 1 – 5 0 – 5
AWS Teste CodeBuild 1 – 5 0 – 5
AWS Teste AWS Device Farm 1 0
AWS Aprovação Manual 0 0
AWS Implante Amazon S3 1 0
AWS Implante AWS CloudFormation 0 – 10 0 – 1
AWS Implante CodeDeploy 1 0
AWS Implante AWS Elastic Beanstalk 1 0
AWS Implante AWS OpsWorks Stacks 1 0
AWS Implante Amazon ECS 1 0
AWS Implante AWS Service Catalog 1 0
AWS Invoke AWS Lambda 0 – 5 0 – 5
Terceiro Implante Alexa Skills Kit 1 – 2 0
Personalizar Compilação Jenkins 0 – 5 0 – 5
Personalizar Teste Jenkins 0 – 5 0 – 5
Personalizar Qualquer categoria compatível Conforme especificado na ação personalizada 0 – 5 0 – 5

Configurações padrão do parâmetro PollForSourceChanges

O padrão do parâmetro PollForSourceChanges é determinado pelo método usado para criar o pipeline, conforme descrito na tabela a seguir. Em muitos casos, o parâmetro PollForSourceChanges é padronizado como verdadeiro e deve ser desativado.

Quando o parâmetro PollForSourceChanges for padronizado como verdadeiro, faça o seguinte:

  • Adicione o parâmetro PollForSourceChanges ao arquivo JSON ou ao modelo do AWS CloudFormation.

  • Crie recursos de detecção de alterações (regra do CloudWatch Events, conforme aplicável).

  • Defina o parâmetro PollForSourceChanges para false.

    nota

    Se você criar uma regra ou um webhook do CloudWatch Events, é necessário definir o parâmetro como falso para evitar o acionamento do pipeline mais de uma vez.

    OPollForSourceChangesO parâmetro não é usado para ações de origem do Amazon ECR.

  • Padrões do parâmetro PollForSourceChanges
    Origem Método de criação Exemplo de saída da estrutura JSON de "configuração"
    CodeCommit O pipeline é criado com o console (e recursos de detecção de alterações são criados pelo console). O parâmetro é exibido na saída da estrutura de pipeline e assume false como padrão.
    BranchName": "main", "PollForSourceChanges": "false", "RepositoryName": "my-repo"
    O pipeline é criado com a CLI ouAWS CloudFormation, e oPollForSourceChangesO parâmetro não é exibido na saída JSON, mas define paratrue
    BranchName": "main", "RepositoryName": "my-repo"
    Amazon S3 O pipeline é criado com o console (e recursos de detecção de alterações são criados pelo console). O parâmetro é exibido na saída da estrutura de pipeline e assume false como padrão.
    "S3Bucket": "my-bucket", "S3ObjectKey": "object.zip", "PollForSourceChanges": "false"
    O pipeline é criado com a CLI ouAWS CloudFormation, e oPollForSourceChangesO parâmetro não é exibido na saída JSON, mas define paratrue
    "S3Bucket": "my-bucket", "S3ObjectKey": "object.zip"
    GitHub O pipeline é criado com o console (e recursos de detecção de alterações são criados pelo console). O parâmetro é exibido na saída da estrutura de pipeline e assume false como padrão.
    "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName" "PollForSourceChanges": "false", "Branch": "main" "OAuthToken": "****"
    O pipeline é criado com a CLI ouAWS CloudFormation, e oPollForSourceChangesO parâmetro não é exibido na saída JSON, mas define paratrue
    "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName", "Branch": "main", "OAuthToken": "****"

    ² SePollForSourceChangesO foi adicionado a qualquer momento à estrutura JSON ou aoAWS CloudFormation, ele é exibido como mostrado:

    "PollForSourceChanges": "true",

    ³ Para obter informações sobre os recursos de detecção de alterações que se aplicam a cada provedor de origem, consulteMétodos de detecção de alterações.

Detalhes de configuração por tipo de provedor

Essa seção lista parâmetros de configuration válidos para cada provedor de ações.

O exemplo a seguir mostra uma configuração válida para uma ação de implantação que usa o AWS Service Catalog, para um pipeline que foi criado no console sem um arquivo de configuração separado:

"configuration": { "TemplateFilePath": "S3_template.json", "ProductVersionName": "devops S3 v2", "ProductType": "CLOUD_FORMATION_TEMPLATE", "ProductVersionDescription": "Product version description", "ProductId": "prod-example123456" }

O exemplo a seguir mostra uma configuração válida para uma ação de implantação que usa o AWS Service Catalog, para um pipeline que foi criado no console com um arquivo de configuração sample_config.json separado:

"configuration": { "ConfigurationFilePath": "sample_config.json", "ProductId": "prod-example123456" }

O exemplo a seguir mostra uma configuração válida para uma ação de implantação que usa o Alexa Skills Kit:

"configuration": { "ClientId": "amzn1.application-oa2-client.aadEXAMPLE", "ClientSecret": "****", "RefreshToken": "****", "SkillId": "amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6cEXAMPLE" }

O exemplo a seguir mostra uma configuração válida para uma ação de implantação que usa o Amazon S3:

"configuration": { "BucketName": "website-bucket", "Extract": "true", "ObjectKey": "MyWebsite" }

O exemplo a seguir mostra uma configuração válida para uma aprovação manual:

"configuration": { "CustomData": "Comments on the manual approval", "ExternalEntityLink": "http://my-url.com", "NotificationArn": "arn:aws:sns:us-west-2:12345EXAMPLE:Notification" }