Solução de problemas com o AWS CloudFormation StackSets - AWS CloudFormation
Motivos comuns de falha na operação da pilhaRealizar novamente operações de criação ou atualização de pilha com falhaFalha de exclusão de instância de pilhaFalha na operação de importação de pilhasContagem de falhas de instâncias de pilha para operações do StackSets

Solução de problemas com o AWS CloudFormation StackSets

Este tópico contém alguns problemas comuns do AWS CloudFormation StackSets e soluções sugeridas para esses problemas.

Motivos comuns de falha na operação da pilha

Problema: uma operação de pilha falhou, e o status da instância de pilha é OUTDATED.

Causa: pode haver várias causas comuns para a falha na operação da pilha.

  • Permissões insuficientes em uma conta de destino para criar recursos especificados no seu modelo.

  • O modelo do AWS CloudFormation pode conter erros. Valide o modelo no AWS CloudFormation e corrija os erros antes de tentar criar seu conjunto de pilhas.

  • O modelo pode estar tentando criar recursos globais que precisam ser únicos, mas não são. Por exemplo, os buckets do S3.

  • Não existe um número de conta de destino especificado. Verifique os números da conta de destino que você especificou na página Definir opções de implantação do assistente.

  • A conta de administrador não possui uma relação de confiança com a conta de destino.

  • A quantidade máxima especificada para um recurso no seu modelo já existe na sua conta de destino. Por exemplo, você pode ter atingido o limite de permitido de funções IAM em uma conta de destino, mas o modelo cria mais funções IAM.

  • Você atingiu a quantidade máxima permitida de pilhas em um conjunto de pilhas. Consulte Limites do AWS CloudFormation para saber o número máximo de pilhas por conjunto de pilhas.

Solução: Para obter mais informações sobre as permissões necessárias das contas de destino e administrador antes de criar conjuntos de pilhas, consulte Definir permissões básicas para operações de conjuntos de pilhas Definir permissões para todos os usuários da conta de administrador para executar operações do conjunto de pilhas em todas as contas de destino.

Realizar novamente operações de criação ou atualização de pilha com falha

Problema: uma operação de criação ou atualização de pilha falhou, e o status da instância de pilha é OUTDATED. Para saber o motivo da falha de uma tentativa de criação ou atualização de pilha, abra o console do AWS CloudFormation e veja os eventos da pilha, que terão um status DELETED (para operações de criação com falha) ou FAILED (para operações de atualização com falha). Navegue pelos eventos de pilha e localize a coluna Motivo do status. O valor de Motivo do status explica o motivo da falha na operação.

Depois de corrigir a causa subjacente da falha na criação da pilha, você poderá tentar realizar a criação da pilha novamente. Para isso, execute as etapas a seguir.

Solução: execute as seguintes etapas para tentar realizar a operação da pilha novamente.

  1. No console, selecione o conjunto de pilhas que contém a pilha na qual a operação falhou.

  2. No menu Actions (Ações), escolha Edit StackSet details (Editar detalhes do StackSet) para tentar criar ou atualizar as pilhas novamente.

  3. Na página Specify template (Especificar modelo), mantenha a opção padrão Use current template (Usar modelo atual) para usar o mesmo modelo do AWS CloudFormation. Se sua operação de pilha falhou porque o modelo necessário foi alterado e você deseja enviar um modelo revisado, escolha Carregar um modelo no Amazon S3 e, em seguida, Procurar para selecionar o modelo atualizado. Quando você terminar de carregar do modelo revisado, escolha Próximo.

  4. Na página Especificar detalhes, escolha Próximo se você não estiver alterando nenhum parâmetro específico do seu modelo.

  5. Na página Definir opções de implantação, altere os padrões para Máximo de contas simultâneas e Tolerância a falhas, se desejar. Para ter mais informações sobre essas configurações, consulte Opções de operação do conjunto de pilhas.

  6. Na página Revisão, revise suas seleções e marque a caixa de seleção para confirmar os recursos do IAM necessários. Selecione Submit (Enviar).

  7. Se sua pilha não for atualizada com êxito, repita este procedimento depois de ter resolvido todos os problemas subjacentes que estejam impedindo a criação de pilhas.

Falha de exclusão de instância de pilha

Problema: houve uma falha de exclusão de pilha.

