
Como usei o Lifecycle Hook no ASG durante deploy de novas instâncias
Pipeline automatizado para deploy em novas instâncias EC2 durante scale-out usando Lifecycle Hooks, Lambda, SNS, GitHub Actions e CodeBuild com Kamal deploy.
TL;DR: Montamos um fluxo automatizado onde, a cada scale-out do Auto Scaling Group, a nova instância EC2 fica em estado pendente (Lifecycle Hook) enquanto uma Lambda aciona um workflow no GitHub Actions que executa o deploy via Kamal usando CodeBuild como runner. A instância só entra em serviço após o deploy finalizar com sucesso. Sem intervenção humana, sem 502 para os usuários.
1. O Problema
As aplicações foram migradas para a AWS vindas de um ambiente que não tinha escalabilidade — as máquinas eram fixas e os deploys eram feitos manualmente. A migração já foi feita com a melhoria na estrutura e com a automação incluída desde o início.
A stack utiliza o Kamal como ferramenta de deploy para aplicações containerizadas rodando em instâncias EC2. O Kamal precisa de acesso SSH às máquinas para executar os comandos de deploy — o que descarta o uso de ECS, já que o Kamal gerencia o ciclo de vida dos containers diretamente nas instâncias.
Com a nova estrutura na AWS, ganhamos escalabilidade com Auto Scaling Group, mas isso trouxe um desafio: quando o ASG lança uma nova instância, ela é registrada no load balancer quase imediatamente — mas o container da aplicação pode levar minutos para estar disponível (pull da imagem, boot, health check). Sem tratamento, a instância ficaria disponível sem a aplicação rodando, gerando erros 502 para os usuários.
Outra particularidade: não existem branches separadas para produção e desenvolvimento. O código vive em uma única branch (
main ), e a distinção entre ambientes é feita no momento do deploy, não no fluxo de Git.O desafio do scale-out com Kamal
Sem o Lifecycle Hook, o cenário seria este:
- ASG lança nova instância durante scale-out
- Instância é registrada no target group imediatamente
- Usuários começam a receber erros 502 (container ainda não está rodando)
- O deploy precisaria ser acionado manualmente ou por algum trigger externo
- Só depois do deploy a instância ficaria funcional
O problema central: o ASG não sabe nada sobre o deploy da aplicação. Ele cuida de infraestrutura (criar/destruir instâncias), mas não garante que a aplicação esteja pronta antes de liberar tráfego. Essa lacuna precisava ser coberta na automação.
2. Arquitetura da Solução
A estrutura montada resolve esse problema criando um fluxo automatizado que:
- Impede que a nova instância fique disponível antes do deploy
- Aciona o deploy automaticamente quando uma instância nova é criada
- Libera a instância para tráfego somente após a confirmação de deploy bem-sucedido
Componentes
Componente | Função | Por que essa escolha |
|---|---|---|
EC2 + Auto Scaling Group | Instâncias que rodam as aplicações via Kamal | Kamal precisa de SSH direto nas máquinas |
Lifecycle Hook | Mantém a instância em estado pendente até o deploy finalizar | Impede registro no target group antes do deploy |
SNS | Recebe o evento de launch e aciona a Lambda | Desacoplamento entre ASG e processamento |
Lambda | Comunica com o GitHub para disparar o workflow de deploy | Serverless, pay-per-use, sem infra para manter |
GitHub Actions | Orquestra o pipeline de deploy | Pipeline já existente, visibilidade, re-runs |
CodeBuild (como runner) | Executa os comandos do Kamal dentro da AWS | Dentro da VPC, acesso SSH, pay-per-use |
Kamal | Realiza o deploy efetivo na nova instância via SSH | Ferramenta de deploy já adotada (ecossistema Rails) |
Decisões de Design
- Lifecycle Hook com
DefaultResult: ABANDON: Se o deploy não finalizar no timeout, a instância é terminada ao invés de entrar em serviço sem aplicação.
- CodeBuild como runner: O Kamal precisa de acesso SSH às instâncias. O CodeBuild roda dentro da VPC, eliminando a necessidade de expor portas na internet.
- Ambiente no payload (sem branches): A distinção staging/production é feita no payload do
workflow_dispatch, não em branches separadas.
O Fluxo

