Executa uma operação em uma pilha do AWS CloudFormation. Uma pilha é um conjunto de recursos da AWS que pode gerenciar como uma unidade. Os recursos em uma pilha são definidos pelo modelo do AWS 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 AWS 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 AWS CloudFormation em que uma operação de pilha falhou, o CodePipeline chama a API DescribeStackEvents
do AWS 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
.
Tópicos
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 AWS 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 AWS 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 AWS CloudFormation o exclui e, em seguida, cria um novo. -
CREATE_UPDATE
cria a pilha, caso não exista. Se a pilha existir, o AWS CloudFormation a atualiza. Use esta ação para atualizar pilhas existentes. Diferente deREPLACE_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 AWS CloudFormation excluirá a pilha e criará uma nova. Se a pilha não estiver em um estado de falha, o AWS CloudFormation a atualiza.A pilha está em no estado de falha quando qualquer um dos seguintes tipos de status estiver exibido no AWS 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 AWS 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 AWS 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 AWS 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, oRoleArn
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 AWS 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 deSourceArtifact
e um nome de arquivo detemplate-export.json
cria um nomeTemplatePath
, 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 AWS 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 AWS 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 AWS CloudFormation.
-
- OutputFileName
-
Obrigatório: Não
Use
OutputFileName
para especificar um nome de arquivo de saída, comoCreateStackOutput.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çãoOutputs
da pilha AWS 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 deSourceArtifact
e um nome de arquivo detest-configuration.json
cria um nomeTemplateConfiguration
, 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 AWS 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 AWS 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 AWS CloudFormation.Para obter mais informações sobre a seção de saídas que pode ser criada para a ação do AWS 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 AWS 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 ter 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.
Declaração de ação
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 AWS CloudFormation.