Implementação do Account Factory for Terraform (AFT) usando um pipeline de bootstrap - Recomendações da AWS
ResumoPré-requisitos e limitaçõesArquiteturaFerramentasPráticas recomendadasÉpicosSolução de problemasRecursos relacionados

Implementação do Account Factory for Terraform (AFT) usando um pipeline de bootstrap

Vinicius Elias e Edgar Costa Filho, Amazon Web Services

Resumo

Aviso: o AWS CodeCommit não está mais disponível para novos clientes. Os clientes atuais do AWS CodeCommit podem continuar usando o serviço normalmente. Saiba mais

Este padrão fornece um método simples e seguro para implantar o AWS Control Tower Account Factory for Terraform (AFT) pela conta gerencial do AWS Organizations. O núcleo da solução é um modelo do CloudFormation que automatiza a configuração do AFT criando um pipeline do Terraform, que é estruturado para ser facilmente adaptável à implantação inicial ou às atualizações subsequentes.

A segurança e a integridade dos dados são as principais prioridades na AWS, portanto, o arquivo de estado do Terraform, que é um componente essencial que rastreia o estado da infraestrutura e das configurações gerenciadas, é armazenado com segurança em um bucket do Amazon Simple Storage Service (Amazon S3). Esse bucket é configurado com várias medidas de segurança, incluindo criptografia do lado do servidor e políticas para bloquear o acesso público, para ajudar a garantir que seu estado do Terraform seja protegido contra acesso não autorizado e violações de dados.

A conta gerencial orquestra e supervisiona todo o ambiente, portanto, é um recurso essencial no AWS Control Tower. Este padrão segue as práticas recomendadas da AWS e garante que o processo de implantação não seja apenas eficiente, mas também esteja alinhado aos padrões de segurança e governança, para oferecer uma maneira abrangente, segura e eficiente de implantar o AFT em seu ambiente da AWS.

Para obter mais informações sobre o AFT, consulte a documentação do AWS Control Tower.

Pré-requisitos e limitações

Pré-requisitos

  • Um ambiente básico da AWS de várias contas com, no mínimo, as seguintes contas: conta gerencial, conta de arquivamento de logs, conta de auditoria e uma conta adicional para gerenciamento dp AFT.

  • Um ambiente do AWS Control Tower estabelecido. A conta gerencial deve ser configurada adequadamente, pois o modelo do CloudFormation será implantado nela.

  • As permissões necessárias na conta gerencial da AWS. Você precisará de permissões suficientes para criar e gerenciar recursos, como buckets do S3, funções do AWS Lambda, perfis do AWS Identity and Access Management (IAM) e projetos do AWS CodePipeline.

  • Familiaridade com o Terraform. Compreender os principais conceitos e o fluxo de trabalho do Terraform é importante porque a implantação envolve a geração e o gerenciamento das configurações do Terraform.

Limitações

  • Esteja ciente das cotas de recursos da AWS em sua conta. A implantação pode criar vários recursos, e encontrar cotas de serviço pode impedir o processo de implantação.

  • O modelo foi desenvolvido para versões específicas do Terraform e Serviços da AWS. A atualização ou alteração de versões pode exigir modificações no modelo.

  • O modelo não é compatível com serviços de sistema de controle de versão (VCS) autogerenciado, como o GitHub Enterprise.

Versões do produto

  • Terraform versão 1.6.6 ou superior

  • AFT versão 1.11 ou posterior

Arquitetura

Pilha de tecnologias de destino

  • CloudFormation

  • AWS CodeBuild

  • AWS CodeCommit

  • AWS CodePipeline

  • Amazon EventBridge

  • IAM

  • AWS Lambda

  • Amazon S3

Arquitetura de destino

O diagrama a seguir ilustra a implementação discutida neste padrão.

Fluxo de trabalho para implementar o AFT usando um pipeline de bootstrap.

O fluxo de trabalho consiste em três tarefas principais: criar os recursos, gerar o conteúdo e executar o pipeline.

Criar os recursos

