Neste guia, vamos demonstrar como configurar a autenticação segura via OIDC (OpenID Connect) entre o GitLab CI/CD e a AWS, eliminando a necessidade de chaves de acesso estáticas. Você aprenderá a automatizar o provisionamento de recursos em múltiplas contas da sua organização utilizando Terraform e CloudFormation StackSets.

Ao final deste tutorial, você terá uma pipeline funcional capaz de implantar recursos padronizados em escala, garantindo conformidade e agilidade na gestão da sua infraestrutura em nuvem

Antes de Começar: Pré-requisitos

Para que você consiga reproduzir este laboratório com sucesso, certifique-se de que possui os seguintes itens preparados:

• Conta AWS Management: Este ambiente foi construído e testado a partir de uma conta Master/Management em um ambiente de laboratório.
• AWS Organizations Habilitado: É necessário que a sua conta principal faça parte de uma Organization para que possamos utilizar os recursos multi-account do StackSets.
• Projeto no GitLab: Você precisará de um repositório criado no GitLab (pode ser uma conta gratuita no GitLab.com) para configurar a pipeline de CI/CD.
• Acesso Administrativo: Certifique-se de ter permissões suficientes na conta AWS para criar Identity Providers e Roles IAM.
• Bucket S3 para o State: Um bucket S3 disponível para armazenar o arquivo de estado (state) do Terraform.

Configuração do Identity Provider (OIDC)

No console AWS da conta de gerenciamento, você deve estabelecer a confiança com o GitLab:

Acesse IAM > Identity providers e clique em Add provider.

Selecione OpenID Connect.

Provider URL: https://gitlab.com

Audience: gitlab.com

E clique em Add Provider

Criação da Role IAM para o Provider

Esta role permitirá que o GitLab assuma permissões na sua conta AWS:

• Configuração da Role IAM
• Nesta etapa, vamos criar a identidade que permitirá ao GitLab realizar alterações na sua conta AWS.
• Em IAM > Roles, clique em Create role.
• Escolha a entidade confiável Web identity.
• Selecione o Identity provider e a Audience (gitlab.com) que você configurou no passo anterior.
• Atenção aos Filtros: Como mostrado no print abaixo, você deve preencher os campos Group e Project conforme o seu ambiente no GitLab.

Nesta etapa, você vai determinar o que a sua pipeline poderá executar dentro da AWS.

1. Escolha das Permissões: Na tela “Add permissions”, você deve selecionar as políticas de acesso. Como o nosso objetivo é um ambiente de laboratório para provisionar diversos recursos, selecione a opção AdministratorAccess.
   • Nota: Isso garante que não teremos erros de “Access Denied” durante a execução da nossa primeira pipeline.
2. Prosseguir: Com a política selecionada, clique no botão Next no canto inferior da tela

Nesta última tela de criação (Step 3: Name, review, and create), você deve consolidar a identidade da sua automação:

• Role name: Digite um nome significativo, como Role-gitlab.
• Description (Opcional): Adicione uma descrição breve, como “Role utilizada pela pipeline do GitLab para provisionar StackSets”.
• Validando a Trust Policy: No campo de visualização do JSON, certifique-se de que a política permite a ação sts:AssumeRoleWithWebIdentity.
  • Verifique se o campo Principal aponta para o ARN do seu provider OIDC.
  • Valide se os campos Condition contêm as strings que restringem o acesso ao seu grupo e projeto específicos no GitLab (project_path:seu-grupo/seu-projeto).
• Finalização: Após validar que todas as informações e as permissões de AdministratorAccess estão corretas, clique em Create role no final da página

Agora que a Role IAM está pronta para ser assumida pelo GitLab, o próximo passo é preparar o serviço de CloudFormation para operar em escala sobre toda a sua estrutura de contas.

Habilitando o Gerenciamento via StackSets

