AWS CloudFormation StackSets - AWS CodePipeline
Como as ações do AWS CloudFormation StackSets funcionam Como estruturar ações do StackSets em um pipelineA ação CloudFormationStackSetA ação CloudFormationStackInstancesModelos de permissões para operações de conjuntos de pilhasTipos de dados de parâmetro do modeloConsulte também

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

AWS CloudFormation StackSets

O CodePipeline permite realizar operações do AWS CloudFormation StackSets como parte do seu processo de CI/CD. Use um conjunto de pilhas para criar pilhas nas contas da AWS em várias regiões da AWS usando um único modelo do AWS CloudFormation. Todos os recursos incluídos em cada pilha são definidos pelo modelo do AWS CloudFormation do conjunto de pilhas. Ao criar o conjunto de pilhas, você especifica o modelo a ser usado, bem como os parâmetros e recursos exigidos pelo modelo.

nota

Você deve usar a conta de gerenciamento do AWS Organizations a ser implantada com os StackSets do AWS CloudFormation. Você não pode usar uma conta de administração delegada para essa ação.

Para obter mais informações sobre os conceitos dos StackSets do AWS CloudFormation, consulte Conceitos dos StackSets no Guia do usuário do AWS CloudFormation.

Você integra seu pipeline ao AWS CloudFormation StackSets por meio de dois tipos de ação distintos, que são usados em conjunto:

  • A ação CloudFormationStackSet cria ou atualiza um conjunto de pilhas ou instâncias de pilha a partir do modelo armazenado no local de origem do pipeline. Sempre que um conjunto de pilhas é criado ou atualizado, ele inicia uma implantação dessas alterações em instâncias especificadas. No console, você pode escolher o provedor de ação do CloudFormation Stack Set ao criar ou editar seu pipeline.

  • A ação CloudFormationStackInstances implanta alterações da ação CloudFormationStackSet para instâncias especificadas, cria novas instâncias de pilha e define substituições de parâmetros para instâncias especificadas. No console, você pode escolher o provedor de ação do CloudFormation Stack Instances ao editar um pipeline existente.

nota

As ações CloudFormationStackSet e CloudFormationStackInstances não estão disponíveis nas regiões Ásia Pacífico (Hong Kong), Europa (Zurique), Europa (Milão), África (Cidade do Cabo) e Oriente Médio (Bahrein). Para fazer referência a outras ações disponíveis, consulte Integrações de produtos e serviços com CodePipeline.

Você pode usar essas ações para realizar implantações em contas da AWS de destino ou IDs de unidade organizacional da AWS Organizations de destino.

nota

Para realizar implantações em contas ou IDs de unidade organizacional da AWS Organizations de destino e usar o modelo de permissões gerenciadas por serviços, você deve habilitar o acesso confiável entre o AWS CloudFormation StackSets e o AWS Organizations. Para obter mais informações, consulte Como habilitar o acesso confiável com o AWS CloudFormation Stacksets.

Como as ações do AWS CloudFormation StackSets funcionam

Uma ação CloudFormationStackSet cria ou atualiza recursos; o que determinará isso é se a ação está sendo executada pela primeira vez ou não.

A ação CloudFormationStackSet cria ou atualiza o conjunto de pilhas e implanta essas alterações em instâncias especificadas.

nota

Se você usar essa ação para fazer uma atualização que inclua a adição de instâncias de pilha, as novas instâncias serão implantadas primeiro e a atualização será concluída por último. As novas instâncias recebem primeiro a versão antiga. Em seguida, a atualização é aplicada a todas as instâncias.

  • Criar: quando nenhuma instância é especificada e o conjunto de pilhas não existe, a ação CloudFormationStackSet cria o conjunto de pilhas sem criar nenhuma instância.

  • Atualizar: quando a ação CloudFormationStackSet é executada para um conjunto de pilhas que já foi criado, a ação atualiza o conjunto de pilhas. Se nenhuma instância for especificada e o conjunto de pilhas já existir, todas as instâncias serão atualizadas. Se essa ação for usada para atualizar instâncias específicas, todas as instâncias restantes passarão para o status OUTDATED.

    Você pode usar a ação CloudFormationStackSet para atualizar o conjunto de pilhas da seguinte maneira.

    • Atualize o modelo em algumas ou em todas as instâncias.

    • Atualize os parâmetros em algumas ou em todas as instâncias.

    • Atualize o perfil de execução do conjunto de pilhas (isso deve corresponder ao perfil de execução especificado no perfil Administrador).

    • Altere o modelo de permissões (somente se nenhuma instância tiver sido criada).

    • Ative/desative AutoDeployment se o modelo de permissões do conjunto de pilhas for Service Managed.

    • Atualize o perfil Administrador.

    • Atualize a descrição no conjunto de pilhas.

    • Adicione destinos de implantação à atualização do conjunto de pilhas para criar novas instâncias de pilha.

A ação CloudFormationStackInstances cria novas instâncias de pilha ou atualiza instâncias de pilha desatualizadas. Uma instância fica desatualizada quando um conjunto de pilhas é atualizado, mas nem todas as instâncias dentro dela são atualizadas.

  • Criar: se a pilha já existir, a ação CloudFormationStackInstances atualizará somente as instâncias e não criará instâncias da pilha.

  • Atualizar: depois que a ação CloudFormationStackSet for executada, se o modelo ou os parâmetros tiverem sido atualizados somente em algumas instâncias, o restante será marcado como OUTDATED. Nos estágios posteriores do pipeline, CloudFormationStackInstances atualiza o restante das instâncias no conjunto de pilhas em ondas para que todas as instâncias sejam marcadas como CURRENT. Essa ação também pode ser usada para adicionar instâncias extras ou substituir parâmetros em instâncias novas ou existentes.

