AWS Builder Center
Como usei o Lifecycle Hook no ASG durante deploy de novas instâncias

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:
  1. ASG lança nova instância durante scale-out
  1. Instância é registrada no target group imediatamente
  1. Usuários começam a receber erros 502 (container ainda não está rodando)
  1. O deploy precisaria ser acionado manualmente ou por algum trigger externo
  1. 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:
  1. Impede que a nova instância fique disponível antes do deploy
  1. Aciona o deploy automaticamente quando uma instância nova é criada
  1. 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

Diagrama mostrando o fluxo automatizado de deploy: Auto Scaling lança instância, Lifecycle Hook mantém em Pending:Wait, SNS aciona Lambda, Lambda dispara GitHub Actions, CodeBuild executa Kamal deploy via SSH, instância é liberada para InService


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 ( CONTINUE  ou  ABANDON ) 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_64

Alternativa: 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.py

3.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_action  antes do deploy terminar — O  workflow_dispatch  do GitHub é assíncrono (retorna 204 imediatamente). Precisamos ajustar o fluxo para que o  CONTINUE  seja chamado ao final do workflow, não ao final da Lambda.
  • GitHub App permissions — O GitHub App precisa de permissão  actions: write  no repositório para disparar  workflow_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 acessar  detail .

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_keys  da instância
  • O  kamal deploy  faz 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!
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article