O modelo do CloudFormation fornecido com este padrão cria e configura todos os recursos necessários, dependendo dos parâmetros selecionados ao implantar o modelo. No mínimo, o modelo cria os seguintes recursos:

  • Um pipeline do CodePipeline para implementar o AFT

  • Um bucket do S3 para armazenar o arquivo de estado do Terraform associado à implementação do AFT

  • Dois projetos do CodeBuild para implementar o plano do Terraform e aplicar comandos em diferentes estágios do pipeline

  • Perfis do IAM para serviços CodeBuild e CodePipeline

  • Um segundo bucket do S3 para armazenar artefatos do runtime do pipeline

Dependendo do provedor de VCS selecionado (CodeCommit ou VCS externo), o modelo cria os recursos a seguir.

  • Para o CodeCommit:

    • Um repositório do CodeCommit para armazenar o código de bootstrap do AFT Terraform

    • Uma regra do EventBridge para capturar as alterações do repositório do CodeCommit na ramificação main

    • Outro perfil do IAM para a regra do EventBridge

  • Para qualquer outro provedor externo de VCS, como o GitHub:

    • Uma conexão do Conexões de código da AWS.

Além disso, quando você seleciona o CodeCommit como provedor de VCS, se você definir o parâmetro Generate AFT Files como true, o modelo cria esses recursos adicionais para gerar o conteúdo:

  • Um bucket do S3 para armazenar o conteúdo gerado e ser usado como fonte do repositório do CodeCommit

  • Uma função do Lambda para processar os parâmetros fornecidos e gerar o conteúdo apropriado

  • Uma função do IAM para executar a função do Lambda

  • Um recurso personalizado do CloudFormation que executa a função do Lambda quando o modelo é implantado

Gerar o conteúdo

Para gerar os arquivos de bootstrap do AFT e seu conteúdo, a solução usa uma função do Lambda e um bucket do S3. A função cria uma pasta no bucket e, em seguida, cria dois arquivos dentro da pasta: main.tf e backend.tf. A função também processa os parâmetros fornecidos do CloudFormation e preenche esses arquivos com código predefinido, substituindo os respectivos valores dos parâmetros.

Para ver o código usado como modelo para gerar os arquivos, consulte o repositório GitHub da solução. Basicamente, os arquivos são gerados da seguinte forma.

main.tf

module "aft" {
  source = "github.com/aws-ia/terraform-aws-control_tower_account_factory?ref=<aft_version>"

  # Required variables
  ct_management_account_id  = "<ct_management_account_id>"
  log_archive_account_id    = "<log_archive_account_id>"
  audit_account_id          = "<audit_account_id>"
  aft_management_account_id = "<aft_management_account_id>"
  ct_home_region            = "<ct_home_region>"

  # Optional variables
  tf_backend_secondary_region = "<tf_backend_secondary_region>"
  aft_metrics_reporting       = "<false|true>"

  # AFT Feature flags
  aft_feature_cloudtrail_data_events      = "<false|true>"
  aft_feature_enterprise_support          = "<false|true>"
  aft_feature_delete_default_vpcs_enabled = "<false|true>"

  # Terraform variables
  terraform_version      = "<terraform_version>"
  terraform_distribution = "<terraform_distribution>"

  # VCS variables (if you have chosen an external VCS)
  vcs_provider                                  = "<github|githubenterprise|gitlab|gitlabselfmanaged|bitbucket>"
  account_request_repo_name                     = "<org-name>/aft-account-request"
  account_customizations_repo_name              = "<org-name>/aft-account-customizations"
  account_provisioning_customizations_repo_name = "<org-name>/aft-account-provisioning-customizations"
  global_customizations_repo_name               = "<org-name>/aft-global-customizations"

}

backend.tf

terraform {
  backend "s3" {
    region = "<aft-main-region>"
    bucket = "<s3-bucket-name>"
    key    = "aft-setup.tfstate"
  }
}

Durante a criação do repositório do CodeCommit, se você definir o parâmetro Generate AFT Files como true, o modelo usará o bucket do S3 com o conteúdo gerado como a origem da ramificação main para preencher automaticamente o repositório.

Execução do pipeline

Depois que os recursos foram criados e os arquivos de bootstrap foram configurados, o pipeline é executado. O primeiro estágio (Origem) busca o código-fonte da ramificação principal do repositório e o segundo estágio (Compilação) executa o comando de plano do Terraform e gera os resultados a serem revisados. No terceiro estágio (Aprovação), o pipeline aguarda uma ação manual para aprovar ou rejeitar o último estágio (Implantação). No último estágio, o pipeline executa o comando apply do Terraform usando o resultado do comando plan anterior do Terraform como entrada. Finalmente, uma função entre contas e as permissões na conta gerencial são usadas para criar os recursos do AFT na conta gerencial do AFT.