Como parte de uma atualização, as ações CloudFormationStackSet e CloudFormationStackInstances podem especificar novos destinos de implantação, o que cria novas instâncias de pilha.

Como parte de uma atualização, as ações CloudFormationStackSet e CloudFormationStackInstances não excluem conjuntos de pilhas, instâncias ou recursos. Quando a ação atualiza uma pilha, mas não especifica todas as instâncias a serem atualizadas, as instâncias que não foram especificadas para atualização são removidas da atualização e definidas para o status OUTDATED.

Durante uma implantação, as instâncias de pilha também poderão mostrar o status OUTDATED se a implantação nas instâncias falhar.

Como estruturar ações do StackSets em um pipeline

Como prática recomendada, você deve criar o pipeline para que o conjunto de pilhas seja criado e implantado inicialmente em um subconjunto ou em uma única instância. Após testar a implantação e visualizar o conjunto de pilhas gerado, adicione a ação CloudFormationStackInstances para que as instâncias restantes sejam criadas e atualizadas.

Use o console ou a CLI para criar a estrutura de pipeline recomendada da seguinte maneira:

  1. Crie um pipeline com uma ação de origem (obrigatória) e a ação CloudFormationStackSet como ação de implantação. Execute seu pipeline.

  2. Quando seu pipeline é executado pela primeira vez, a ação CloudFormationStackSet cria seu conjunto de pilhas e pelo menos uma instância inicial. Verifique a criação do conjunto de pilhas e analise a implantação na sua instância inicial. Por exemplo, para a criação inicial do conjunto de pilhas para a conta Account-A em que us-east-1 é a região especificada, a instância da pilha é criada com o conjunto de pilhas:

    Instância da pilha Região Status
    StackInstanceID-1 us-east-1 CURRENT

  3. Edite seu pipeline para adicionar CloudFormationStackInstances como a segunda ação de implantação para criar/atualizar instâncias de pilha para os destinos que você designar. Por exemplo, para a criação de instâncias de pilha para a conta Account-A em que as regiões us-east-2 e eu-central-1 são especificadas, as instâncias de pilha restantes são criadas e a instância inicial permanece atualizada da seguinte maneira:

    Instância da pilha Região Status
    StackInstanceID-1 us-east-1 CURRENT
    StackInstanceID-2 us-east-2 CURRENT
    StackInstanceID-3 eu-central-1 CURRENT

  4. Execute seu pipeline conforme necessário para atualizar seu conjunto de pilhas e atualize ou crie instâncias de pilha.

Quando você inicia uma atualização da pilha em que removeu os destinos de implantação da configuração da ação, as instâncias da pilha que não foram designadas para atualização são removidas da implantação e passam para o status OUTDATED. Por exemplo, na atualização da instância de pilha para a conta Account-A em que a região us-east-2 é removida da configuração da ação, as instâncias de pilha restantes são criadas e a instância removida é definida como OUTDATED da seguinte maneira:

Instância da pilha Região Status
StackInstanceID-1 us-east-1 CURRENT
StackInstanceID-2 us-east-2 OUTDATED
StackInstanceID-3 eu-central-1 CURRENT

Para obter mais informações sobre as práticas recomendadas para implantar conjuntos de pilhas, consulte Práticas recomendadas para StackSets no Guia do usuário do AWS CloudFormation.

A ação CloudFormationStackSet

Esta ação cria ou atualiza um conjunto de pilhas a partir do modelo armazenado no local de origem do pipeline.

Após definir um conjunto de pilhas, você pode criar, atualizar ou excluir pilhas nas contas e regiões de destino especificadas nos parâmetros de configuração. Ao criar, atualizar ou excluir pilhas, você também pode especificar preferências, como a ordem das regiões para que as operações sejam realizadas, o percentual de tolerância a falhas para interrupção das operações de pilhas e a quantidade de contas nas quais as operações serão executadas nas pilhas simultaneamente.

Um conjunto de pilhas é um recurso regional. Se você criar um conjunto de pilhas em uma região da AWS, não será possível acessá-lo em outras regiões.

Quando essa ação é usada como uma ação de atualização para o conjunto de pilhas, as atualizações na pilha não são permitidas sem uma implantação em pelo menos uma instância da pilha.

Tipo de ação

  • Categoria: Deploy

  • Proprietário: AWS

  • Fornecedor: CloudFormationStackSet

  • Versão: 1

Parâmetros de configuração

StackSetName

Obrigatório: sim

O nome a ser associado ao conjunto de pilhas. Esse nome deve ser exclusivo na região em que ele foi criado.

O nome pode conter apenas caracteres alfanuméricos e hifens. Ele deve começar com um caractere alfabético e ter 128 caracteres ou menos.

Descrição

Obrigatório: não

Uma descrição do conjunto de pilhas. Você pode usar isso para descrever a finalidade do conjunto de pilhas ou outras informações relevantes.

TemplatePath

Obrigatório: sim

O local do modelo que define os recursos no conjunto de pilhas. Isso deve apontar para um modelo com um tamanho máximo de 460.800 bytes.

Insira o caminho para o nome do artefato de origem e o arquivo de modelo no formato "InputArtifactName::TemplateFileName", conforme mostrado no exemplo a seguir.

