TerraformComunidade
Nível de dificuldade: Avançado (4 de 5)
Pipeline de CI/CD no ECS Fargate elimina o deploy manual com Terraform
Um tutorial publicado na DEV Community mostra como ligar GitHub, CodePipeline, CodeBuild, ECR e ECS Fargate para que git push seja o único passo manual do deploy. Adaptamos o roteiro para Terraform e mapeamos as dez armadilhas que o autor levou horas para resolver.
Nota da redação: este artigo faz duas afirmações sobre cobrança da AWS (minutos gratuitos do CodeBuild no tipo general1.small e cobrança por segundo do ECS Fargate) que não puderam ser confirmadas em documentação oficial da AWS entre as fontes consultadas; são descrições gerais de como esses serviços costumam funcionar, não checadas linha a linha. Além disso, duas frases do texto ('o item que mais gente esquece' e 'a falha que mais custou tempo') são caracterizações de ênfase da redação, não afirmações feitas pelo autor do tutorial original. Recomendamos ao leitor confirmar os detalhes de billing diretamente na documentação da AWS antes de planejar custos.
Um tutorial publicado na DEV Community, em circulação desde pelo menos outubro de 2024 (um comentário na página de origem já traz essa data), mostra como ligar GitHub, CodePipeline, CodeBuild, ECR e ECS Fargate para que git push seja o único passo manual do deploy. Adaptamos o roteiro para Terraform e mapeamos as dez armadilhas que o autor levou horas para resolver.
Um tutorial publicado na DEV Community, em circulação desde pelo menos outubro de 2024, mostra como ligar GitHub, CodePipeline, CodeBuild, ECR e ECS Fargate para que git push seja o único passo manual do deploy. Adaptamos o roteiro para Terraform e mapeamos as dez armadilhas que o autor levou horas para resolver.
Muhammad Bilal Sharif Bukhari publicou na DEV Community, em um tutorial que já circula há mais de um ano, o relato de como montou um pipeline de CI/CD para um cliente que ainda fazia deploy manual: build na máquina local, push manual de imagem, clique no console da ECS e um refresh na esperança de que nada tivesse quebrado. O projeto (disponível no post original) virou um roteiro completo de GitHub até Amazon ECS on Fargate, com uma regra única: depois do git push, nenhum passo humano deveria existir.
Para quem trabalha com arquitetura, DevOps ou SRE e já mantém a infraestrutura como código, o valor do material não está no "como clicar no console", mas no desenho do pipeline e, principalmente, na lista de dez coisas que quebraram no caminho. Reescrevemos o tutorial com Terraform no lugar do console, porque reproduzir esse ambiente à mão duas vezes (uma para teste, outra para produção) é exatamente o tipo de trabalho manual que este artigo tenta eliminar.
O que você vai construir
Um pipeline de entrega contínua totalmente provisionado por Terraform, com este fluxo:
- Um push para o branch principal no GitHub dispara o AWS CodePipeline.
- O AWS CodeBuild builda a imagem Docker a partir do
Dockerfiledo repositório e a tagueia com o hash do commit. - A imagem é publicada no Amazon ECR, um registro privado.
- O Amazon ECS, rodando em Fargate, sobe uma nova task com a imagem fresca e desliga a antiga sem downtime perceptível.
Não há instância EC2 para corrigir, nem build manual, nem clique no console. O exemplo original usava um jogo 2048 em Nginx estático; aqui mantemos o mesmo container de referência, mas qualquer aplicação dockerizada segue o mesmo esqueleto.
| Serviço | Função no pipeline |
|---|---|
| GitHub | Fonte da verdade e gatilho do pipeline |
| AWS CodePipeline | Orquestra as etapas Source, Build e Deploy |
| AWS CodeBuild | Builda e tagueia a imagem Docker |
| Amazon ECR | Registro privado das imagens |
| Amazon ECS (Fargate) | Executa o container sem servidor para gerenciar |
| IAM roles | Permitem que cada serviço fale com o próximo |
Pré-requisitos
- Uma conta AWS com permissão para criar recursos em ECR, ECS, CodeBuild, CodePipeline e IAM (ou um usuário com a policy
AdministratorAccesssó para o laboratório; em produção, restrinja por serviço). - Terraform na versão 1.5 ou superior e o provider
hashicorp/awsconfigurado com credenciais válidas (aws configureou variáveisAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY). - AWS CLI instalado, para validar o que o Terraform criou.
- Docker instalado localmente, só para testar o build antes de confiar no CodeBuild.
- Um repositório no GitHub com um
Dockerfileválido e um token de acesso pessoal (ou uma conexão via AWS CodeStar Connections) para o CodePipeline ler o código. - Este roteiro usa a região São Paulo (
sa-east-1); o tutorial original rodou emus-east-1, então troque a região nos exemplos se preferir seguir o original à risca.
Passo a passo
1. ECR e cluster ECS em Terraform
Comece pelos recursos de base: o repositório de imagens e o cluster Fargate.
resource "aws_ecr_repository" "game" {
name = "game-2048-repo"
force_delete = true
}
resource "aws_ecs_cluster" "game" {
name = "game-2048-cluster"
}A flag force_delete = true evita que um terraform destroy trave porque o repositório ainda tem imagens dentro, o que é exatamente o tipo de resíduo que o tutorial original aponta como fonte de cobrança esquecida.
2. Task definition e service
O autor original escolheu um tamanho de task maior que o mínimo para não ter que debugar limite de CPU/memória ao mesmo tempo que o resto do pipeline. Faz sentido replicar isso em Terraform:
resource "aws_ecs_task_definition" "game" {
family = "game-2048-task"
requires_compatibilities = ["FARGATE"]
network_mode = "awsvpc"
cpu = "512"
memory = "1024"
execution_role_arn = aws_iam_role.execution.arn
container_definitions = jsonencode([{
name = "2048-container"
image = "${aws_ecr_repository.game.repository_url}:latest"
portMappings = [{ containerPort = 80, hostPort = 80 }]
}])
}
resource "aws_ecs_service" "game" {
name = "game-2048-service"
cluster = aws_ecs_cluster.game.id
task_definition = aws_ecs_task_definition.game.arn
desired_count = 1
launch_type = "FARGATE"
network_configuration {
subnets = [aws_subnet.public.id]
security_groups = [aws_security_group.http.id]
assign_public_ip = true
}
}O nome 2048-container precisa ser idêntico, caractere por caractere, ao que o CodeBuild vai escrever depois no arquivo imagedefinitions.json. Essa foi a falha que mais custou tempo no tutorial original: um nome digitado de memória, em vez de copiado da task definition, quebrou o deploy inteiro sem nenhum erro óbvio na tela.
3. IAM: a parte que decide se tudo funciona
Quase todo erro do tutorial original foi, no fundo, uma permissão IAM faltando. Duas roles são obrigatórias:
resource "aws_iam_role" "execution" {
name = "ecsTaskExecutionRole"
assume_role_policy = data.aws_iam_policy_document.ecs_assume.json
}
resource "aws_iam_role_policy_attachment" "execution" {
role = aws_iam_role.execution.name
policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
}
resource "aws_iam_role_policy_attachment" "codebuild_ecr" {
role = aws_iam_role.codebuild.name
policy_arn = "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPowerUser"
}Sem a policy AmazonEC2ContainerRegistryPowerUser (ou uma policy customizada equivalente) na role do CodeBuild, o push para o ECR falha com um erro de autenticação que não tem nada a ver com login ou senha: é a role que não tem permissão, não o comando que está errado.
4. O buildspec.yml do CodeBuild
O Dockerfile do exemplo original é mínimo, porque a aplicação é estática:
FROM nginx:alpine
COPY . /usr/share/nginx/html
EXPOSE 80E o buildspec.yml que o CodeBuild lê do repositório faz login no ECR, builda, tagueia e escreve o imagedefinitions.json que o ECS vai consumir na etapa de deploy:
version: 0.2
phases:
pre_build:
commands:
- aws ecr get-login-password --region sa-east-1 | docker login --username AWS --password-stdin $ECR_URI
build:
commands:
- docker build -t game-2048-repo .
- docker tag game-2048-repo:latest $ECR_URI/game-2048-repo:$CODEBUILD_RESOLVED_SOURCE_VERSION
post_build:
commands:
- docker push $ECR_URI/game-2048-repo:$CODEBUILD_RESOLVED_SOURCE_VERSION
- printf '[{"name":"2048-container","imageUri":"%s"}]' $ECR_URI/game-2048-repo:$CODEBUILD_RESOLVED_SOURCE_VERSION > imagedefinitions.json
artifacts:
files: imagedefinitions.jsonRepare que trocamos a tag latest do tutorial original por $CODEBUILD_RESOLVED_SOURCE_VERSION, a variável de ambiente que o CodeBuild preenche com o SHA do commit. O próprio autor lista isso como aprendizado em aberto: latest serve para laboratório, não para produção, porque torna impossível saber qual imagem está rodando ou fazer rollback com segurança.
Também é preciso habilitar o modo Privileged no ambiente do CodeBuild (em Terraform, privileged_mode = true no bloco environment de aws_codebuild_project), porque o CodeBuild não permite Docker-in-Docker por padrão. Sem isso, o build morre assim que chega no docker build, com uma mensagem de que não consegue falar com o daemon do Docker.
5. CodePipeline: ligando as três etapas
O pipeline final tem três estágios: Source (GitHub), Build (CodeBuild) e Deploy (ECS). Em Terraform, o recurso aws_codepipeline referencia o aws_codebuild_project e o aws_ecs_service criados acima, com um bucket S3 como artifact store entre os estágios. Quando as três etapas aparecem verdes, um push qualquer no repositório já é suficiente para rodar o fluxo inteiro sem tocar no console.
Testando
- Faça um push trivial no repositório (uma mudança de cor, por exemplo) e acompanhe o pipeline em CodePipeline > game-2048-pipeline.
- Confira os logs do build em tempo real com
aws logs tail /aws/codebuild/game-2048-build --follow. - Depois que o estágio Deploy terminar, liste as tasks rodando:
aws ecs list-tasks --cluster game-2048-cluster. - Se uma task aparecer como
STOPPEDem segundos, abra ostoppedReasoncomaws ecs describe-tasksantes de qualquer outra coisa; o tutorial original aponta isso como o sintoma mais comum de porta de container errada ou de execution role ausente. - Pegue o IP público da task (
aws ecs describe-taskstraz o ENI, e a partir dele dá para consultar o IP) e acesse viacurl -I http://<ip>:80. Se a resposta não vier, o suspeito número um é o security group: ele precisa liberar entrada na porta 80, e a task precisa terassign_public_ip = true. - Se o pipeline terminar verde mas a página não mudar, é cache do navegador, não falha do pipeline, outro ponto que o autor original confundiu até perceber que a tag
latestestava sendo reaproveitada.
Um comentário no post original, de outro leitor, sugere ir além desses testes manuais:
Uma coisa que eu adicionaria antes do passo de ALB e HTTPS: uma verificação de saúde pós-deploy dentro do próprio pipeline. Depois que o ECS reportar a nova task como rodando, faça o CodeBuild (ou uma etapa com Lambda) bater no endpoint do serviço e falhar o pipeline se ele não responder 200 em alguns minutos. Assim, uma imagem ruim que sobe mas nunca serve tráfego falha de forma visível, em vez de aparecer verde.
One thing I'd add before the ALB/HTTPS step: a small post-deploy health check in the pipeline itself. After ECS reports the new task as running, have CodeBuild (or a Lambda invoke step) hit the service endpoint and fail the pipeline if it doesn't return 200 within a couple of minutes. That way a bad image that starts but never serves traffic fails loudly instead of looking green.Abdullah Naseer, desenvolvedor independente do Paquistão
É um complemento razoável ao roteiro original: pipeline verde não é sinônimo de aplicação saudável, só de etapas executadas sem erro de infraestrutura.
Limpando os recursos
Este pipeline sai do Free Tier em pontos específicos: o ECS Fargate cobra por vCPU e GB de memória por segundo enquanto a task roda, e o CodeBuild só tem minutos gratuitos limitados por mês no tipo general1.small; o resto é cobrado por minuto de build. Por isso, ao encerrar o laboratório:
- Rode
terraform destroypara removeraws_ecs_service,aws_ecs_task_definition,aws_ecs_cluster,aws_codebuild_project,aws_codepipelinee as roles IAM associadas. - Confirme que o
aws_ecr_repositorytinhaforce_delete = true; sem isso, o destroy falha com o repositório ainda cheio de imagens. - Verifique manualmente no console ou via
aws ecr list-images --repository-name game-2048-repose não sobrou nenhuma imagem órfã fora do que o Terraform geriu. - Apague o bucket S3 usado como artifact store do CodePipeline, se ele não estiver sob o gerenciamento do Terraform.
- Rode
aws ecs list-clusterseaws codepipeline list-pipelinesno final para confirmar que nada ficou para trás; o tutorial original cita exatamente isso como o item que mais gente esquece, um cluster, um serviço e um registro cheio de imagens rodando cobrança sozinhos.
Próximos passos
O autor original lista, como evolução natural do laboratório, um Application Load Balancer com certificado ACM na frente do serviço (o pipeline, como descrito, serve a aplicação em HTTP puro, daí o aviso de "não seguro" no navegador), deployments blue/green para eliminar qualquer janela de indisponibilidade, alarmes de CloudWatch para saúde das tasks e uma etapa de testes (lint ou testes unitários) antes do deploy. Ele também cita Terraform ou CloudFormation como passo seguinte, exatamente o que este roteiro já adianta.
Para quem desenha esse tipo de ambiente em produção, dois itens merecem prioridade sobre os demais: a tag de imagem por commit SHA (já incorporada acima) e a verificação de saúde pós-deploy sugerida no comentário, porque juntas elas resolvem o pior cenário do tutorial original, um deploy que o pipeline considera bem-sucedido, mas que não serve tráfego de verdade.
Fonte: DEV Community — #aws
Serviços neste textoTerraform
Leve para a sua IA
Decida com o seu assistente, com o contexto deste texto já montado.
1. O que você quer saber
Ver o prompt
Li no AWS Hub: "Pipeline de CI/CD no ECS Fargate elimina o deploy manual com Terraform" (https://awshub.com.br/comunidade/pipeline-de-ci-cd-no-ecs-fargate-elimina-o-deploy-manual-com-terraform). Resumo: Um tutorial publicado na DEV Community mostra como ligar GitHub, CodePipeline, CodeBuild, ECR e ECS Fargate para que git push seja o único passo manual do deploy. Adaptamos o roteiro para Terraform e mapeamos as dez armadilhas que o autor levou horas para resolver. Serviços: Terraform Minha stack: [descreva em uma linha: serviços, linguagem, volume, região] Isso muda alguma coisa na minha arquitetura? O que eu faria diferente a partir de amanhã?