nota

Se você selecionar um provedor de VCS externo, precisará autorizar a conexão com suas credenciais de provedor de VCS. Para concluir a configuração, siga as etapas em Update a pending connection na documentação do console do AWS Developer Tools.

Ferramentas

Serviços da AWS

  • O CloudFormation permite configurar recursos da AWS, provisioná-los de forma rápida e consistente, e administrá-los durante todo o ciclo de vida em diferentes regiões e Contas da AWS.

  • O AWS CodeBuild é um serviço de compilação totalmente gerenciado que permite compilar o código-fonte, realizar testes de unidade e produzir artefatos preparados para a implantação. 

  • O AWS CodeCommit é um serviço de controle de versão que ajuda no armazenamento e no gerenciamento de repositórios Git de forma privada, sem a necessidade de administrar o próprio sistema de controle de origem.

  • O AWS CodePipeline ajuda você a modelar e configurar rapidamente os diferentes estágios de uma versão de software, além de automatizar as etapas necessárias para a implantação contínua de alterações.

  • O Conexões de código da AWS permite que recursos e serviços da AWS, como o CodePipeline, se conectem a repositórios de código externos, como o GitHub.

  • O AWS Lambda é um serviço de computação que executa seu código em resposta a eventos e gerencia automaticamente os recursos de computação, fornecendo uma maneira rápida de criar uma aplicação moderna e sem servidor para produção.

  • O AWS SDK para Python (Boto3) é um kit de desenvolvimento de software que ajuda você a integrar sua aplicação, biblioteca ou script Python aos Serviços da AWS.

Outras ferramentas

  • O Terraform é uma ferramenta de infraestrutura como código (IaC) que permite criar, alterar e versionar a infraestrutura com segurança e eficiência. Isso inclui componentes de baixo nível, como instâncias de computação, armazenamento e rede, e componentes de alto nível, como entradas de DNS e recursos de SaaS.

  • O Python é uma linguagem de programação poderosa e fácil de aprender. Ele tem estruturas de dados de alto nível eficientes e fornece uma abordagem simples, mas eficaz, à programação orientada a objetos.

Repositório de código

O código para este padrão está disponível no repositório AFT bootstrap pipeline repository do GitHub.

Para o repositório oficial do AFT, consulte AWS Control TowerAccount Factory for Terraform no GitHub.

Práticas recomendadas

Ao implantar o AFT usando o modelo fornecido do CloudFormation, recomendamos que você siga as práticas recomendadas para ajudar a garantir uma implementação segura, eficiente e bem-sucedida. As principais diretrizes e recomendações para implementar e operar o AFT incluem o seguinte.

  • Análise completa dos parâmetros: analise e compreenda cuidadosamente cada parâmetro no modelo do CloudFormation. A definição correta dos parâmetros é crucial para a configuração e o funcionamento corretos do AFT.

  • Atualizações regulares do modelo: mantenha o modelo atualizado com os recursos da AWS e as versões do Terraform mais recentes. As atualizações regulares ajudam você a aproveitar as novas funcionalidades e manter a segurança.

  • Versionamento: especifique a versão do módulo do AFT e, se possível, realize testes em uma implantação separada do AFT.

  • Escopo: use o AFT apenas para implantar barreiras de proteção e personalizações para a infraestrutura. Não o use para implantar sua aplicação.

  • Análise de código e validação: o pipeline do AFT exige uma configuração do Terraform que tenha passado por análise de código e validação. Execute a análise de código, a validação e os testes antes de enviar a configuração para os repositórios do AFT.

  • Módulos do Terraform: desenvolva código do Terraform reutilizável como módulos e sempre especifique as versões do Terraform e do provedor da AWS de acordo com os requisitos da sua organização.

Épicos

TarefaDescriçãoHabilidades necessárias

Prepare o ambiente do AWS Control Tower.

Prepare e configure o AWS Control Tower em seu ambiente da AWS para garantir o gerenciamento centralizado e a governança das Contas da AWS. Para obter mais informações, consulte Getting started with AWS Control Tower na documentação do AWS Control Tower.