SourceArtifact::template.txt
Parâmetros

Obrigatório: não

Uma lista de parâmetros de modelo para seu conjunto de pilhas que são atualizados durante uma implantação.

Você pode fornecer parâmetros como uma lista literal ou um caminho de arquivo:

  • Você pode inserir parâmetros no seguinte formato de sintaxe abreviada: ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string. Para obter mais informações sobre tipos de dados, consulte Tipos de dados de parâmetro do modelo.

    O exemplo a seguir mostra um parâmetro chamado BucketName com o valor my-bucket.

    ParameterKey=BucketName,ParameterValue=my-bucket

    O exemplo a seguir mostra uma entrada com vários parâmetros:

                                                                                                          
  ParameterKey=BucketName,ParameterValue=my-bucket
  ParameterKey=Asset1,ParameterValue=true              
  ParameterKey=Asset2,ParameterValue=true

  • Você pode inserir o local do arquivo que contém uma lista de substituições de parâmetros de modelo inseridas no formato "InputArtifactName::ParametersFileName", conforme mostrado no exemplo a seguir.

    SourceArtifact::parameters.txt

    O exemplo a seguir mostra o conteúdo do arquivo parameters.txt.

    [
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    },
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    }
]
Capacidades

Obrigatório: não

Indica que o modelo pode criar e atualizar recursos, dependendo dos tipos de recursos no modelo.

Você deve usar essa propriedade se tiver recursos do IAM em seu modelo de pilha ou criar uma pilha diretamente a partir de um modelo que contenha macros. Para que a ação AWS CloudFormation opere com êxito dessa forma, você deve usar um dos seguintes recursos:

  • CAPABILITY_IAM

  • CAPABILITY_NAMED_IAM

Você pode especificar mais de um recurso usando uma vírgula sem espaço entre os recursos. O exemplo em Exemplo de configuração de ação do CloudFormationStackset mostra uma entrada com vários recursos.

PermissionModel

Obrigatório: não

Determina como os perfis do IAM são criados e gerenciados. Se o campo não for especificado, o padrão será usado. Para obter mais informações, consulte Modelos de permissões para operações de conjuntos de pilhas.

Os valores válidos são:

  • SELF_MANAGED (padrão): você deve criar perfis de administrador e de execução para implantação em contas de destino.

  • SERVICE_MANAGED: AWS CloudFormation o StackSets cria automaticamente os perfis do IAM necessários à implantação em contas gerenciadas pelo AWS Organizations. Isso requer que uma conta seja membro de uma organização.

nota

Este parâmetro só pode ser alterado quando não há instâncias de pilha no conjunto de pilhas.

AdministrationRoleArn
nota

Como o AWS CloudFormation StackSets executa operações em várias contas, você deve definir as permissões necessárias nessas contas para que possa criar o conjunto de pilhas.

Obrigatório: não

nota

Este parâmetro é opcional para o modelo de permissões SELF_MANAGED e não é usado para o modelo de permissões SERVICE_MANAGED.

O ARN do perfil do IAM na conta do administrador usada para realizar operações de conjunto de pilhas.

O nome pode conter caracteres alfanuméricos, qualquer um dos seguintes caracteres: _+=,.@- e sem espaços. O nome não faz distinção entre maiúsculas e minúsculas. Este nome de perfil deve ter um tamanho mínimo de 20 caracteres e um tamanho máximo de 2.048 caracteres. Os nomes de perfil deve ser exclusivo na conta. O nome do perfil especificado aqui deve ser um nome de perfil existente. Se você não especificar o nome do perfil, ele será definido como AWSCloudFormationStackSetAdministrationRole. Se você especificar ServiceManaged, não deverá definir um nome de perfil.

ExecutionRoleName
nota

Como o AWS CloudFormation StackSets executa operações em várias contas, você deve definir as permissões necessárias nessas contas para que possa criar o conjunto de pilhas.

Obrigatório: não

nota

Este parâmetro é opcional para o modelo de permissões SELF_MANAGED e não é usado para o modelo de permissões SERVICE_MANAGED.

O nome do perfil do IAM nas contas de destino usadas para realizar operações de conjunto de pilhas. O nome pode conter caracteres alfanuméricos, qualquer um dos seguintes caracteres: _+=,.@- e sem espaços. O nome não faz distinção entre maiúsculas e minúsculas. Este nome de perfil deve ter um tamanho mínimo de 1 caractere e um tamanho máximo de 64 caracteres. Os nomes de perfil deve ser exclusivo na conta. O nome do perfil especificado aqui deve ser um nome de perfil existente. Não especifique esse perfil se você estiver usando perfis de execução personalizados. Se você não especificar o nome do perfil, ele será definido como AWSCloudFormationStackSetExecutionRole. Se você definir ServiceManaged como true, não deverá definir um nome de perfil.

OrganizationsAutoDeployment

Obrigatório: não

nota

Este parâmetro é opcional para o modelo de permissões SERVICE_MANAGED e não é usado para o modelo de permissões SELF_MANAGED.

Descreve se o AWS CloudFormation StackSets é implantado automaticamente em contas do AWS Organizations que são adicionadas a uma organização ou unidade organizacional (UO) de destino. Se OrganizationsAutoDeployment for especificado, não especifique DeploymentTargets e Regions.

nota

Se nenhuma entrada for fornecida para OrganizationsAutoDeployment, o valor padrão será Disabled.

