AWS CloudFormation StackSets referência de ação de implantação - AWS CodePipeline
Como AWS CloudFormation StackSets as ações funcionam Como estruturar StackSets ações em um pipelineA ação CloudFormationStackSetA CloudFormationStackInstances açãoModelos 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 referência de ação de implantação

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

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

Você integra seu pipeline por AWS CloudFormation StackSets meio de dois tipos de ação distintos que você usa juntos:

  • 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ções 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.

Você pode usar essas ações para implantar em AWS contas de destino ou na unidade organizacional da AWS Organizations de destinoIDs.

nota

Para implantar em contas ou unidades organizacionais de AWS organizações de destino IDs e usar o modelo de permissões gerenciadas por serviços, você deve habilitar o acesso confiável entre e AWS CloudFormation StackSets Organizations AWS . Para obter mais informações, consulte Habilitar o acesso confiável com AWS CloudFormation Stacksets.

Como AWS CloudFormation StackSets as ações 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 CloudFormationStackSetação cria o conjunto de pilhas sem criar nenhuma instância.

  • Atualização: quando a CloudFormationStackSetação é 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 um OUTDATED status.

    Você pode usar a CloudFormationStackSetação para atualizar o conjunto de pilhas das seguintes maneiras.

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

    • Atue como administrador delegado em uma conta de membro 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 StackSets ações 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 o CLI para criar a estrutura de pipeline recomendada da seguinte forma:

  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 alvos 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 um status. OUTDATED Por exemplo, para a atualização da instância de pilha para a conta Account-A em que a us-east-2 região é removida da configuração da ação, as instâncias de pilha restantes são criadas e a instância removida é definida da seguinte OUTDATED forma:

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 melhores práticas para implantar conjuntos de pilhas, consulte Práticas recomendadas StackSets no Guia do AWS CloudFormation usuário.

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 AWS região, não poderá acessá-lo de 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 nomeado BucketName com o valoramzn-s3-demo-source-bucket.

    ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket

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

                                                                                                          
  ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-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 IAM recursos em seu modelo de pilha ou criar uma pilha diretamente de um modelo contendo macros. Para que a AWS CloudFormation ação 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 CloudFormationStackSetação mostra uma entrada com vários recursos.

PermissionModel

Obrigatório: Não

Determina como as IAM funções são criadas e gerenciadas. Se o campo não for especificado, o padrão será usado. Para ter 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: cria AWS CloudFormation StackSets automaticamente as IAM funções necessárias para implantação em contas gerenciadas por 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 AWS CloudFormation StackSets executa operações em várias contas, você deve definir as permissões necessárias nessas contas antes de criar o conjunto de pilhas.

Obrigatório: Não

nota

Esse parâmetro é opcional para o modelo SELF _ MANAGED permissions e não é usado para o modelo SERVICE _ MANAGED permissions.

A ARN IAM função 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 da função, ela será definida como AWSCloudFormationStackSetAdministrationRole. Se você especificar ServiceManaged, não deverá definir um nome de função.

ExecutionRoleName
nota

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

Obrigatório: Não

nota

Esse parâmetro é opcional para o modelo SELF _ MANAGED permissions e não é usado para o modelo SERVICE _ MANAGED permissions.

O nome da IAM função nas contas de destino 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 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

Esse parâmetro é opcional para o modelo SERVICE _ MANAGED permissions e não é usado para o modelo SELF _ MANAGED permissions.

Descreve se é implantado AWS CloudFormation StackSets automaticamente em AWS Organizations contas que são adicionadas a uma organização ou unidade organizacional (OU) 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.

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

  • Disabled. Obrigatório: Não.

    StackSets não implanta automaticamente instâncias de pilha adicionais em contas de AWS Organizations que são adicionadas a uma organização ou unidade organizacional (OU) 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 MANAGED permissões SERVICE _, você pode fornecer o ID raiz da organização ou a unidade organizacional IDs para destinos de implantação. Para o modelo de MANAGED permissões SELF _, você só pode fornecer contas.

nota

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

