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 ação de implantação do CloudFormation Executa uma operação em uma CloudFormation pilha. Uma pilha é uma coleção de AWS recursos que você pode gerenciar como uma única unidade. Os recursos em uma pilha são definidos pelo modelo do CloudFormation da pilha. Um conjunto de alterações cria uma comparação que pode ser visualizada sem alterar a pilha original. Para obter informações sobre os tipos de CloudFormation ações que podem ser executadas em pilhas e conjuntos de alterações, consulte o `ActionMode` parâmetro. Para criar uma mensagem de erro para uma CloudFormation ação em que uma operação de pilha falhou, CodePipeline chame a CloudFormation `DescribeStackEvents` API. Se uma função do IAM de ação tiver permissão para acessar essa API, os detalhes sobre o primeiro recurso com falha serão incluídos na mensagem CodePipeline de erro. Caso contrário, se a política de função não tiver a permissão apropriada, CodePipeline ignorará o acesso à API e, em vez disso, mostrará uma mensagem de erro genérica. Para fazer isso, a permissão `cloudformation:DescribeStackEvents` deve ser adicionada ao perfil de serviço ou a outros perfis do IAM para o pipeline. Se você não quiser que os detalhes do recurso apareçam nas mensagens de erro do pipeline, poderá revogar essa permissão para o perfil do IAM de ação removendo a permissão `cloudformation:DescribeStackEvents`. **Topics** + [Tipo de ação](#action-reference-CloudFormation-type) + [Parâmetros de configuração](#action-reference-CloudFormation-config) + [Input artifacts (Artefatos de entrada)](#action-reference-CloudFormation-input) + [Artefatos de saída](#action-reference-CloudFormation-output) + [Variáveis de saída](#action-reference-CloudFormation-variables) + [Permissões da função de serviço: CloudFormation ação](#edit-role-cloudformation) + [Declaração de ação](#action-reference-CloudFormation-example) + [Consulte também](#action-reference-CloudFormation-links) ## Tipo de ação + Categoria: `Deploy` + Proprietário: `AWS` + Fornecedor: `CloudFormation` + Versão: `1` ## Parâmetros de configuração **ActionMode** Obrigatório: Sim `ActionMode`é o nome da ação CloudFormation executada em uma pilha ou conjunto de alterações. Os seguintes modos de ação estão disponíveis: + `CHANGE_SET_EXECUTE` executa um conjunto de alterações para a pilha de recursos com base em um conjunto de atualizações de recurso especificadas. Com essa ação, CloudFormation começa a alterar a pilha. + `CHANGE_SET_REPLACE` cria um conjunto de alterações, se ainda não existir, com base no nome da pilha e no modelo enviado. Se o conjunto de alterações existir, ele será CloudFormation excluído e, em seguida, criará um novo. + `CREATE_UPDATE` cria a pilha, caso não exista. Se a pilha existir, CloudFormation atualiza a pilha. Use esta ação para atualizar pilhas existentes. Ao contrário`REPLACE_ON_FAILURE`, se a pilha existir e estiver em um estado de falha, CodePipeline não excluirá nem substituirá a pilha. + `DELETE_ONLY` exclui uma pilha. Se você especificar uma pilha que não existe, a ação será concluída com êxito sem excluir uma pilha. + `REPLACE_ON_FAILURE` cria uma pilha, caso não exista. Se a pilha existir e estiver em um estado de falha, CloudFormation excluirá a pilha e criará uma nova pilha. Se a pilha não estiver em um estado de falha, CloudFormation atualize-a. A pilha está em no estado de falha quando qualquer um dos seguintes tipos de status estiver exibido no CloudFormation: + `ROLLBACK_FAILED` + `CREATE_FAILED` + `DELETE_FAILED` + `UPDATE_ROLLBACK_FAILED` Use esta ação para substituir automaticamente as pilhas com falha sem recuperá-las nem solucionar o problema delas. **Importante** Recomendamos usar `REPLACE_ON_FAILURE` apenas para fins de teste, pois ele pode excluir sua pilha. **StackName** Obrigatório: Sim `StackName` é o nome de uma pilha existente ou de uma pilha que você deseja criar. **Capacidades** Obrigatório: condicional O uso de `Capabilities` reconhece que o modelo pode ter os recursos para criar e atualizar alguns recursos por conta própria e que esses recursos são determinados com base nos tipos de recursos do modelo. Essa propriedade será necessária se você tiver recursos do IAM em seu modelo de pilha ou criar uma pilha diretamente de um modelo que contém macros. Para que a CloudFormation ação opere com sucesso dessa forma, você deve reconhecer explicitamente que gostaria que ela funcionasse com um dos seguintes recursos: + `CAPABILITY_IAM` + `CAPABILITY_NAMED_IAM` + `CAPABILITY_AUTO_EXPAND` Você pode especificar mais de um recurso usando uma vírgula (sem espaço) entre os recursos. O exemplo em [Declaração de ação](#action-reference-CloudFormation-example) mostra uma entrada com as propriedades CAPABILITY\$1IAM e CAPABILITY\$1AUTO\$1EXPAND. Para obter mais informações sobre`Capabilities`, consulte as propriedades abaixo [UpdateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html)na *Referência da AWS CloudFormation API*. **ChangeSetName** Obrigatório: condicional `ChangeSetName` é o nome de um conjunto de alterações existente ou um novo conjunto de alterações que você deseja criar para a pilha especificada. Essa propriedade é necessária para os seguintes modos de ação: CHANGE\$1SET\$1REPLACE e CHANGE\$1SET\$1EXECUTE. Para todos os outros modos de ação, essa propriedade será ignorado. **RoleArn** Obrigatório: condicional O `RoleArn` é o ARN da função de serviço do IAM que o CloudFormation assume ao operar em recursos na pilha especificada. `RoleArn` não é aplicado ao executar um conjunto de alterações. Se você não usar CodePipeline para criar o conjunto de alterações, verifique se o conjunto de alterações ou a pilha tem uma função associada. Esse perfil deve estar na mesma conta do perfil da ação em execução, conforme configurado no `RoleArn` da declaração de ação. Essa propriedade é necessária para os seguintes modos de ação: + CREATE\$1UPDATE + REPLACE\$1ON\$1FAILURE + DELETE\$1ONLY + CHANGE\$1SET\$1REPLACE CloudFormation recebe uma URL assinada em S3 para o modelo; portanto, isso `RoleArn` não precisa de permissão para acessar o repositório de artefatos. No entanto, o `RoleArn` da ação *precisa* de permissão para acessar o bucket de artefatos, a fim de gerar o URL assinado. **TemplatePath** Obrigatório: condicional `TemplatePath`representa o arquivo CloudFormation de modelo. Inclua o arquivo em um artefato de entrada para essa ação. O nome do arquivo segue este formato: `Artifactname::TemplateFileName` `Artifactname` é o nome do artefato de entrada, da forma como aparece no CodePipeline. Por exemplo, um estágio de origem com o nome de artefato de `SourceArtifact` e um nome de arquivo de `template-export.json` cria um nome `TemplatePath`, conforme mostrado neste exemplo: ``` "TemplatePath": "SourceArtifact::template-export.json" ``` Essa propriedade é necessária para os seguintes modos de ação: + CREATE\$1UPDATE + REPLACE\$1ON\$1FAILURE + CHANGE\$1SET\$1REPLACE Para todos os outros modos de ação, essa propriedade será ignorado. O arquivo CloudFormation de modelo contendo o corpo do modelo tem um comprimento mínimo de 1 byte e um comprimento máximo de 1 MB. Para ações CloudFormation de implantação em CodePipeline, o tamanho máximo do artefato de entrada é sempre 256 MB. Para mais informações, consulte [Cotas no AWS CodePipeline.](limits.md) e [Limites do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html). **OutputFileName** Obrigatório: não Use `OutputFileName` para especificar um nome de arquivo de saída, como`CreateStackOutput.json`, que é CodePipeline adicionado ao artefato de saída do pipeline para essa ação. O arquivo JSON contém o conteúdo da `Outputs` seção da CloudFormation pilha. Se você não especificar um nome, CodePipeline não gera um arquivo ou artefato de saída. **ParameterOverrides** Obrigatório: não Os parâmetros são definidos no modelo de pilha e permitem que você forneça valores para eles no momento da criação ou atualização da pilha. Você pode usar um objeto JSON para definir valores de parâmetro em seu modelo. (Esses valores substituem os definidos no arquivo de configuração de modelo.) Para obter mais informações sobre como usar substituições de parâmetros, consulte [Propriedades de configuração (objeto JSON)](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-action-reference.html#w4363ab1c13c13b9). Recomendamos usar o arquivo de configuração de modelo para a maioria dos valores de parâmetro. Use substituições de parâmetros somente para valores que não são conhecidos até que o pipeline esteja em execução. Para obter mais informações, consulte [Usando funções de substituição de parâmetros com CodePipeline pipelines](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-parameter-override-functions.html) no Guia do *AWS CloudFormation usuário*. Todos os nomes de parâmetros devem estar presentes no modelo de pilha. **TemplateConfiguration** Obrigatório: não `TemplateConfiguration` é o arquivo de configuração do modelo. Inclua o arquivo em um artefato de entrada para essa ação. Ele pode conter valores de parâmetro de modelo e uma política de pilha. Para obter mais informações sobre o formato do arquivo de configuração de modelo, consulte [Artefatos do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-cfn-artifacts.html). O nome do arquivo de configuração de modelo segue este formato: `Artifactname::TemplateConfigurationFileName` `Artifactname` é o nome do artefato de entrada, da forma como aparece no CodePipeline. Por exemplo, um estágio de origem com o nome de artefato de `SourceArtifact` e um nome de arquivo de `test-configuration.json` cria um nome `TemplateConfiguration`, conforme mostrado neste exemplo: ``` "TemplateConfiguration": "SourceArtifact::test-configuration.json" ``` ## Input artifacts (Artefatos de entrada) + **Número de artefatos:** `0 to 10` + **Descrição:** Como entrada, a CloudFormation ação aceita opcionalmente artefatos para estas finalidades: + Fornecer o arquivo de modelo de pilha a ser executado. (Consulte o parâmetro `TemplatePath`.) + Fornecer o arquivo de configuração de modelo a ser usado. (Consulte o parâmetro `TemplateConfiguration`.) Para obter mais informações sobre o formato do arquivo de configuração de modelo, consulte [Artefatos do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-cfn-artifacts.html). + Fornecer o artefato para que uma função Lambda seja implantada como parte da pilha. CloudFormation ## Artefatos de saída + **Número de artefatos:** `0 to 1` + **Descrição:** se o parâmetro `OutputFileName` for especificado, haverá um artefato de saída produzido por essa ação que contém um arquivo JSON com o nome especificado. O arquivo JSON contém o conteúdo da seção Saídas da pilha do CloudFormation . Para obter mais informações sobre a seção de saídas que pode ser criada para a ação do CloudFormation , consulte [Saídas](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html). ## Variáveis de saída Quando configurada, essa ação produz variáveis que podem ser referenciadas pela configuração de ação de uma ação downstream no pipeline. Configure uma ação com um namespace a fim de disponibilizar as variáveis para a configuração de ações downstream. Para CloudFormation ações, as variáveis são produzidas a partir de qualquer valor designado na `Outputs` seção de um modelo de pilha. Observe que os únicos modos de CloudFormation ação que geram saídas são aqueles que resultam na criação ou atualização de uma pilha, como criação de pilha, atualizações de pilha e execução de conjuntos de alterações. Os modos de ação correspondentes que geram variáveis são: + `CHANGE_SET_EXECUTE` + `CHANGE_SET_REPLACE` + `CREATE_UPDATE` + `REPLACE_ON_FAILURE` Para obter mais informações, consulte [Referência de variáveis](reference-variables.md). Para ver um tutorial que mostra como criar um pipeline com uma ação de CloudFormation implantação em um pipeline que usa variáveis CloudFormation de saída, consulte[Tutorial: criar um pipeline que usa variáveis das ações de AWS CloudFormation implantação](tutorials-cloudformation-action.md). ## Permissões da função de serviço: CloudFormation ação Ao CodePipeline executar a ação, a política de função de CodePipeline serviço exige as seguintes permissões, com escopo adequado até o ARN do recurso do pipeline, a fim de manter o acesso com menos privilégios. Por exemplo, adicione o seguinte à declaração da política: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCFNStackAccess", "Effect": "Allow", "Action": [ "cloudformation:CreateStack", "cloudformation:UpdateStack", "cloudformation:DeleteStack", "cloudformation:DescribeStacks", "cloudformation:DescribeStackResources", "cloudformation:DescribeStackEvents", "cloudformation:GetTemplate", "cloudformation:DescribeChangeSet", "cloudformation:CreateChangeSet", "cloudformation:DeleteChangeSet", "cloudformation:ExecuteChangeSet" ], "Resource": [ "arn:aws:cloudformation:*:111122223333:stack/[[cfnDeployStackNames]]/*" ] }, { "Sid": "ValidateTemplate", "Effect": "Allow", "Action": [ "cloudformation:ValidateTemplate" ], "Resource": "*" }, { "Sid": "AllowIAMPassRole", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::111122223333:role/[[cfnExecutionRoles]]" ], "Condition": { "StringEqualsIfExists": { "iam:PassedToService": [ "cloudformation.amazonaws.com" ] } } } ] } ``` ------ Observe que a permissão `cloudformation:DescribeStackEvents` é opcional. Isso permite que a CloudFormation ação mostre uma mensagem de erro mais detalhada. Essa permissão poderá ser revogada do perfil do IAM se você não quiser que os detalhes do recurso apareçam nas mensagens de erro do pipeline. ## Declaração de ação ------ #### [ YAML ] ``` Name: ExecuteChangeSet ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' RunOrder: 2 Configuration: ActionMode: CHANGE_SET_EXECUTE Capabilities: CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND ChangeSetName: pipeline-changeset ParameterOverrides: '{"ProjectId": "my-project","CodeDeployRole": "CodeDeploy_Role_ARN"}' RoleArn: CloudFormation_Role_ARN StackName: my-project--lambda TemplateConfiguration: 'my-project--BuildArtifact::template-configuration.json' TemplatePath: 'my-project--BuildArtifact::template-export.yml' OutputArtifacts: [] InputArtifacts: - Name: my-project-BuildArtifact ``` ------ #### [ JSON ] ``` { "Name": "ExecuteChangeSet", "ActionTypeId": { "Category": "Deploy", "Owner": "AWS", "Provider": "CloudFormation", "Version": "1" }, "RunOrder": 2, "Configuration": { "ActionMode": "CHANGE_SET_EXECUTE", "Capabilities": "CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND", "ChangeSetName": "pipeline-changeset", "ParameterOverrides": "{\"ProjectId\": \"my-project\",\"CodeDeployRole\": \"CodeDeploy_Role_ARN\"}", "RoleArn": "CloudFormation_Role_ARN", "StackName": "my-project--lambda", "TemplateConfiguration": "my-project--BuildArtifact::template-configuration.json", "TemplatePath": "my-project--BuildArtifact::template-export.yml" }, "OutputArtifacts": [], "InputArtifacts": [ { "Name": "my-project-BuildArtifact" } ] }, ``` ------ ## Consulte também Os recursos relacionados a seguir podem ajudar você à medida que trabalha com esta ação. + [Referência de propriedades de configuração](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-action-reference.html) — Este capítulo de referência no *Guia AWS CloudFormation do usuário* fornece mais descrições e exemplos desses CodePipeline parâmetros. + [AWS CloudFormation Referência da API](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/) — O [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html)parâmetro na *Referência da AWS CloudFormation API* descreve os parâmetros da pilha para CloudFormation modelos.