Os valores válidos são:

  • Enabled. Obrigatório: Não.

    O StackSets implantará automaticamente instâncias de pilha adicionais em contas do AWS Organizations adicionadas a uma organização ou unidade organizacional (UO) de destino nas regiões especificadas. Se uma conta for removida de uma organização ou UO de destino, o AWS CloudFormation StackSets excluirá instâncias de pilha da conta nas regiões especificadas.

  • Disabled. Obrigatório: Não.

    O StackSets não implantará automaticamente instâncias de pilha adicionais em contas da AWS Organizations adicionadas a uma organização ou unidade organizacional (UO) de destino nas regiões especificadas.

  • EnabledWithStackRetention. Obrigatório: Não.

    Os recursos de pilha são retidos quando uma conta é removida de uma organização ou OU de destino.

DeploymentTargets

Obrigatório: não

nota

Para o modelo de permissões SERVICE_MANAGED, você pode fornecer o ID raiz da organização ou os IDs da unidade organizacional como destinos de implantação. Para o modelo de permissões SELF_MANAGED, você só pode fornecer contas.

nota

Quando este parâmetro é selecionado, você também deve selecionar Regions.

Uma lista de contas ou IDs de unidade organizacional da AWS em que as instâncias de conjunto de pilhas devem ser criadas/atualizadas.

  • Accounts:

    Você pode fornecer contas como uma lista literal ou um caminho de arquivo:

    • Literal: insira parâmetros no formato de sintaxe abreviada account_ID,account_ID, conforme mostrado no exemplo a seguir.

      111111222222,333333444444

    • Caminho do arquivo: o local do arquivo que contém uma lista de contas da AWS em que as instâncias de conjunto de pilhas devem ser criadas/atualizadas, inseridas no formato InputArtifactName::AccountsFileName. Se você usar o caminho do arquivo para especificar accounts ou OrganizationalUnitIds, o formato do arquivo deverá estar em JSON, conforme mostrado no exemplo a seguir.

      SourceArtifact::accounts.txt

      O exemplo a seguir mostra o conteúdo do arquivo accounts.txt.

      [
    "111111222222"
]

      O exemplo a seguir mostra o conteúdo do arquivo para accounts.txt ao listar mais de uma conta:

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds:

    nota

    Este parâmetro é opcional para o modelo de permissões SERVICE_MANAGED e não é usado para o modelo de permissões SELF_MANAGED. Não o utilize se você selecionar OrganizationsAutoDeployment.

    As unidades organizacionais da AWS nas quais serão atualizadas as instâncias de pilha associadas.

    Você pode fornecer IDs de unidade organizacional como uma lista literal ou um caminho de arquivo:

    • Literal: insira uma matriz de strings separadas por vírgulas, conforme mostrado no exemplo a seguir.

      ou-examplerootid111-exampleouid111,ou-examplerootid222-exampleouid222

    • Caminho do arquivo: o local do arquivo que contém uma lista de OrganizationalUnitIds nas quais serão criadas ou atualizadas instâncias de conjunto de pilhas. Se você usar o caminho do arquivo para especificar accounts ou OrganizationalUnitIds, o formato do arquivo deverá estar em JSON, conforme mostrado no exemplo a seguir.

      Insira um caminho para o arquivo no formato InputArtifactName::OrganizationalUnitIdsFileName.

      SourceArtifact::OU-IDs.txt

      O exemplo a seguir mostra o conteúdo do arquivo OU-IDs.txt:

      [
    "ou-examplerootid111-exampleouid111","ou-examplerootid222-exampleouid222"
]
Regiões

Obrigatório: não

nota

Quando este parâmetro é selecionado, você também deve selecionar DeploymentTargets.

Uma lista das regiões da AWS em que as instâncias de conjunto de pilhas são criadas ou atualizadas. As regiões são atualizadas na ordem em que são inseridas.

Insira uma lista de regiões da AWS válidas no formato Region1,Region2, conforme mostrado no exemplo a seguir.

us-west-2,us-east-1
FailureTolerancePercentage

Obrigatório: não

A porcentagem de contas, por região, em que essa operação de pilha pode falhar antes que o AWS CloudFormation interrompa a operação nessa região. Se a operação for interrompida em uma região, o AWS CloudFormation não tentará a operação nas regiões subsequentes. Ao calcular o número de contas com base na porcentagem especificada, o AWS CloudFormation arredonda para o número inteiro anterior.

MaxConcurrentPercentage

Obrigatório: não

A porcentagem máxima de contas em que essa operação pode ser executada ao mesmo tempo. Ao calcular o número de contas com base na porcentagem especificada, o AWS CloudFormation arredonda para o número inteiro anterior. Se o arredondamento para baixo resultar em zero, o AWS CloudFormation definirá o número como um. Embora você use essa configuração para especificar o máximo, nas grandes implementações, o número real de contas utilizadas simultaneamente pode ser menor devido ao controle de utilização do serviço.

RegionConcurrencyType

Obrigatório: não

Você pode especificar se o conjunto de pilhas deve ser implantado entre Regiões da AWS sequencial ou paralelamente, configurando o parâmetro de implantação simultânea da região. Quando a simultaneidade da região é especificada para implantar pilhas em várias Regiões da AWS paralelamente, isso pode resultar tempos gerais de implantação mais rápidos.

  • Em paralelo: as implantações de conjuntos de pilhas serão conduzidas simultaneamente, desde que as falhas de implantação de uma região não excedam uma tolerância a falhas especificada.

  • Sequencial: as implantações de conjuntos de pilhas serão conduzidas uma de cada vez, desde que as falhas de implantação de uma região não excedam uma tolerância a falhas especificada. A implantação sequencial é a seleção padrão.