Uma lista de AWS contas ou unidades organizacionais em IDs que as instâncias do 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: a localização do arquivo contendo uma lista de AWS contas em que as instâncias do conjunto de pilhas devem ser criadas/atualizadas, inserida no formato. InputArtifactName::AccountsFileName Se você usar o caminho do arquivo para especificar contas ou OrganizationalUnitIds, o formato do arquivo deverá estar emJSON, 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

    Esse parâmetro é opcional para o modelo SERVICE _ MANAGED permissions e não é usado para o modelo SELF _ MANAGED permissions. Não use isso se você selecionar OrganizationsAutoDeployment.

    As unidades AWS organizacionais nas quais atualizar as instâncias de pilha associadas.

    Você pode fornecer a unidade organizacional IDs 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 onde criar ou atualizar instâncias do conjunto de pilhas. Se você usar o caminho do arquivo para especificar contas ou OrganizationalUnitIds, o formato do arquivo deverá estar emJSON, 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 esse parâmetro é selecionado, você também deve selecionar DeploymentTargets.

Uma lista das AWS regiões em que as instâncias do 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 AWS regiões válidas no formatoRegion1,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 nas quais essa operação de pilha pode falhar antes de AWS CloudFormation interromper a operação nessa região. Se a operação for interrompida em uma região, AWS CloudFormation não tente a operação nas regiões subsequentes. Ao calcular o número de contas com base na porcentagem especificada, AWS CloudFormation arredonda para baixo para o próximo número inteiro.

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, AWS CloudFormation arredonda para baixo para o próximo número inteiro. Se o arredondamento para baixo resultar em zero, AWS CloudFormation defina 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 em Regiões da AWS paralelo, isso pode resultar em 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. O Soft Failure Tolerance prioriza a velocidade de implantação e, ao mesmo tempo, aproveita AWS CloudFormation os recursos de segurança.

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

CallAs

Obrigatório: Não

nota

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

Especifica se você está atuando na conta de gerenciamento da organização ou como administrador delegado em uma conta de membro.

nota

Se esse parâmetro estiver definido comoDELEGATED_ADMIN, certifique-se de que a IAM função do pipeline tenha organizations:ListDelegatedAdministrators permissão. Caso contrário, a ação falhará durante a execução com um erro semelhante ao seguinte:Account used is not a delegated administrator.

  • SELF: a implantação do conjunto de pilhas usará permissões gerenciadas pelo serviço enquanto estiver conectado à conta de gerenciamento.

  • DELEGATED_ADMIN: a implantação do Stack Set usará permissões gerenciadas pelo serviço enquanto estiver conectado a uma conta de administrador delegado.

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 do conjunto de pilhas.

Para obter mais informações, consulte Referência de variáveis.

Exemplo de configuração de CloudFormationStackSetação

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

Exemplo do modelo de permissões autogerenciadas

O exemplo a seguir mostra uma CloudFormationStackSetação em que a meta de implantação inserida é uma ID de AWS conta.

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 CloudFormationStackSetação para o modelo de permissões gerenciadas por serviços em que a opção de implantação automática em 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 CloudFormationStackInstances ação

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 MANAGED permissões SERVICE _, você pode fornecer o ID raiz da organização ou a unidade organizacional IDs para destinos de implantação. Para o modelo de MANAGED permissões SELF _, você só pode fornecer contas.

nota

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

Uma lista de AWS contas ou unidades organizacionais em IDs que as instâncias do 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: a localização do arquivo contendo uma lista de AWS contas em que as instâncias do conjunto de pilhas devem ser criadas/atualizadas, inserida no formato. InputArtifactName::AccountsFileName Se você usar o caminho do arquivo para especificar contas ou OrganizationalUnitIds, o formato do arquivo deverá estar emJSON, 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

    Esse parâmetro é opcional para o modelo SERVICE _ MANAGED permissions e não é usado para o modelo SELF _ MANAGED permissions. Não use isso se você selecionar OrganizationsAutoDeployment.

    As unidades AWS organizacionais nas quais atualizar as instâncias de pilha associadas.

    Você pode fornecer a unidade organizacional IDs 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 onde criar ou atualizar instâncias do conjunto de pilhas. Se você usar o caminho do arquivo para especificar contas ou OrganizationalUnitIds, o formato do arquivo deverá estar emJSON, 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 esse parâmetro é selecionado, você também deve selecionar DeploymentTargets.