Causa: a exclusão de pilha falhará para as pilhas em que a proteção contra encerramento foi ativada.

Solução: determine se a proteção contra encerramento foi ativada para a pilha. Caso tenha sido, desative a proteção contra encerramento e, em seguida, execute a exclusão de instância de pilha novamente.

Falha na operação de importação de pilhas

Problema: uma operação de importação de pilhas falha ao importar pilhas existentes para conjuntos de pilhas novos ou existentes. A instância da pilha está em um status INOPERABLE.

Solução: reverta a operação de importação de pilhas, concluindo as seguintes tarefas.

  1. Use a opção Delete Stacks from StackSets (Excluir pilhas do StackSets), habilite RetainStacks durante a configuração e depois exclua instâncias de pilha do seu conjunto de pilhas. Para saber mais, consulte Excluir instâncias de pilhas do seu conjunto de pilhas.

  2. Você verá que a instância da pilha do Stackset é atualizada para remover a instância da pilha INOPERABLE.

  3. Corrija as instâncias da pilha de acordo com o erro de falha na importação e repita a operação de importação da pilha.

Contagem de falhas de instâncias de pilha para operações do StackSets

A contagem de falhas de instâncias de pilha alerta você se houver falha no provisionamento ou na atualização de instâncias de pilha. Essas instâncias da pilha não foram implantados por um ou mais dos seguintes motivos:

  • Recursos existentes com uma configuração semelhante

  • Dependências ausentes, como perfis do AWS Identity and Access Management (IAM)

  • Outros fatores conflitantes

Se você quiser implantar com o máximo de simultaneidade, a contagem máxima de simultaneidade é uma mais do que a contagem de tolerância a falhas. Por exemplo, se a contagem de tolerância a falhas for 9, a contagem máxima de simultaneidade não poderá ser maior que 10. Isso fará com que a operação retorne SUCCEEDED mesmo se houver falha algumas na atualização de algumas instâncias de pilha. A nova contagem de falhas de instâncias de pilha permite que você determine se a operação só foi bem-sucedida condicionalmente porque a contagem de tolerância a falhas está definida para permitir todas as falhas.

Você pode usar o AWS Management Console, o AWS SDK ou a AWS CLI para obter a contagem de falhas e filtrar as instâncias de pilha para determinar quais instâncias precisam ser reimplantadas.

Usar o console

Para ver o número de instâncias de pilha em que houve falha:

  1. Abra o console do AWS CloudFormation e escolha StackSets.

  2. Escolha o StackSet e depois a guia Operations (Operações).

  3. Escolha um status na coluna Status para visualizar detalhes do status. Você encontrará o número de instâncias de pilha em que houve falha para uma determinada operação nos detalhes do status.

Para visualizar a conta, a região e o status das instâncias de pilha para a operação:

  1. Nos detalhes do status, escolha a contagem das instâncias de pilha em que houve falha. Exemplo: instâncias de pilha: <number of failed stack instances>.

  2. Expanda o painel lateral escolhendo o cabeçalho do painel. Os resultados no painel lateral são os status das instâncias de pilha após a conclusão da operação selecionada.

Para ver os detalhes da instância de pilha atual para uma operação:

  1. Escolha a guia Stack Instances (Instâncias de pilha).

  2. Filtre por Last operation ID (ID da última operação). Os resultados são os status atuais e os motivos dos status da última operação a modificar a instância. É possível usar esse filtro em combinação com Conta da AWS, Região da AWS, Status detalhado e Status de desvio para refinar ainda mais os resultados da pesquisa.

Usar a AWS CLI

Para obter o número de instâncias de pilha em que houve falha, chame describe-stack-set-operation ou list-stack-set-operations e consulte StatusDetails.