ConcurrencyMode

Obrigatório: não

O modo de simultaneidade permite escolher como o nível de simultaneidade se comporta durante as operações de conjunto de pilhas, seja com tolerância da falhas estrita ou moderada. A Alta tolerância a falhas reduz a velocidade de implantação à medida que ocorrem falhas na operação do conjunto de pilhas porque a simultaneidade diminui para cada falha. A Tolerância moderada a falhas prioriza a velocidade de implantação e, ao mesmo tempo, aproveita os recursos de segurança do AWS CloudFormation.

  • STRICT_FAILURE_TOLERANCE: essa opção reduz dinamicamente o nível de simultaneidade para garantir que o número de contas com falha nunca exceda uma tolerância a falhas específica. Esse é o comportamento padrão.

  • SOFT_FAILURE_TOLERANCE: essa opção desacopla a tolerância a falhas da simultaneidade real. Isso permite que as operações de conjunto de pilhas em um nível de simultaneidade definido, independentemente do número de falhas.

Input artifacts (Artefatos de entrada)

Você deve incluir pelo menos um artefato de entrada que contenha o modelo para o conjunto de pilhas em uma ação CloudFormationStackSet. Você pode incluir mais artefatos de entrada para listas de destinos, contas e parâmetros de implantação.

  • Número de artefatos: 1 to 3

  • Descrição: você pode incluir artefatos para fornecer:

    • O arquivo de modelo de pilha. (Consulte o parâmetro TemplatePath.)

    • O arquivo de parâmetros. (Consulte o parâmetro Parameters.)

    • O arquivo de contas. (Consulte o parâmetro DeploymentTargets.)

Artefatos de saída

  • Número de artefatos: 0

  • Descrição: os artefatos de saída não se aplicam a esse tipo de ação.

Variáveis de saída

Se você configurar essa ação, ela produzirá variáveis que podem ser referenciadas pela configuraçã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.

  • StackSetId: o ID do conjunto de pilhas.

  • OperationId: o ID da operação de conjunto de pilhas.

Para obter mais informações, consulte Variáveis.

Exemplo de configuração de ação do CloudFormationStackset

Os exemplos a seguir mostram a configuração da ação CloudFormationStackSet.

Exemplo do modelo de permissões autogerenciadas

O exemplo a seguir mostra uma ação do CloudFormationStackSet em que o destino de implantação inserido é um ID de conta da AWS.

YAML
Name: CreateStackSet
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackSet
  Version: '1'
RunOrder: 1
Configuration:
  DeploymentTargets: '111111222222'
  FailureTolerancePercentage: '20'
  MaxConcurrentPercentage: '25'
  PermissionModel: SELF_MANAGED
  Regions: us-east-1
  StackSetName: my-stackset
  TemplatePath: 'SourceArtifact::template.json'
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: us-west-2
Namespace: DeployVariables
JSON
{
    "Name": "CreateStackSet",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackSet",
        "Version": "1"
    },
    "RunOrder": 1,
    "Configuration": {
        "DeploymentTargets": "111111222222",
        "FailureTolerancePercentage": "20",
        "MaxConcurrentPercentage": "25",
        "PermissionModel": "SELF_MANAGED",
        "Regions": "us-east-1",
        "StackSetName": "my-stackset",
        "TemplatePath": "SourceArtifact::template.json"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "us-west-2",
    "Namespace": "DeployVariables"
}

Exemplo do modelo de permissões autogerenciadas

O exemplo a seguir mostra uma ação do CloudFormationStackSet para o modelo de permissões gerenciadas por serviços em que a opção de implantação automática no AWS Organizations é habilitada com retenção de pilha.

YAML
Name: Deploy
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackSet
  Version: '1'
RunOrder: 1
Configuration:
  Capabilities: 'CAPABILITY_IAM,CAPABILITY_NAMED_IAM'
  OrganizationsAutoDeployment: EnabledWithStackRetention
  PermissionModel: SERVICE_MANAGED
  StackSetName: stacks-orgs
  TemplatePath: 'SourceArtifact::template.json'
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: eu-central-1
Namespace: DeployVariables
JSON
{
    "Name": "Deploy",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackSet",
        "Version": "1"
    },
    "RunOrder": 1,
    "Configuration": {
        "Capabilities": "CAPABILITY_IAM,CAPABILITY_NAMED_IAM",
        "OrganizationsAutoDeployment": "EnabledWithStackRetention",
        "PermissionModel": "SERVICE_MANAGED",
        "StackSetName": "stacks-orgs",
        "TemplatePath": "SourceArtifact::template.json"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "eu-central-1",
    "Namespace": "DeployVariables"
}

A ação CloudFormationStackInstances

Essa ação cria novas instâncias e implanta conjuntos de pilhas em instâncias especificadas. Uma instância de pilha é uma referência a uma pilha em uma conta de destino dentro de uma região. É possível haver uma instância de pilha sem uma pilha. Por exemplo, se a criação da pilha não for bem-sucedida, a instância de pilha mostrará o motivo da falha da criação da pilha. Uma instância de pilha está associada a apenas um conjunto de pilhas.

Após a criação inicial de um conjunto de pilhas, você pode adicionar novas instâncias de pilha usando CloudFormationStackInstances. Os valores dos parâmetros do modelo podem ser substituídos no nível da instância da pilha durante as operações de criação ou atualização da instância do conjunto de pilhas.