Uma lista das AWS regiões em que as instâncias do 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 AWS regiões 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 nomeado BucketName com o valoramzn-s3-demo-source-bucket.

    ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket

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

                                                                                                          
  ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-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 nas quais essa operação de pilha pode falhar antes de AWS CloudFormation interromper a operação nessa região. Se a operação for interrompida em uma região, AWS CloudFormation não tente a operação nas regiões subsequentes. Ao calcular o número de contas com base na porcentagem especificada, AWS CloudFormation arredonda para baixo para o próximo número inteiro.

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, AWS CloudFormation arredonda para baixo para o próximo número inteiro. Se o arredondamento para baixo resultar em zero, AWS CloudFormation defina 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 em Regiões da AWS paralelo, isso pode resultar em 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. O Soft Failure Tolerance prioriza a velocidade de implantação e, ao mesmo tempo, aproveita AWS CloudFormation os recursos de segurança.

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

CallAs

Obrigatório: Não

nota

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

Especifica se você está atuando na conta de gerenciamento da organização ou como administrador delegado em uma conta de membro.

nota

Se esse parâmetro estiver definido comoDELEGATED_ADMIN, certifique-se de que a IAM função do pipeline tenha organizations:ListDelegatedAdministrators permissão. Caso contrário, a ação falhará durante a execução com um erro semelhante ao seguinte:Account used is not a delegated administrator.

  • SELF: a implantação do conjunto de pilhas usará permissões gerenciadas pelo serviço enquanto estiver conectado à conta de gerenciamento.

  • DELEGATED_ADMIN: a implantação do Stack Set usará permissões gerenciadas pelo serviço enquanto estiver conectado a uma conta de administrador delegado.

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 do conjunto de pilhas.

Para obter mais informações, consulte Referência de variáveis.

Exemplo de configuração da ação

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

Exemplo do modelo de permissões autogerenciadas

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

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 CloudFormationStackInstancesação para o modelo de permissões gerenciadas por serviços em que o destino da implantação é uma ID da unidade organizacional da AWS Organizations. ou-1111-1example

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 AWS CloudFormation StackSets executa operações em várias contas, você deve definir as permissões necessárias nessas contas antes de criar o conjunto de pilhas. Você pode definir permissões por meio de permissões autogerenciadas ou permissões gerenciadas por serviços.

Com as permissões autogerenciadas, você cria as duas IAM funções exigidas por StackSets : uma função de administrador, como a da conta AWSCloudFormationStackSetAdministrationRole em que você define o conjunto de pilhas, e uma função de execução, como a de cada uma das contas AWSCloudFormationStackSetExecutionRole em que você implanta instâncias do conjunto de pilhas. Usando esse modelo de permissões, StackSets pode implantar em qualquer AWS conta na qual o usuário tenha permissões para criar uma IAM função. Para obter mais informações, consulte Conceder permissões autogerenciadas no Guia do usuário do AWS CloudFormation .

nota

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

Com permissões gerenciadas por serviços, você pode implantar instâncias de pilha em contas gerenciadas por Organizations. AWS Usando esse modelo de permissões, você não precisa criar as IAM funções necessárias porque StackSets cria as IAM funções 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 acesso confiável com AWS Organizations no Guia AWS CloudFormation do Usuário.

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 determinado parâmetro, AWS CloudFormation usa o valor padrão especificado no modelo.

  • Exemplo:

    "ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket"
ParameterValue

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

  • Exemplo:

    "ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-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 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.

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

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

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

  • AWS CloudFormation APIReferência — Você pode consultar as seguintes CloudFormation ações na AWS CloudFormation APIReferência para obter mais informações sobre os parâmetros usados nas operações de conjunto de pilhas:

    • A CreateStackSetação cria um conjunto de pilhas.

    • A UpdateStackSetação 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. CreateStackInstances As chamadas subsequentes no conjunto de pilhas especificado usam o conjunto de pilhas atualizado.

    • A CreateStackInstancesação 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ço. Você pode substituir os parâmetros das instâncias criadas por essa ação. Se as instâncias já existirem, CreateStackInstances chamadas 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 UpdateStackInstancesação atualiza as instâncias de pilha com a pilha definida 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 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 DescribeStackSetOperationação retorna a descrição da operação de conjunto de pilhas especificada.

    • A DescribeStackSetação retorna a descrição do conjunto de pilhas especificado.