3. Implementação
3.1 Lifecycle Hook — Configuração
O Lifecycle Hook do tipo
autoscaling:EC2_INSTANCE_LAUNCHING cria uma janela de tempo entre o momento em que a instância é lançada e o momento em que ela entra em serviço. Durante essa janela:- A instância existe e está acessível via SSH (o Kamal pode se conectar)
- A instância não está no target group (não recebe requests dos usuários)
- O ASG espera um sinal explícito (
CONTINUEouABANDON) para prosseguir
{
"LifecycleHookName": "wait-for-deploy",
"LifecycleTransition": "autoscaling:EC2_INSTANCE_LAUNCHING",
"HeartbeatTimeout": 900,
"DefaultResult": "ABANDON"
}- HeartbeatTimeout: 900 — 15 minutos de timeout para o deploy finalizar
- DefaultResult: ABANDON — se o deploy não completar no timeout, a instância é terminada. Isso impede máquinas sem aplicação "penduradas" no grupo.
3.2 Lambda — Código Completo
A Lambda funciona como a ponte entre o evento de infraestrutura (nova instância) e o pipeline de deploy (GitHub Actions):
import boto3
import requests
import jwt
import time
import json
# Clientes AWS
secrets_client = boto3.client("secretsmanager")
autoscaling = boto3.client("autoscaling")
def get_secret(secret_name):
"""Lê segredos do AWS Secrets Manager."""
response = secrets_client.get_secret_value(SecretId=secret_name)
if "SecretString" in response:
return response["SecretString"]
else:
raise Exception("SecretBinary não suportado")
def get_installation_token(app_id, installation_id, private_key):
"""Gera um Installation Token do GitHub App usando JWT."""
now = int(time.time())
payload = {
"iat": now - 60,
"exp": now + 600,
"iss": app_id
}
jwt_token = jwt.encode(payload, private_key, algorithm="RS256")
headers = {
"Authorization": f"Bearer {jwt_token}",
"Accept": "application/vnd.github+json"
}
url = f"https://api.github.com/app/installations/{installation_id}/access_tokens"
r = requests.post(url, headers=headers)
if r.status_code != 201:
print(f"Erro na criação do token: {r.status_code} - {r.text}")
r.raise_for_status()
return r.json()["token"]
def lambda_handler(event, context):
# Lendo segredos do Secrets Manager
app_id = get_secret("/my-app/github_app_id")
installation_id = int(get_secret("/my-app/github_installation_id"))
private_key = get_secret("/my-app/github_private_key")
# Gera token temporário do GitHub App
gh_token = get_installation_token(app_id, installation_id, private_key)
# Dados do repositório e workflow
repo = "sua-org/seu-repositorio"
workflow_id = "deploy.yml"
url = f"https://api.github.com/repos/{repo}/actions/workflows/{workflow_id}/dispatches"
headers = {
"Authorization": f"Bearer {gh_token}",
"Accept": "application/vnd.github+json"
}
# Payload com o ambiente de destino
# A distinção staging/production é feita aqui, sem branches separadas
payload = {
"ref": "main",
"inputs": {
"deploy_destination": "staging",
"docker_image_tag": "latest-staging"
}
}
# Dispara o workflow no GitHub
response = requests.post(url, headers=headers, json=payload)
print(f"GitHub dispatch response: {response.status_code}")
# Finalizar Lifecycle Hook do ASG
if "detail" in event:
detail = event["detail"]
instance_id = detail.get("EC2InstanceId")
lifecycle_hook = detail.get("LifecycleHookName")
asg_name = detail.get("AutoScalingGroupName")
if instance_id and lifecycle_hook and asg_name:
autoscaling.complete_lifecycle_action(
LifecycleHookName=lifecycle_hook,
AutoScalingGroupName=asg_name,
LifecycleActionResult="CONTINUE",
InstanceId=instance_id
)
print(f"Lifecycle Hook finalizado para {instance_id}")
return {"status": "deploy iniciado para nova instância"}3.3 Deploy sem branches — Ambiente no Payload
Cada ambiente (staging e production) roda em uma conta AWS separada e nenhum deles se conversa. Ambas as contas possuem a mesma estrutura (ASG, Lifecycle Hook, SNS, Lambda), replicada de forma independente.
Como não existem branches separadas por ambiente no repositório, a diferenciação entre staging e production é feita diretamente no payload de cada função Lambda. Cada conta possui sua própria Lambda com o payload fixo para o respectivo ambiente:
# Lambda na conta de STAGING
payload = {
"ref": "main",
"inputs": {
"deploy_destination": "staging",
"docker_image_tag": "latest-staging"
}
}
# Lambda na conta de PRODUCTION
payload = {
"ref": "main",
"inputs": {
"deploy_destination": "production",
"docker_image_tag": "latest"
}
}O workflow no GitHub recebe esses inputs e o Kamal executa o deploy apontando para o ambiente certo — mesma branch, mesmo código, comportamento diferente baseado no destino. A separação de contas garante isolamento total entre os ambientes, enquanto o payload na Lambda define qual configuração do Kamal será executada.
3.4 Lambda Layer e Dependências
A Lambda utiliza bibliotecas externas que não estão disponíveis no runtime padrão do AWS Lambda (Python 3.12). É necessário empacotá-las como Lambda Layer.
Dependências necessárias
Pacote | Uso |
|---|---|
requests | Chamadas HTTP para a API do GitHub |
PyJWT | Geração do JWT para autenticação via GitHub App |
cryptography | Dependência do PyJWT para assinar com RS256 (chave privada RSA) |
Criando a Lambda Layer
# Criar diretório com a estrutura esperada pela Layer
mkdir -p layer/python
# Instalar dependências para Linux (runtime da Lambda)
pip install requests PyJWT cryptography -t layer/python \
--platform manylinux2014_x86_64 --only-binary=:all:
# Empacotar como zip
cd layer
zip -r ../lambda-layer-deploy.zip python/> Importante: O parâmetro
--platform manylinux2014_x86_64 garante que as bibliotecas compiladas (como cryptography ) sejam compatíveis com o ambiente Linux da Lambda, mesmo que você esteja buildando em Windows ou macOS.Publicando a Layer
aws lambda publish-layer-version \
--layer-name kamal-deploy-dependencies \
--zip-file fileb://lambda-layer-deploy.zip \
--compatible-runtimes python3.12 \
--compatible-architectures x86_64Alternativa: empacotar junto com o código
# Instalar na pasta do projeto
pip install requests PyJWT cryptography -t package/ \
--platform manylinux2014_x86_64 --only-binary=:all:
# Criar o zip com tudo junto
cd package
zip -r ../deploy-lambda.zip .
cd ..
zip deploy-lambda.zip lambda_function.py3.5 Configurações da Lambda
Configuração | Valor |
|---|---|
Runtime | Python 3.12 |
Timeout | 60 segundos |
Memória | 256 MB |
Arquitetura | x86_64 |
Handler | lambda_function.lambda_handler |
3.6 IAM — Permissões Mínimas
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["secretsmanager:GetSecretValue"],
"Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:/my-app/*"
},
{
"Effect": "Allow",
"Action": ["autoscaling:CompleteLifecycleAction"],
"Resource": "arn:aws:autoscaling:REGION:ACCOUNT_ID:autoScalingGroup:*"
}
]
}3.7 Secrets Manager
Secret Path | Conteúdo |
|---|---|
/my-app/github_app_id | ID numérico do GitHub App |
/my-app/github_installation_id | ID da instalação do App no repositório/org |
/my-app/github_private_key | Chave privada RSA do GitHub App (formato PEM) |
4. Por que não ECS
O Kamal faz parte do ecossistema Rails (é mantido pelo mesmo time que mantém o framework). Ele:
- Gerencia containers diretamente via Docker nas instâncias
- Precisa de acesso SSH às máquinas
- Cuida de zero-downtime deploy, health checks e rollback
- Não se integra nativamente com o modelo de orquestração do ECS
Migrar para ECS significaria abandonar o Kamal e reestruturar todo o pipeline de deploy — um custo que não faz sentido quando a solução com Lifecycle Hook atende perfeitamente.
5. Por que o CodeBuild como runner
O Kamal precisa de conectividade SSH com a instância de destino. O CodeBuild rodando como runner do GitHub Actions resolve isso porque:
- Roda dentro da VPC, na mesma rede das instâncias EC2
- Tem acesso SSH direto, sem necessidade de expor portas na internet
- Pode assumir roles IAM para interagir com outros serviços AWS
- Elimina a necessidade de runners self-hosted permanentes (pay-per-use)
6. Resultados
Métrica | Antes (manual) | Depois (automação) |
|---|---|---|
Tempo de engenheiro | ~30min por scale-out | 0 (automático) |
Erros 502 durante scaling | Frequentes | Zero |
Intervenção humana | Obrigatória | Nenhuma |
Disponibilidade no scale-out | Parcial (até alguém deployar) | Imediata após deploy |
Funcionamento fora do horário | Não (dependia de alguém online) | 24/7 |
Branches por ambiente | N/A | Branch única, ambiente no payload |
7. Lições Aprendidas / Gotchas
O que deu errado na primeira vez
- HeartbeatTimeout muito curto — Inicialmente configuramos 300s (5 min). Alguns deploys demoravam mais que isso e a instância era abandonada. Aumentamos para 900s.
- Lambda chamava
complete_lifecycle_actionantes do deploy terminar — Oworkflow_dispatchdo GitHub é assíncrono (retorna 204 imediatamente). Precisamos ajustar o fluxo para que oCONTINUEseja chamado ao final do workflow, não ao final da Lambda.
- GitHub App permissions — O GitHub App precisa de permissão
actions: writeno repositório para dispararworkflow_dispatch. Sem isso, retorna 404 (não 403).
- SNS message format — O evento que chega na Lambda via SNS vem empacotado em
Records[0].Sns.Message. O parsing precisa considerar isso antes de acessardetail.
Particularidades do Kamal
- Kamal precisa que o Docker já esteja rodando na instância antes do deploy
- A chave SSH do CodeBuild precisa estar no
authorized_keysda instância
- O
kamal deployfaz health check — se o container não responder, ele faz rollback automaticamente
8. Cenários de Falha e Resiliência
Cenário | O que acontece |
|---|---|
Deploy falha | Timeout do hook → ABANDON → instância terminada → ASG lança nova |
Lambda falha | Sem CONTINUE → timeout → ABANDON → retry automático pelo ASG |
GitHub fora do ar | Mesmo comportamento — instância é abandonada e ASG tenta novamente |
Deploy excede o timeout | Opção de usar record_lifecycle_action_heartbeat para estender o prazo |
Instância com problema de rede | Kamal falha no SSH → deploy falha → ABANDON |
9. Conclusão
A combinação de Lifecycle Hook + SNS + Lambda + GitHub Actions + CodeBuild transforma um processo manual e frágil em um fluxo automatizado e resiliente. O Kamal se mantém como ferramenta de deploy (sem lock-in em serviços gerenciados), a automação é completa no scale-out, e há a garantia de que nenhuma instância nova recebe tráfego antes de estar com a aplicação deployada e saudável — tudo com uma única branch e a distinção de ambiente feita pela própria infraestrutura.
Se você implementou algo parecido ou tem sugestões de melhoria, adoraria trocar ideias nos comentários!
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article