Cada conjunto de pilhas tem um modelo e um conjunto de parâmetros de modelo. Ao atualizar o modelo ou os parâmetros do modelo, você os atualiza para todo o conjunto. Em seguida, todos os status da instância são definidos como OUTDATED até que as alterações sejam implantadas nessa instância.

Para substituir valores de parâmetros em instâncias específicas, por exemplo, se o modelo contiver um parâmetro para stage com um valor prod, você poderá substituir o valor desse parâmetro para que seja beta ou gamma.

Tipo de ação

  • Categoria: Deploy

  • Proprietário: AWS

  • Fornecedor: CloudFormationStackInstances

  • Versão: 1

Parâmetros de configuração

StackSetName

Obrigatório: sim

O nome a ser associado ao conjunto de pilhas. Esse nome deve ser exclusivo na região em que ele foi criado.

O nome pode conter apenas caracteres alfanuméricos e hifens. Ele deve começar com um caractere alfabético e ter 128 caracteres ou menos.

DeploymentTargets

Obrigatório: não

nota

Para o modelo de permissões SERVICE_MANAGED, você pode fornecer o ID raiz da organização ou os IDs da unidade organizacional como destinos de implantação. Para o modelo de permissões SELF_MANAGED, você só pode fornecer contas.

nota

Quando este parâmetro é selecionado, você também deve selecionar Regions.

Uma lista de contas ou IDs de unidade organizacional da AWS em que as instâncias de conjunto de pilhas devem ser criadas/atualizadas.

  • Accounts:

    Você pode fornecer contas como uma lista literal ou um caminho de arquivo:

    • Literal: insira parâmetros no formato de sintaxe abreviada account_ID,account_ID, conforme mostrado no exemplo a seguir.

      111111222222,333333444444

    • Caminho do arquivo: o local do arquivo que contém uma lista de contas da AWS em que as instâncias de conjunto de pilhas devem ser criadas/atualizadas, inseridas no formato InputArtifactName::AccountsFileName. Se você usar o caminho do arquivo para especificar accounts ou OrganizationalUnitIds, o formato do arquivo deverá estar em JSON, conforme mostrado no exemplo a seguir.

      SourceArtifact::accounts.txt

      O exemplo a seguir mostra o conteúdo do arquivo accounts.txt:

      [
    "111111222222"
]

      O exemplo a seguir mostra o conteúdo do arquivo para accounts.txt ao listar mais de uma conta:

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds:

    nota

    Este parâmetro é opcional para o modelo de permissões SERVICE_MANAGED e não é usado para o modelo de permissões SELF_MANAGED. Não o utilize se você selecionar OrganizationsAutoDeployment.

    As unidades organizacionais da AWS nas quais serão atualizadas as instâncias de pilha associadas.

    Você pode fornecer IDs de unidade organizacional como uma lista literal ou um caminho de arquivo.

    • Literal: insira uma matriz de strings separadas por vírgulas, conforme mostrado no exemplo a seguir.

      ou-examplerootid111-exampleouid111,ou-examplerootid222-exampleouid222

    • Caminho do arquivo: o local do arquivo que contém uma lista de OrganizationalUnitIds nas quais serão criadas ou atualizadas instâncias de conjunto de pilhas. Se você usar o caminho do arquivo para especificar accounts ou OrganizationalUnitIds, o formato do arquivo deverá estar em JSON, conforme mostrado no exemplo a seguir.

      Insira um caminho para o arquivo no formato InputArtifactName::OrganizationalUnitIdsFileName.

      SourceArtifact::OU-IDs.txt

      O exemplo a seguir mostra o conteúdo do arquivo OU-IDs.txt:

      [
    "ou-examplerootid111-exampleouid111","ou-examplerootid222-exampleouid222"
]
Regiões

Obrigatório: sim

nota

Quando este parâmetro é selecionado, você também deve selecionar DeploymentTargets.

Uma lista das regiões da AWS em que as instâncias de conjunto de pilhas são criadas ou atualizadas. As regiões são atualizadas na ordem em que são inseridas.

Insira uma lista de regiões da AWS válidas no formato: Region1,Region2, conforme mostrado no exemplo a seguir.

us-west-2,us-east-1
ParameterOverrides

Obrigatório: não

Uma lista de parâmetros de conjunto de pilhas que você deseja substituir nas instâncias de pilha selecionadas. Os valores de parâmetros substituídos são aplicados a todas as instâncias da pilha nas contas e regiões especificadas.

Você pode fornecer parâmetros como uma lista literal ou um caminho de arquivo:

  • Você pode inserir parâmetros no seguinte formato de sintaxe abreviada: ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string. Para obter mais informações sobre tipos de dados, consulte Tipos de dados de parâmetro do modelo.

    O exemplo a seguir mostra um parâmetro chamado BucketName com o valor my-bucket.

    ParameterKey=BucketName,ParameterValue=my-bucket

    O exemplo a seguir mostra uma entrada com vários parâmetros.

                                                                                                          
  ParameterKey=BucketName,ParameterValue=my-bucket
  ParameterKey=Asset1,ParameterValue=true              
  ParameterKey=Asset2,ParameterValue=true

  • Você pode inserir o local do arquivo que contém uma lista de substituições de parâmetros de modelo inseridas no formato InputArtifactName::ParameterOverridessFileName, conforme mostrado no exemplo a seguir.

    SourceArtifact::parameter-overrides.txt

    O exemplo a seguir mostra o conteúdo do arquivo parameter-overrides.txt.

    [
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    },
    {
        "ParameterKey": "KeyName",
        "ParameterValue": "true"
    }
]
FailureTolerancePercentage

