AWS Builder Center
5 erros que cometi no meu primeiro deploy com AWS CDK (e como resolvi cada um)

5 erros que cometi no meu primeiro deploy com AWS CDK (e como resolvi cada um)

Neste artigo, conto os erros reais que encontrei ao seguir o projeto Setting Up Your Dev Environment do AWS Builder Center, que usa CDK e Python para criar um tópico SNS com notificações por email. O tutorial em si é excelente — o que me travou foram detalhes de ambiente específicos do Windows que ele não cobre. Se você está começando agora, este guia vai te poupar bastante tempo.

Quando decidi aprender AWS CDK, achei que seria simples: escrever um pouco de Python, rodar um comando e ver a infraestrutura subir na nuvem. A realidade foi um pouco diferente — e muito mais instrutiva.
Neste artigo, conto os erros reais que encontrei ao seguir o projeto  Setting Up Your Dev Environment  do AWS Builder Center, que usa CDK e Python para criar um tópico SNS com notificações por email. O tutorial em si é excelente — o que me travou foram detalhes de ambiente específicos do Windows que ele não cobre. Se você está começando agora, este guia vai te poupar bastante tempo.



O que eu queria construir

Um tópico Amazon SNS com uma inscrição de email. Ou seja: qualquer mensagem publicada no tópico seria automaticamente entregue na minha caixa de entrada. Simples conceitualmente, mas cheio de armadilhas na prática — especialmente no Windows.
A imagem mostra o código de envio da mensagem e seu respectivo ID




Erro 1:  ModuleNotFoundError: No module named 'aws_cdk' 

O que aconteceu

Rodei o comando  cdk synth  e recebi este erro:
ModuleNotFoundError: No module named 'aws_cdk'
python app.py: Subprocess exited with error 1

A causa

O CDK cria um ambiente virtual Python ( .venv ) durante a inicialização do projeto e instala as dependências lá dentro. O problema é que, no Windows, simplesmente rodar  cdk synth  ou  cdk deploy  no terminal usa o Python do sistema — não o Python do  .venv  onde o  aws_cdk  está instalado.

A solução

Passar o Python do ambiente virtual explicitamente com o parâmetro  --app :
cdk synth --app ".venv\Scripts\python.exe app.py"
cdk deploy --app ".venv\Scripts\python.exe app.py"
Para não precisar repetir isso toda vez, você pode atualizar a linha  app  no  cdk.json :
{
"app": ".venv\\Scripts\\python.exe app.py"
}



Erro 2: Comandos multilinha com  \  não funcionam no PowerShell

O que aconteceu

Copiei um comando de exemplo de um tutorial e colei no PowerShell:
aws sns publish \
--topic-arn "arn:aws:sns:..." \
--subject "Hello" \
--message "Minha primeira mensagem"
O resultado foi uma série de erros como:
Expressão ausente após operador unário '--'.
Token 'topic-arn' inesperado na expressão ou instrução.

A causa

A barra invertida  \  no final da linha é usada no Bash (Linux/Mac) para indicar que o comando continua na próxima linha. No PowerShell do Windows isso não funciona — o shell interpreta  --topic-arn  como uma expressão matemática e fica confuso.

A solução

Colocar o comando inteiro em uma única linha:
aws sns publish --topic-arn "arn:aws:sns:sa-east-1:123456789012:my-notifications-topic" --subject "Hello" --message "Minha primeira mensagem" --region sa-east-1
Ou, se quiser quebrar em múltiplas linhas no PowerShell, use o backtick  `  no lugar do  \ :
aws sns publish `
--topic-arn "arn:aws:sns:sa-east-1:123456789012:my-notifications-topic" `
--subject "Hello" `
--message "Minha primeira mensagem" `
--region sa-east-1



Erro 3:  &&  para encadear comandos não funciona no PowerShell

O que aconteceu

Tentei ativar o ambiente virtual e rodar o CDK em seguida com:
.venv\Scripts\activate.bat && cdk synth
O PowerShell retornou um erro de sintaxe.

A causa

O operador  &&  para encadear comandos é sintaxe do Bash. No PowerShell tradicional, ele não é suportado da mesma forma (versões mais antigas do PowerShell não reconhecem  &&  como operador de encadeamento condicional).

A solução

Rodar os comandos separadamente, um por vez:
.venv\Scripts\activate.bat
cdk synth
Ou usar ponto e vírgula  ; , que executa o segundo comando independentemente do resultado do primeiro:
.venv\Scripts\activate.bat; cdk synth



Erro 4: Usar o ARN de exemplo em vez do ARN real

O que aconteceu

Copiei um comando de teste com um ARN genérico:
aws sns publish --topic-arn "arn:aws:sns:us-east-1:111122223333:MyTopic" ...
O comando falhou porque esse ARN não existe na minha conta.

A causa

Tutoriais costumam usar ARNs fictícios como placeholder. É fácil esquecer de substituir pelo valor real.

A solução

Buscar o ARN real do tópico com:
aws sns list-topics --region sa-east-1
Ou, no PowerShell, já buscar e publicar em sequência:
$topicArn = (aws sns list-topics --region sa-east-1 --query "Topics[?contains(TopicArn,'my-notifications-topic')].TopicArn" --output text)
aws sns publish --topic-arn $topicArn --subject "Teste" --message "Funcionou!" --region sa-east-1



Erro 5: Não confirmar a inscrição de email

O que aconteceu

Fiz o deploy, publiquei uma mensagem no tópico e... nada chegou no email. O comando executou sem erros, mas a caixa de entrada ficou vazia.

A causa

O Amazon SNS não começa a entregar emails automaticamente após o deploy. Ele envia uma mensagem de confirmação primeiro, e a inscrição só fica ativa depois que você clica no link "Confirm subscription" dentro desse email.

A solução

Depois de rodar  cdk deploy , verifique sua caixa de entrada (e a pasta de spam) por um email com assunto "AWS Notification - Subscription Confirmation". Clique no link de confirmação. Só depois disso as mensagens publicadas no tópico serão entregues.



Conclusão

Erros de ambiente e de sistema operacional são tão frustrantes quanto bugs de código — às vezes mais, porque a mensagem de erro não deixa claro o que está errado. A maioria dos tutoriais de AWS é escrita para Linux ou Mac, e pequenos detalhes como  \  versus  `  ou o caminho do Python fazem toda a diferença no Windows.
O projeto em si ficou pequeno e funcional: um tópico SNS com notificação por email, definido como código com AWS CDK e Python, versionável e reproduzível. O aprendizado real, porém, veio dos erros no meio do caminho.
Se você está começando com CDK no Windows, espero que este artigo tenha te poupado pelo menos uma hora de frustração.


Construído com AWS CDK v2, Python 3.14, Windows 11 e muita paciência.



Referências

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