CloudFormationReferência da ação de implantação do

Executa uma operação em uma pilha do CloudFormation. Uma pilha é um conjunto de recursos da AWS que você pode gerenciar como uma 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 ações do CloudFormation que podem ser executadas em pilhas e conjuntos de alterações, consulte o parâmetro ActionMode.

Para criar uma mensagem de erro para uma ação do CloudFormation em que uma operação de pilha falhou, o CodePipeline chama a API DescribeStackEvents do CloudFormation. Se um perfil 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 de erro do CodePipeline. Caso contrário, se a política de perfil não tiver a permissão apropriada, o CodePipeline vai 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.

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 que o CloudFormation executa em uma pilha ou um 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, 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, o CloudFormation o exclui e, em seguida, cria um novo.

• CREATE_UPDATE cria a pilha, caso não exista. Se a pilha existir, o CloudFormation a atualiza. Use esta ação para atualizar pilhas existentes. Diferente de REPLACE_ON_FAILURE, se a pilha existir e estiver no estado de falha, o 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 no estado de falha, o CloudFormation excluirá a pilha e criará uma nova. Se a pilha não estiver em um estado de falha, o CloudFormation a atualiza.

  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 ação do CloudFormation opere com êxito dessa maneira, você deve reconhecer explicitamente que deseja que ela faça isso 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 mostra uma entrada com as propriedades CAPABILITY_IAM e CAPABILITY_AUTO_EXPAND.

Para obter mais informações sobre Capabilities, consulte as propriedades em UpdateStack na Referência da API do AWS CloudFormation.

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_SET_REPLACE e CHANGE_SET_EXECUTE. 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 o CodePipeline para criar o conjunto de alterações, verifique se o conjunto de alterações ou a pilha está associada a uma função.

nota

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_UPDATE

• REPLACE_ON_FAILURE

• DELETE_ONLY

• CHANGE_SET_REPLACE

nota

O CloudFormation recebe um URL assinado em S3 para o modelo; portanto, esse RoleArn não precisa de permissão para acessar o bucket 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 de modelo do CloudFormation. 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_UPDATE

• REPLACE_ON_FAILURE

• CHANGE_SET_REPLACE

Para todos os outros modos de ação, essa propriedade será ignorado.

nota

O arquivo de modelo do CloudFormation que contém o corpo do modelo tem um tamanho mínimo de 1 byte e um tamanho máximo de 1 MB. Para ações de implantação do CloudFormation no CodePipeline, o tamanho máximo do artefato de entrada é sempre 256 MB. Para mais informações, consulte Cotas no AWS CodePipeline. e Limites do CloudFormation.

OutputFileName

Obrigatório: Não

Use OutputFileName para especificar um nome de arquivo de saída, como CreateStackOutput.json, que o CodePipeline adiciona ao artefato de saída do pipeline para essa ação. O arquivo JSON contém o conteúdo da seção Outputs da pilha CloudFormation.

Se você não especificar um nome, o CodePipeline não gerará um artefato ou arquivo 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).

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 Usar funções de substituição de parâmetros com pipelines do CodePipeline no Guia do usuário do AWS CloudFormation.

nota

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.

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 ação do CloudFormation aceita opcionalmente artefatos para as seguintes 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.

  • Fornecer o artefato para que uma função Lambda seja implantada como parte da pilha do 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.

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 ações do CloudFormation, as variáveis são produzidas com quaisquer valores designados na seção Outputs de um modelo de pilha. Observe que os únicos modos de ação do CloudFormation que geram saídas são aqueles que resultam na criação ou na atualização de uma pilha, como criação e atualizações de pilha, bem como execução de conjunto 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. Para ver um tutorial que mostra como criar um pipeline com uma ação de implantação do CloudFormation em um pipeline que usa variáveis de saída do CloudFormation, consulte Tutorial: Criar um pipeline que usa variáveis de ações de implantação do AWS CloudFormation.

Permissões do perfil de serviço: ação CloudFormation

Quando o CodePipeline executa a ação, o perfil de serviço do CodePipeline exige as permissões a seguir, com escopo indicado para o ARN de recurso do pipeline a fim de manter acesso com privilégio mínimo. 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 ação CloudFormation 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 das propriedades de configuração: este capítulo de referência no Guia do usuário do AWS CloudFormation fornece mais descrições e exemplos para esses parâmetros do CodePipeline.

• Referência da API do AWS CloudFormation: o parâmetro CreateStack na Referência da API do AWS CloudFormation descreve os parâmetros de pilha para modelos do CloudFormation.