Obrigatório: não

A porcentagem de contas, por região, em que essa operação de pilha pode falhar antes que o AWS CloudFormation interrompa a operação nessa região. Se a operação for interrompida em uma região, o AWS CloudFormation não tentará a operação nas regiões subsequentes. Ao calcular o número de contas com base na porcentagem especificada, o AWS CloudFormation arredonda para o número inteiro anterior.

MaxConcurrentPercentage

Obrigatório: não

A porcentagem máxima de contas em que essa operação será executada em cada momento. Ao calcular o número de contas com base na porcentagem especificada, o AWS CloudFormation arredonda para o número inteiro anterior. Se o arredondamento para baixo resultar em zero, o AWS CloudFormation definirá o número como um. Embora você especifique o máximo, nas grandes implantações, o número real de contas utilizadas simultaneamente pode ser menor devido ao controle de utilização do serviço.

RegionConcurrencyType

Obrigatório: não

Você pode especificar se o conjunto de pilhas deve ser implantado entre Regiões da AWS sequencial ou paralelamente, configurando o parâmetro de implantação simultânea da região. Quando a simultaneidade da região é especificada para implantar pilhas em várias Regiões da AWS paralelamente, isso pode resultar tempos gerais de implantação mais rápidos.

  • Em paralelo: as implantações de conjuntos de pilhas serão conduzidas simultaneamente, desde que as falhas de implantação de uma região não excedam uma tolerância a falhas especificada.

  • Sequencial: as implantações de conjuntos de pilhas serão conduzidas uma de cada vez, desde que as falhas de implantação de uma região não excedam uma tolerância a falhas especificada. A implantação sequencial é a seleção padrão.

ConcurrencyMode

Obrigatório: não

O modo de simultaneidade permite escolher como o nível de simultaneidade se comporta durante as operações de conjunto de pilhas, seja com tolerância da falhas estrita ou moderada. A Alta tolerância a falhas reduz a velocidade de implantação à medida que ocorrem falhas na operação do conjunto de pilhas porque a simultaneidade diminui para cada falha. A Tolerância moderada a falhas prioriza a velocidade de implantação e, ao mesmo tempo, aproveita os recursos de segurança do AWS CloudFormation.

  • STRICT_FAILURE_TOLERANCE: essa opção reduz dinamicamente o nível de simultaneidade para garantir que o número de contas com falha nunca exceda uma tolerância a falhas específica. Esse é o comportamento padrão.

  • SOFT_FAILURE_TOLERANCE: essa opção desacopla a tolerância a falhas da simultaneidade real. Isso permite que as operações de conjunto de pilhas em um nível de simultaneidade definido, independentemente do número de falhas.

Input artifacts (Artefatos de entrada)

CloudFormationStackInstances pode conter artefatos que listam destinos e parâmetros de implantação.

  • Número de artefatos: 0 to 2

  • Descrição: como entrada, a ação do conjunto de pilhas aceita opcionalmente artefatos para as seguintes finalidades:

    • Para fornecer o arquivo de parâmetros a ser usado. (Consulte o parâmetro ParameterOverrides.)

    • Para fornecer o arquivo de contas de destino a ser usado. (Consulte o parâmetro DeploymentTargets.)

Artefatos de saída

  • Número de artefatos: 0

  • Descrição: os artefatos de saída não se aplicam a esse tipo de ação.

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.

  • StackSetId: o ID do conjunto de pilhas.

  • OperationId: o ID da operação de conjunto de pilhas.

Para obter mais informações, consulte Variáveis.

Exemplo de configuração da ação

Os exemplos a seguir mostram a configuração da ação CloudFormationStackInstances.

Exemplo do modelo de permissões autogerenciadas

O exemplo a seguir mostra uma ação CloudFormationStackInstances em que o destino de implantação inserido é um ID 111111222222 da Conta da AWS.

YAML
Name: my-instances
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackInstances
  Version: '1'
RunOrder: 2
Configuration:
  DeploymentTargets: '111111222222'
  Regions: 'us-east-1,us-east-2,us-west-1,us-west-2'
  StackSetName: my-stackset
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: us-west-2
JSON
{
    "Name": "my-instances",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackInstances",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "DeploymentTargets": "111111222222",
        "Regions": "us-east-1,us-east-2,us-west-1,us-west-2",
        "StackSetName": "my-stackset"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "us-west-2"
}

Exemplo do modelo de permissões autogerenciadas

O exemplo a seguir mostra uma ação CloudFormationStackInstances para o modelo de permissões gerenciadas por serviços em que o destino da implantação é um ID de unidade organizacional ou-1111-1example do AWS Organizations.

YAML
Name: Instances
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormationStackInstances
  Version: '1'
RunOrder: 2
Configuration:
  DeploymentTargets: ou-1111-1example
  Regions: us-east-1
  StackSetName: my-stackset
OutputArtifacts: []
InputArtifacts:
  - Name: SourceArtifact
Region: eu-central-1
JSON
{
    "Name": "Instances",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormationStackInstances",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "DeploymentTargets": "ou-1111-1example",
        "Regions": "us-east-1",
        "StackSetName": "my-stackset"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
            "Name": "SourceArtifact"
        }
    ],
    "Region": "eu-central-1"
}