Para que o provisionamento centralizado funcione, você precisa autorizar a comunicação entre o CloudFormation e o AWS Organizations. Sem isso, a automação não terá permissão para “espalhar” os recursos pelas contas subordinadas.

1. No console da AWS, procure por CloudFormation.
2. No menu lateral esquerdo, clique na opção StackSets
3. Você visualizará um banner informativo azul no topo da página. Clique no botão Enable trusted access localizado à direita.
   • O que isso faz? Essa ação ativa as permissões gerenciadas pelo serviço (service-managed permissions). Isso permite que a AWS crie automaticamente as roles necessárias em cada conta da sua organização para que o StackSet consiga realizar o deploy.

Preparando o Ambiente Local e Personalizando o Código

Agora que a infraestrutura na AWS está pronta, vamos configurar o seu repositório local. Siga exatamente esta ordem para garantir que a automação funcione:

1. Clone o seu Repositório

Primeiro, você deve trazer o projeto (que você criou no GitLab) para a sua máquina:

Bash

git clone https://gitlab.com/seu-usuario/seu-projeto.git
cd seu-projeto

2. Baixe os Arquivos Base

Acesse o link abaixo e baixe os arquivos de configuração que preparei para este laboratório. Após baixar, extraia e coloque todos os arquivos dentro da pasta onde você clonou o seu projeto:

• Link dos Arquivos: https://gist.github.com/renanlira31/d83d43e53698c4d373db968e3941edaa

Após baixar e extrair os arquivos, você deve garantir que a organização das pastas dentro do seu repositório clonado esteja correta. Como este é um projeto que utiliza Terraform para gerenciar CloudFormation StackSets, a localização dos arquivos é crucial para que a pipeline encontre os templates.

A estrutura do seu projeto deve ficar exatamente desta forma:

Detalhes da Estrutura:

• stacksets-lab/: Este é o diretório raiz do seu projeto.
• templates/: Pasta obrigatória que deve conter o arquivo role-teste.yaml.
• .gitlab-ci.yml: Deve estar na raiz para que o GitLab reconheça a pipeline.
• main.tf: Arquivo principal de configuração do provedor AWS e Backend.
• stackset-role-teste.tf: Recurso que define a criação do StackSet.
• variables.tf: Onde residem as variáveis que você personalizou anteriormente.
• README.md: Arquivo de documentação do seu laboratório.

Agora que os arquivos estão na pasta correta, você precisa ajustá-los para que a automação reconheça a sua infraestrutura específica. Como este é um ambiente de Cloud Foundation, a precisão aqui é o que garante o sucesso do deploy.

Abra os arquivos em seu editor de código e realize as seguintes alterações conforme os placeholders:

Guia de Alterações por Arquivo

Placeholder	Arquivo(s)	O que você deve fazer
YOUR_ACCOUNT_ID	.gitlab-ci.yml e role-teste.yaml	Substitua pelo ID de 12 dígitos da sua conta de gerenciamento (Management Account).
YOUR_ROLE_NAME	.gitlab-ci.yml	Insira o nome exato da Role IAM que você criou para o OIDC do GitLab.
YOUR_STATE_BUCKET	main.tf	Coloque o nome de um bucket S3 (que você já possua ou vá criar) para armazenar o arquivo de estado do Terraform.
YOUR_OU_OR_ROOT_ID	variables.tf	Informe o ID da sua Organization Root (ex: r-xxxx) ou da Unidade Organizacional (OU) alvo.

Disparando a Automação via Git

Agora que o seu ambiente local está configurado e os arquivos personalizados, vamos enviar tudo para o GitLab. Abra o terminal dentro da pasta do seu projeto e execute os comandos na ordem abaixo:

Preparar os arquivos: Adicione todas as alterações e novos arquivos ao controle do Git:

Bash

git add .

Validar o status: Este passo é importante para garantir que todos os arquivos (incluindo a pasta templates/ e o .gitlab-ci.yml) estão prontos para o envio:

Bash

git status

Registrar a versão: Crie o commit com uma mensagem descritiva para o seu histórico:

Bash

git commit -m "Primeira pipeline multi-account"

Enviar e Iniciar: Ao realizar o push, o GitLab detectará automaticamente o arquivo de configuração e iniciará a pipeline de imediato:

Bash

git push

Com o envio do código via Git, a automação ganha vida. Agora é o momento de acompanhar o progresso diretamente pela interface do GitLab, onde você verá as etapas (stages) que definimos no arquivo .gitlab-ci.yml sendo processadas.

Monitorando a Execução em Tempo Real

Para visualizar o status da sua automação:

• Acesso às Pipelines: No menu lateral do seu projeto no GitLab, navegue até Build > Pipelines.
• Status Running: Você verá a sua execução com a tag “Primeira pipeline” e o status azul indicando Running.
• Etapas de Validação: A pipeline passará automaticamente pelos processos de validação e planejamento (terraform_plan), garantindo que o código está correto antes de qualquer alteração na AWS.

Aguardando o Apply Manual

Como medida de segurança em ambientes de infraestrutura, a etapa final não ocorre sozinha:

• Aprovação Manual: Assim que as primeiras fases passarem (status verde “Passed”), a pipeline ficará aguardando uma ação no estágio de apply.
• Ação Necessária: Localize o job terraform_apply e note que ele possui um ícone de “play”, indicando que aguarda a sua autorização manual para provisionar os recursos.

Após autorizar o terraform_apply, a pipeline percorrerá o estágio final de execução. Ao término do processo, você verá o status verde indicando que a operação foi bem-sucedida.

Validando a Conclusão no GitLab

• Status Passed: A pipeline exibirá o selo verde Passed, confirmando que todos os estágios (Validate, Plan e Apply) foram concluídos sem erros.
• Log de Sucesso: Ao abrir o job de apply, você verá a confirmação de que os recursos foram provisionados na AWS conforme planejado.

Verificação no Console AWS

Com a automação finalizada, é hora de validar o resultado diretamente na console da AWS para garantir que os recursos foram distribuídos corretamente entre as contas:

1. Visualizando o StackSet: No console de CloudFormation > StackSets, você agora poderá visualizar o novo StackSet criado (ex: stackset-role-teste).
2. Status das Instâncias: Clique no StackSet e vá até a aba Stack instances. Lá, você verá a listagem das contas alvo e o status SUCCEEDED, indicando que o recurso foi provisionado com sucesso naquela conta específica.

Confirmação na Conta Destino: Ao acessar a conta subordinada e navegar até o IAM > Roles, você encontrará a nova Role (ex: role Teste) com as permissões definidas (como AmazonS3ReadOnlyAccess), provando que a automação multi-account funcionou perfeitamente.

Conclusão e Próximos Passos

Parabéns! Você acaba de implementar uma solução de Cloud Foundation digna de ambientes corporativos. Ao integrar o GitLab CI/CD com o OIDC e o CloudFormation StackSets, você eliminou o uso de credenciais estáticas e criou um motor de distribuição de infraestrutura capaz de gerenciar centenas de contas AWS com um único comando.

A automação que construímos aqui garante que a governança da sua organização seja aplicada de forma consistente, rápida e segura.

Flexibilidade para o seu Cenário

É importante lembrar que esta é apenas uma das diversas formas de automatizar o seu ambiente. O poder desta arquitetura reside na sua escalabilidade:

• Gerenciamento por OU: Você pode configurar os StackSets para mirar em Unidades Organizacionais específicas, garantindo que contas de “Desenvolvimento” recebam recursos diferentes das contas de “Produção”.
• Controle por Ambiente: É possível separar a lógica por pastas ou branches no seu repositório, adaptando o provisionamento conforme a necessidade de cada projeto.

A automação está pronta, agora o limite é a sua criatividade para expandir esse ecossistema!

Espero que este guia tenha sido útil para a sua jornada Cloud. Seja feliz e bons deploys!