$ aws cloudformation describe-stack-set-operation --stack-set-name ss1 \
    --operation-id 5550e62f-c822-4331-88fa-21c1d7bafc60
{
    "StackSetOperation": {
        "OperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60",
        "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
        "Action": "CREATE",
        "Status": "SUCCEEDED",
        "OperationPreferences": {
            "RegionOrder": [],
            "FailureToleranceCount": 10,
            "MaxConcurrentCount": 10
        },
        "AdministrationRoleARN": "arn:aws:iam::123456789012:role/AWSCloudFormationStackSetAdministrationRole",
        "ExecutionRoleName": "AWSCloudFormationStackSetExecutionRole",
        "CreationTimestamp": "2022-10-26T17:18:53.947000+00:00",
        "EndTimestamp": "2022-10-26T17:19:35.304000+00:00",
        "StatusDetails": {
            "FailedStackInstancesCount": 3
        }
    }
}
aws cloudformation list-stack-set-operations --stack-set-name ss1
{
    "Summaries": [
        {
            "OperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60",
            "Action": "CREATE",
            "Status": "SUCCEEDED",
            "CreationTimestamp": "2022-10-26T17:18:53.947000+00:00",
            "EndTimestamp": "2022-10-26T17:19:35.304000+00:00",
            "StatusDetails": {
                "FailedStackInstancesCount": 3
            },
            "OperationPreferences": {
                "RegionOrder": [],
                "FailureToleranceCount": 10,
                "MaxConcurrentCount": 10
            }
        }
    ]
}

Para obter uma visão geral histórica de uma determinada operação, use list-stack-set-operation-results para visualizar o status e o motivo do status de cada instância de pilha após a conclusão da operação. Veja Status e StatusReason no seguinte exemplo:

aws cloudformation list-stack-set-operation-results --stack-set-name ss1 --operation-id 5550e62f-c822-4331-88fa-21c1d7bafc60 --filters Name=OPERATION_RESULT_STATUS,Values=FAILED
{
    "Summaries": [
        {
            "Account": "123456789012",
            "Region": "us-west-2",
            "Status": "FAILED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "AccountGateResult": {
                "Status": "SKIPPED",
                "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."
            },
            "OrganizationalUnitId": ""
        },
        {
            "Account": "123456789012",
            "Region": "us-west-1",
            "Status": "FAILED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "AccountGateResult": {
                "Status": "SKIPPED",
                "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."
            },
            "OrganizationalUnitId": ""
        },
        {
            "Account": "123456789012",
            "Region": "us-east-1",
            "Status": "FAILED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "AccountGateResult": {
                "Status": "SKIPPED",
                "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."
            },
            "OrganizationalUnitId": ""
        }
    ]
}

Use list-stack-instances com os filtros DETAILED_STATUS e LAST_OPERATION_ID para obter uma lista das instâncias de pilha em que houve falha na última operação que tentou implantar a instância de pilha. Veja o sinalizador --filters no exemplo com DETAILED_STATUS e LAST_OPERATION_ID:

aws cloudformation list-stack-instances --stack-set-name ss1 --filters Name=DETAILED_STATUS,Values=FAILED Name=LAST_OPERATION_ID,Values=5550e62f-c822-4331-88fa-21c1d7bafc60
{
    "Summaries": [
        {
            "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
            "Region": "us-east-1",
            "Account": "123456789012",
            "Status": "OUTDATED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "StackInstanceStatus": {
                "DetailedStatus": "FAILED"
            },
            "OrganizationalUnitId": "",
            "DriftStatus": "NOT_CHECKED",
            "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
        },
        {
            "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
            "Region": "us-west-1",
            "Account": "123456789012",
            "Status": "OUTDATED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "StackInstanceStatus": {
                "DetailedStatus": "FAILED"
            },
            "OrganizationalUnitId": "",
            "DriftStatus": "NOT_CHECKED",
            "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
        },
        {
            "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
            "Region": "us-west-2",
            "Account": "123456789012",
            "Status": "OUTDATED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "StackInstanceStatus": {
                "DetailedStatus": "FAILED"
            },
            "OrganizationalUnitId": "",
            "DriftStatus": "NOT_CHECKED",
            "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
        }
    ]
}

Para encontrar o ID da última operação para modificar uma instância de pilha, use list-stack-instances ou describe-stack-instance para obter o LastOperationId:

aws cloudformation describe-stack-instance --stack-set-name ss1 --stack-instance-account 123456789012 --stack-instance-region us-east-2
{
    "StackInstance": {
        "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
        "Region": "us-west-2",
        "Account": "123456789012",
        "ParameterOverrides": [],
        "Status": "OUTDATED",
        "StackInstanceStatus": {
            "DetailedStatus": "FAILED"
        },
        "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
        "OrganizationalUnitId": "",
        "DriftStatus": "NOT_CHECKED",
        "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
    }
}