Modelos de permissões para operações de conjuntos de pilhas

Como o AWS CloudFormation StackSets executa operações em várias contas, você deve definir as permissões necessárias nessas contas para que possa criar o conjunto de pilhas. Você pode definir permissões por meio de permissões autogerenciadas ou permissões gerenciadas por serviços.

Com permissões autogerenciadas, você cria os dois perfis do IAM exigidos pelos StackSets: um perfil de administrador, por exemplo, o AWSCloudFormationStacksetAdministrationRole, na conta em que você define o conjunto de pilhas, e um perfil de execução, por exemplo, o AWSCloudFormationStacksetExecutionRole, em cada uma das contas em que você implanta instâncias de conjunto de pilhas. Usando esse modelo de permissões, o StackSets pode implantar em qualquer conta da AWS na qual o usuário tenha permissões para criar um perfil do IAM. Para obter mais informações, consulte Conceder permissões autogerenciadas no Guia do usuário do AWS CloudFormation.

nota

Como o AWS CloudFormation StackSets executa operações em várias contas, você deve definir as permissões necessárias nessas contas para que possa criar o conjunto de pilhas.

Com permissões gerenciadas por serviços, você pode implantar instâncias de pilha em contas gerenciadas pelo AWS Organizations. Usando esse modelo de permissões, você não precisa criar os perfis do IAM necessários porque o StackSets cria perfis do IAM em seu nome. Com esse modelo, você também pode habilitar implantações automáticas em contas que serão adicionadas à sua organização no futuro. Consulte Habilitar o acesso confiável com o AWS Organizations no Guia do usuário do AWS CloudFormation.

Tipos de dados de parâmetro do modelo

Os parâmetros do modelo usados nas operações de conjunto de pilhas incluem os seguintes tipos de dados. Para obter mais informações, consulte DescribeStackSet.

ParameterKey

  • Descrição: a chave associada ao parâmetro. Se você não especificar uma chave e um valor para um parâmetro específico, o AWS CloudFormation usará o valor padrão especificado no modelo.

  • Exemplo:

    "ParameterKey=BucketName,ParameterValue=my-bucket"
ParameterValue

  • Descrição: o valor de entrada associado ao parâmetro.

  • Exemplo:

    "ParameterKey=BucketName,ParameterValue=my-bucket"
UsePreviousValue

  • Durante uma atualização da pilha, use o valor do parâmetro existente que a pilha está usando para uma determinada chave de parâmetro. Se você especificar true, não especifique um valor de parâmetro.

  • Exemplo:

    "ParameterKey=Asset1,UsePreviousValue=true"

Cada conjunto de pilhas tem um modelo e um conjunto de parâmetros de modelo. Ao atualizar o modelo ou os parâmetros do modelo, você os atualiza para todo o conjunto. Em seguida, todos os status de instância são definidos como OUTDATED até que as alterações sejam implantadas nessa instância.

Para substituir valores de parâmetros em instâncias específicas, por exemplo, se o modelo contiver um parâmetro para stage com um valor prod, você poderá substituir o valor desse parâmetro para que seja beta ou gamma.

Os recursos relacionados a seguir podem ajudar você à medida que trabalha com esta ação.

  • Tipos de parâmetro: este capítulo de referência no Guia do usuário do AWS CloudFormation fornece mais descrições e exemplos dos parâmetros do modelo CloudFormation.

  • Práticas recomendadas: para obter mais informações sobre as práticas recomendadas para implantar conjuntos de pilhas, consulte https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html no Guia do usuário do AWS CloudFormation.

  • Referência de API do AWS CloudFormation: você pode fazer referência às seguintes ações do CloudFormation na Referência de API do AWS CloudFormation para obter mais informações sobre os parâmetros usados nas operações de conjunto de pilhas:

    • A ação CreateStackSet cria um conjunto de pilhas.

    • A ação UpdateStackSet atualiza o conjunto de pilhas e as instâncias de pilha associadas nas contas e regiões especificadas. Mesmo que a operação de conjunto de pilhas criada pela atualização do conjunto de pilhas falhe (total ou parcialmente, abaixo ou acima de uma tolerância a falhas especificada), o conjunto de pilhas será atualizado com essas alterações. As chamadas subsequentes de CreateStackInstances no conjunto de pilhas especificado usam o conjunto de pilhas atualizado.

    • A ação CreateStackInstances cria uma instância de pilha para todas as regiões especificadas em todas as contas especificadas em um modelo de permissão autogerenciado ou em todos os destinos de implantação especificados em um modelo de permissão gerenciado por serviços. Você pode substituir os parâmetros das instâncias criadas por essa ação. Se as instâncias já existirem, CreateStackInstances chamará UpdateStackInstances com os mesmos parâmetros de entrada. Quando você usa essa ação para criar instâncias, ela não altera o status de outras instâncias de pilha.

    • A ação CreateStackInstances atualiza as instâncias de pilha com base no conjunto de pilhas de todas as regiões especificadas em todas as contas especificadas em um modelo de permissões autogerenciados ou em todos os destinos de implantação especificados em um modelo de permissão gerenciado por serviços. Você pode substituir os parâmetros das instâncias atualizadas por essa ação. Quando você usa essa ação para criar um subconjunto de instâncias, ela não altera o status de outras instâncias de pilha.

    • A ação DescribeStackSetOperation retorna a descrição da operação do conjunto de pilhas especificado.

    • A ação DescribeStackSet retorna a descrição da operação do conjunto de pilhas especificado.