Administrador de nuvem

Crie a conta gerencial do AFT.

Use o AWS Control Tower Account Factory para criar uma nova Conta da AWS para servir como sua conta gerencial do AFT. Para obter mais informações, consulte Provision accounts with AWS Service Catalog Account Factory na documentação do AWS Control Tower.

Administrador de nuvem
TarefaDescriçãoHabilidades necessárias

Inicialize o modelo do CloudFormation.

Neste épico, você implanta o modelo do CloudFormation fornecido com essa solução para configurar o pipeline de bootstrap do AFT em sua conta gerencial da AWS. O pipeline implanta a solução AFT na conta gerencial do AFT que você configurou no épico anterior.

Etapa 1: abrir o console do CloudFormation

  • Faça login no Console de gerenciamento da AWS e abra o console do CloudFormation. Verifique se está operando na região principal correta do AWS Control Tower.

Etapa 2: criar uma nova pilha

  1. Selecione para criar uma nova pilha.

  2. Selecione a opção de fazer upload de um arquivo de modelo e carregue o modelo do CloudFormation fornecido com este padrão.

Etapa 3: configurar os parâmetros da pilha

  • VCS Provider: selecione o provedor do sistema de controle de versão (VCS) a ser usado. Você pode selecionar um VCS externo, como o GitHub, ou usar o CodeCommit se sua conta tiver permissão para usar o serviço.

  • Repository Name: especifique o nome do repositório para armazenar o módulo de bootstrap do AFT. Para provedores externos de VCS, use o caminho completo, incluindo o nome da organização (por exemplo, my-github-org/my-repo).

  • Branch Name: especifique a ramificação do repositório de origem.

  • CodeBuild Docker Image: escolha o arquivo a ser usado como imagem base do CodeBuild Docker.

  • Se você definir o provedor de VCS para uma opção diferente de CodeCommit, vá para a etapa 8.

Etapa 4: decidir sobre a geração de arquivos

  • Se você selecionou o CodeCommit como seu provedor de VCS, você pode usar o parâmetro Generate AFT Files para controlar a geração de arquivos de implantação padrão do AFT. Defina esse parâmetro como:

    • true para criar e armazenar automaticamente arquivos de implantação do AFT no repositório especificado.

    • false se quiser lidar manualmente com a criação do arquivo ou se já tiver os arquivos no lugar.

  • Se você selecionou false, vá para a etapa 8; caso contrário, siga primeiro as etapas 5 a 7.

Etapa 5: preencher os detalhes da conta do AFT no AWS Control Tower

  • Se você definir o parâmetro Generate AFT Files como true, forneça as informações específicas do AWS Control Tower e da conta do AFT a seguir.

    • Log Archive Account ID: o ID do ID da conta de arquivamento de logs em AWS Control Tower.

    • Audit Account ID: o ID da conta de auditoria em AWS Control Tower.

    • AFT Management Account ID: o ID da conta gerencial do AFT que você criou no primeiro épico.

    • AFT Main Region e AFT Secondary Region: as Regiões da AWS principais e secundárias da implantação do AFT.

Etapa 6: configurar as opções do AFT

  • Configure o relatório de métricas:

    • AFT Enable Metrics Reporting: habilite ou desabilite os relatórios de métricas do AFT. Para obter mais informações, consulte Operational metrics na documentação do AWS Control Tower.

  • Defina as opções de recursos do AFT:

    • Enable AFT CloudTrail Data Events: habilite eventos de dados do CloudTrail em todas as contas gerenciadas do AFT. Para obter mais informações, consulte AWS CloudTrail data events na documentação do AWS Control Tower.

    • Enable AFT Enterprise Support: habilite o Enterprise Support em todas as contas gerenciadas do AFT. Para obter mais informações, consulte AWS Enterprise Support plan na documentação do AWS Control Tower.

    • Enable AFT Delete Default VPC: exclua todas as VPCs somente na conta gerencial do AFT. Para obter mais informações, consulte Delete the AWS default VPC na documentação do AWS Control Tower.

Etapa 7: especificar as versões

  • AFT Terraform Version: escolha a versão do Terraform para usar em pipelines do AFT.

  • AFT Version: defina a versão do AFT para implantação. Mantenha a configuração padrão (latest) para usar a versão mais atual do AFT.

Etapa 8: analisar e criar a pilha

  • Revise todos os parâmetros e configurações. Se tudo estiver em ordem, continue criando a pilha.

Etapa 9: monitorar a criação da pilha

  • O CloudFormation provisiona e configura os recursos que você definiu. Monitore o processo de criação da pilha no console do CloudFormation. Esse processo pode levar vários minutos.

Etapa 10: verificar a implantação

  • Quando o status da pilha mostrar CREATE_COMPLETE, verifique se todos os recursos foram criados corretamente.

  • Na seção Saídas, anote o valor TerraformBackendBucketName.

Administrador de nuvem
TarefaDescriçãoHabilidades necessárias

Opção 1: preencher o repositório de bootstrap do AFT para um VCS externo.

Se você definir o provedor de VCS para um VCS externo (não para o CodeCommit), siga estas etapas.

(Opcional) Depois de implantar o modelo do CloudFormation, você pode preencher ou validar o conteúdo no repositório de bootstrap do AFT recém-criado e testar se o pipeline foi executado com êxito.

Etapa 1: atualizar a conexão

  1. No console do CodePipeline, no painel de navegação, escolha Configurações, Conexões.

  2. Selecione a conexão aft-vcs-connection. O status deve ser Pending.

  3. Escolha Atualizar conexão pendente e siga as instruções em Atualizar uma conexão pendente na documentação do console do Developer Tools.

  4. Quando o status da conexão for Available, siga para a próxima etapa.

Etapa 2: preencher o repositório

  1. Use suas credenciais do VCS externas para clonar o repositório que você especificou no modelo na sua máquina local. Se você manteve o nome padrão, o repositório será chamado aft-setup.

  2. No repositório, crie uma pasta chamada terraform com dois arquivos vazios dentro dela: backend.tf e main.tf.

  3. Abra o arquivo backend.tf e adicione este trecho de código:

    terraform {
  backend "s3" {
    region = "<aft-main-region>"
    bucket = "<s3-bucket-name>"
    key    = "aft-setup"
  }
}

    No arquivo:

    • Substitua <aft-main-region> pela região principal do AFT. Isse valor deve corresponder à região principal do AWS Control Tower.

    • Substitua <s3-bucket-name> pelo nome do bucket do backend do Terraform. É possível encontrar esse valor na TerraformBackendBucketName saída gerada pelo modelo do CloudFormation que você implantou anteriormente.

  4. Abra o arquivo main.tf e use um dos exemplos disponíveis no repositório do AFT para implantar o AFT. Por exemplo, você pode trabalhar com seu provedor de VCS preferido (CodeCommit, GitHub ou Bitbucket) ou personalizar a VPC do AFT. Para obter mais opções de entrada do AFT, consulte o arquivo README no repositório do AFT.

Etapa 2: confirmar e enviar as alterações

  • Depois de criar e preencher a pasta e os arquivos, confirme suas alterações e faça o upload do código no repositório. O pipeline é iniciado automaticamente, percorre os estágios de origem e compilação e, em seguida, aguarda uma ação de aprovação antes do estágio de implantação.

Administrador de nuvem

Opção 2: preencher o repositório de bootstrap do AFT para o CodeCommit.

Se você definir o provedor de VCS como o CodeCommit, siga estas etapas.

(Opcional) Depois de implantar o modelo do CloudFormation, você pode preencher ou validar o conteúdo no repositório de bootstrap do AFT recém-criado e testar se o pipeline foi executado com êxito.

Se você definir o parâmetro Generate AFT Files como true, vá para a próxima narrativa (validando o pipeline).

Etapa 1: preencher o repositório

  1. Abra o console do AWS CodeCommit e selecione o repositório recém-criado. Se você manteve o nome padrão, o nome do repositório será aft-setup.

  2. Clone o repositório em sua máquina local usando SSH, HTTPS ou HTTPS (GRC) e abra-o em um editor.

  3. Crie uma pasta chamada terraform e dois arquivos vazios dentro dela: backend.tf e main.tf.

  4. Abra o arquivo backend.tf e adicione este trecho de código:

    terraform {
  backend "s3" {
    region = "<aft-main-region>"
    bucket = "<s3-bucket-name>"
    key    = "aft-setup"
  }
}

    No arquivo:

    • Substitua <aft-main-region> pela região principal do AFT. Isse valor deve corresponder à região principal do AWS Control Tower.

    • Substitua <s3-bucket-name> pelo nome do bucket do backend do Terraform. É possível encontrar esse valor na TerraformBackendBucketName saída gerada pelo modelo do CloudFormation que você implantou anteriormente.

  5. Abra o arquivo main.tf e use um dos exemplos disponíveis no repositório do AFT para implantar o AFT. Por exemplo, você pode trabalhar com seu provedor de sistema de controle de versão (VCS) preferido (CodeCommit, GitHub ou Bitbucket) ou personalizar a VPC do AFT. Para obter mais opções de entrada do AFT, consulte o arquivo README no repositório do AFT.

Etapa 2: confirmar e enviar as alterações

  • Depois de criar e preencher a pasta e os arquivos, confirme suas alterações e faça o upload do código no repositório. O pipeline é iniciado automaticamente, percorre os estágios de origem e compilação e, em seguida, aguarda uma ação de aprovação antes do estágio de implantação.

Administrador de nuvem

Valide o pipeline de bootstrap do AFT.

Etapa 1: exibir o pipeline

  • Abra o console do CodePipeline e verifique se o pipeline aft-bootstrap-pipeline foi iniciado com sucesso. Ele deve estar executando um plano do Terraform ou aguardando uma ação de aprovação manual.

Etapa 2: aprovar os resultados do plano do Terraform

  • Você pode revisar os resultados do plano do Terraform examinando os logs de execução do estágio de compilação e, em seguida, aprovar ou rejeitar a execução no estágio de aprovação. Se você aprovar, o pipeline começará a implantar recursos do AFT na conta gerencial do AFT fornecida.

Etapa 3: aguardar a implantação

  • Aguarde até que o pipeline seja executado com sucesso. Esse processo deve levar cerca de 30 minutos. Qualquer falha que você possa encontrar geralmente é causada por cotas de API. Nesses casos, você pode executar novamente o pipeline para continuar a implantação.

Etapa 4: verificar os recursos criados

  • Acesse a conta gerencial do AFT e confirme se os recursos foram criados.

Administrador de nuvem

Solução de problemas

ProblemaSolução

A função do Lambda personalizada incluída no modelo do CloudFormation falha durante a implantação.

Verifique os logs do Amazon CloudWatch da função do Lambda para identificar o erro. Os logs fornecem informações detalhadas e podem ajudar a identificar o problema específico. Confirme se a função do Lambda tem as permissões necessárias e se as variáveis de ambiente foram definidas corretamente.

Você recebe falhas na criação ou no gerenciamento de recursos devido a permissões insuficientes.

Analise as políticas e os perfis do IAM que estão associadas à função do Lambda, ao CodeBuild e a outros serviços envolvidos na implantação. Confirme que todos têm as permissões necessárias. Se houver problemas de permissão, ajuste as políticas do IAM para conceder o acesso necessário.

Você está usando uma versão desatualizada do modelo do CloudFormation com Serviços da AWS ou versões do Terraform mais recentes.

Atualize regularmente o modelo do CloudFormation para que seja compatível com as versões da AWS e do Terraform mais recentes. Verifique as notas de lançamento ou a documentação para ver se há alterações ou requisitos específicos da versão.

As cotas do AWS service (Serviço da AWS) são atingidas durante a implantação.

Antes de implantar o pipeline, verifique as cotas do AWS service (Serviço da AWS) para recursos como buckets do S3, perfis do IAM e funções do Lambda. Solicite aumentos, se necessário. Para obter mais informações, consulte AWS service (Serviço da AWS) quotas no site da AWS.

Você encontra erros devido a parâmetros de entrada incorretos no modelo do CloudFormation.

Verifique novamente todos os parâmetros de entrada em busca de erros de digitação ou valores incorretos. Confirme se os identificadores de recursos, como IDs de conta e nomes de regiões, estão corretos.

Recursos relacionados

Para implementar este padrão com sucesso, revise os recursos a seguir. Esses recursos fornecem informações e orientações adicionais que podem ser imprescindíveis na configuração e no gerenciamento do AFT usando o CloudFormation.

AWS Documentação do:

Práticas recomendadas e políticas do IAM:

O Terraform na AWS:

AWS service (Serviço da AWS) Cotas do: