11 min de leitura
O AWS Emulator não tem UI, então eu dei uma pra ele
O AWS Emulator saiu sem interface. Como fiz o StackPort, um console web open source para emuladores locais da AWS, funcionar com ele, e o que ele achou no meu próprio código.
- aws
- stackport
- opensource
- python
Em 11 de novembro, a AWS lançou o AWS Emulator: um programa na sua máquina que responde às APIs da AWS, pra que o seu código crie filas, buckets e funções Lambda sem conta e sem fatura. O README é claro sobre uma coisa que ele não faz:
The emulator is a local program that serves an AWS API endpoint. It has no graphical interface.
Ou seja: é um programa local que serve um endpoint da API da AWS, e não tem interface gráfica.
Ele foi direto pra primeira página do Hacker News. Em menos de meia hora, alguém perguntou: "ok who's gonna build the GUI / web console on top of it?" ("ok, quem vai fazer a GUI / o console web em cima disso?"). Outra pessoa respondeu: "For what? Use the APIs." ("Pra quê? Use as APIs."). No dia seguinte, o criador do MiniStack, o emulador de onde o StackPort nasceu, respondeu: "StackPort ;)"
O StackPort é o console web open source que eu mantenho para emuladores locais da AWS. Comecei ele como um pull request pro MiniStack. Só tinha um problema com aquela resposta: o StackPort nunca tinha falado com o AWS Emulator.
Então apontei a última versão pra ele. Das 14 telas que testei, 3 abriram. O "Test connection" disse que o endpoint estava unhealthy. O dashboard levou 57 segundos pra carregar.
Dois dias e cinco releases depois, o mesmo dashboard estava assim:
O StackPort conectado ao AWS Emulator em 13 de novembro.
Este post é sobre o que aconteceu no meio.
"Pra quê? Use as APIs."
É uma pergunta justa, e a resposta é o motivo de o StackPort existir. A API é como o seu código fala com a AWS. Um console é como você confere o que o seu código fez. Quando um teste falha porque uma mensagem nunca chegou, não quero escrever um script que lista as filas e espia as mensagens. Quero olhar.
Emuladores deixam a AWS barata de rodar na sua máquina. Eles não deixam a AWS visível. O AWS Emulator acabou sendo o mais rigoroso que já apontei pro StackPort, e essa foi a parte interessante.
O problema não era o emulador
Antes de escrever qualquer código, conferi se o emulador conseguia pelo menos responder ao StackPort. Listei todas as chamadas boto3 distintas que o StackPort faz, 244, e procurei cada uma no emulador: todas implementadas, nenhuma era stub.
Então as 11 telas quebradas eram culpa do StackPort. Mais exatamente, eram culpa de hábitos que os outros emuladores deixavam passar. A maioria dos emuladores locais aceita qualquer access key, em HTTP simples. O AWS Emulator se comporta muito mais como a AWS:
- só serve HTTPS, em
127.0.0.1:9297, com um certificado autoassinado que ele cria a cada start; - confere toda assinatura, contra chaves que ele também cria a cada start;
- recusa requisições de páginas web de outros sites.
Cada uma dessas coisas quebrou alguma coisa. Tente fazer uma requisição passar:
1. Browsers não são bem-vindos
Essa é a regra que decide como uma UI pro AWS Emulator pode ser. Ela está no código do emulador, com um comentário que explica melhor do que eu:
Refuses a request a browser sent from another site (its
OriginorSec-Fetch-Sitesays so), before authentication, so a web page the developer visits cannot drive the emulator, even an operation served unsigned. SDKs and CLIs send neither header.
Em português: o emulador recusa uma requisição que um browser mandou de outro site (o Origin ou o Sec-Fetch-Site diz isso), antes da autenticação, pra que uma página que o desenvolvedor visita não consiga controlar o emulador, nem numa operação que dispensa assinatura. SDKs e CLIs não mandam nenhum dos dois headers.
A recusa é um 403 que diz "Requests a browser sends from another site are refused". Então um console que roda só no browser, chamando o emulador com o SDK de JavaScript, não funciona. Um console com backend funciona: o servidor do StackPort chama o emulador com boto3, e o browser só fala com o StackPort.
O StackPort já funcionava assim, menos num lugar. O "Download code" de uma função Lambda mandava o browser pra URL pré-assinada que o GetFunction devolve. O browser não confia no certificado do emulador, e o emulador recusa requisições de outros sites de qualquer jeito. Agora o StackPort baixa o código ele mesmo e repassa pro browser em stream.
2. Um certificado só pra localhost
O certificado cobre localhost, 127.0.0.1 e ::1, e é novo a cada start. O Python recusa ele até você entregar o ca.pem do emulador, que o emulador grava em ~/.aws/emulator/9297/.
O Docker piorou as coisas. No Docker Compose, um container acha o outro pelo nome do serviço, então o StackPort chamaria https://aws-emulator:9297, e esse nome não está no certificado (aws-emulator#23). O exemplo de Compose do StackPort contorna isso: o StackPort entra na rede do emulador (network_mode: "service:aws-emulator"), então, pro StackPort, o emulador é o 127.0.0.1.
Tinha mais uma armadilha. A correção óbvia, definir AWS_CA_BUNDLE pro processo inteiro, substitui os certificados confiáveis do sistema. Um endpoint da AWS de verdade, configurado ao lado do emulador, pararia de confiar na AWS. Por isso, no StackPort, o CA bundle é uma configuração de cada endpoint.
3. Chaves que mudam a cada start
O StackPort guarda os clients boto3 em cache, o que normalmente é uma boa ideia, porque criar um client é lento. Com o AWS Emulator, isso significava que, depois de reiniciar o emulador, o StackPort continuava assinando com as chaves da execução anterior. Toda chamada voltava com "Sign the request with the emulator credentials" até você reiniciar o StackPort também.
Agora o StackPort lê as chaves e o certificado direto de ~/.aws/emulator/<porta>/, e o carimbo dos arquivos (data de modificação, tamanho e inode) faz parte da chave do cache de clients. Um restart grava arquivos novos, o carimbo muda, e a próxima requisição cria um client novo. Não tem nada pra colar nem nada pra reiniciar.
4. Hosts que não existem
Algumas operações da AWS vão pra um host diferente do resto do serviço. O botocore manda o DiscoverInstances do Cloud Map pra data-<host> e o StartSyncExecution do Step Functions pra sync-<host>. Na AWS esses hosts existem. Na sua máquina, data-127.0.0.1 não existe. O guia da AWS desliga esses prefixos de host na AWS CLI e no boto3 com AWS_DISABLE_HOST_PREFIX_INJECTION=true. O StackPort agora faz o mesmo, só pra endpoints locais, então os clients da AWS de verdade continuam iguais.
5. Um teto de 16 MiB
Um PutObject no S3 de 16 MiB ou mais volta como 413 (aws-emulator#67). O StackPort agora envia arquivos de 8 MiB ou mais em partes de 8 MiB, com multipart upload, o que funciona em todo emulador e na AWS.
Erros que dizem o que fazer
A pior parte daquela primeira tentativa não foram as falhas. Foi que todas pareciam iguais. Um serviço que o emulador não implementa, um certificado em que o StackPort não confia e uma chave faltando apareciam todos como "Available, 0 resources", ou como um 500 genérico.
Agora o StackPort separa as falhas em alguns tipos (não implementado, credenciais, permissão, TLS, inacessível) e responde cada uma com o próprio status e uma dica do que mudar. Uma operação que o emulador responde com NotImplemented aparece como "Not supported by this endpoint". Um emulador parado aparece em segundos, em vez de uns 40, porque endpoints locais ganham um timeout de conexão curto e nenhuma nova tentativa.
Os dois problemas que todo mundo encontra primeiro, cada um com o que fazer.
O emulador que não confia em browsers me fez perguntar se o StackPort confiava
Aquele comentário no código ficou na minha cabeça. O AWS Emulator recusa páginas de outros sites porque um desenvolvedor visita muitas páginas, e qualquer uma delas pode mandar requisições pro localhost. O StackPort também escuta no localhost. Ele também guarda credenciais da AWS, às vezes de uma conta de verdade. Então, o que uma página qualquer conseguia fazer com ele?
Mais do que eu gostaria. Uma revisão de como o StackPort trata as requisições achou três problemas que estavam lá muito antes do AWS Emulator:
- Qualquer arquivo da máquina podia ser lido. O fallback que serve o app web pra caminhos desconhecidos também servia
GET /%2Fetc%2Fhosts. - Outros sites podiam mudar os seus recursos. O browser manda requisições cross-site "simples" sem perguntar antes, então uma página que você visitou podia esvaziar uma fila, terminar uma instância ou subir arquivos pro S3 através do StackPort. Dava até pra esconder as suas mensagens do SQS com uma tag
<img>, porque receber uma mensagem esconde ela por um tempo. - DNS rebinding passava pelas checagens de mesma origem. Uma página podia fazer o próprio domínio resolver pra
127.0.0.1e falar com o StackPort como se fosse a página do próprio StackPort.
As correções pegam emprestada a ideia do emulador. O StackPort recusa requisições cross-site na API e no WebSocket com base no Sec-Fetch-Site e no Origin, só responde a browsers que o acessam por localhost, por um endereço IP ou por um nome de host que você permitir, escuta em 127.0.0.1 por padrão e deixa o CORS desligado, a menos que você ligue. Se você usa o StackPort, use a v0.4.7 ou mais nova.
Um emulador novo é uma suíte de testes de graça
Depois, passei pelo StackPort tela por tela contra o AWS Emulator, e continuei achando bugs que não tinham nada a ver com ele. Quase todos também aconteciam nos outros emuladores e na AWS de verdade:
- Os documentos das policies do IAM sempre apareciam vazios: trust policies, inline policies, todas.
- O EC2 contava reservations em vez de instâncias.
- Os downloads do S3 eram umas 14 vezes mais lentos do que precisavam ser, e arquivos com nomes fora do Latin-1 nem baixavam.
- Os horários dos logs apareciam sem fuso horário.
Eles saíram juntos na v0.4.9, "fixes found testing against AWS Emulator". Cada emulador exercita um console de um jeito um pouco diferente, o que faz de cada emulador novo uma suíte de testes de graça.
De "funciona" a um console pra ele
Funcionar não era o objetivo. O AWS Emulator guarda tudo em memória, não guarda log de requisições, e a única rota de admin dele é um health check. Um console consegue preencher parte dessas lacunas:
- Um API Explorer pra tudo o que o StackPort não tem tela. Ele lista todos os serviços que o botocore conhece (436 na versão que testei), monta um formulário pra cada operação a partir dos modelos do próprio botocore e copia a chamada como comando da AWS CLI ou código boto3, já com o setup do emulador.
O API Explorer, apontado pro AWS Emulator.
- Activity: as chamadas de API que o CloudTrail registrou, da mais nova pra mais antiga. O AWS Emulator registra uma dúzia de serviços, mais ou menos.
- Try it pra function URLs do Lambda e stages do API Gateway, que o emulador serve em caminhos como
/_aws/lambda-url/<id>/e/_aws/execute-api/<id>/<stage>/.
Try it: um POST pra uma function URL do Lambda no AWS Emulator.
- Detalhes de conexão pro RDS e o ElastiCache, que o emulador roda em portas de banco de verdade: o endereço, e um comando
psqlouredis-clipra copiar. - Limites ao lado das ações que eles afetam: o teto de 16 MiB ao lado do upload do S3, e os runtimes de Python e Node.js do emulador ao lado do invoke do Lambda.
- Mais 16 serviços no dashboard, chegando a 51.
Adicionar todos esses serviços revelou um último bug. O StackPort criava uma sessão boto3 separada pra cada client, e os clients de cada endpoint ocupavam uns 500 MB. Compartilhar uma sessão por conjunto de credenciais levou a memória de 1 GB pra uns 330 MB com dois endpoints, e a primeira carga do dashboard de 3,3 segundos pra 0,4.
Como abrir o AWS Emulator numa UI web
Suba o emulador como no guia da AWS: o pacote de Linux, ou Docker no macOS e no Windows, que compartilha o ~/.aws/emulator com a sua máquina. Depois:
pip install stackport
AWS_ENDPOINT_URL=https://127.0.0.1:9297 stackport
# Abra http://localhost:8080O StackPort acha as chaves e o certificado sozinho. Pra rodar os dois no Docker, tem um arquivo de Compose que builda o emulador a partir do Dockerfile da AWS (a AWS não publica imagem pronta) e cria alguns recursos de exemplo:
curl -O https://raw.githubusercontent.com/DaviReisVieira/stackport/main/examples/docker-compose.aws-emulator.yml
docker compose -f docker-compose.aws-emulator.yml up -d
# Abra http://localhost:8080O StackPort é um projeto open source independente, sem afiliação com a AWS. O mesmo console funciona com o MiniStack, o projeto parceiro dele, e com Floci, LocalStack, Moto e a AWS de verdade. Tem mais em stackport.cloud.
Respostas rápidas
O AWS Emulator tem UI? Não. O README diz "It has no graphical interface". Você usa ele pela AWS CLI ou por um SDK, ou por um console separado, como o StackPort.
Dá pra usar o AWS Management Console com o AWS Emulator? Não. O console da AWS só funciona com a própria AWS.
Por que o meu browser recebe "Requests a browser sends from another site are refused"? O AWS Emulator recusa qualquer requisição cujo header Origin ou Sec-Fetch-Site diga que ela veio de outro site, antes até de conferir a assinatura. Mande a requisição de um servidor, de uma CLI ou de um teste, não de uma página web.
Como aponto o boto3 ou a AWS CLI pro AWS Emulator? Defina AWS_ENDPOINT_URL=https://127.0.0.1:9297, aponte AWS_CA_BUNDLE, AWS_SHARED_CREDENTIALS_FILE e AWS_CONFIG_FILE pros arquivos em ~/.aws/emulator/9297/ e defina AWS_DISABLE_HOST_PREFIX_INJECTION=true. O guia da AWS tem a lista completa.
Por que as minhas chaves pararam de funcionar depois que reiniciei o emulador? Ele cria chaves novas e um certificado novo a cada start. Leia de novo de ~/.aws/emulator/9297/, ou suba o emulador com --auth off pra trabalho local, o que desliga a checagem de assinatura.
Por que uma chamada vai pra data-127.0.0.1 ou sync-127.0.0.1? É o prefixo de host que o SDK usa em operações como o DiscoverInstances do Cloud Map e o StartSyncExecution do Step Functions. Defina AWS_DISABLE_HOST_PREFIX_INJECTION=true.
Por que um upload pro S3 falha com 413? O AWS Emulator recusa corpos de PutObject de 16 MiB ou mais. Use multipart upload. O aws s3 cp já faz isso sozinho com arquivos grandes.
O AWS Emulator guarda os meus dados depois de um restart? Não. Ele guarda tudo em memória, então um restart começa de uma conta vazia.
Obrigado
Ao criador do MiniStack, por responder "StackPort ;)" antes de eu saber que alguém tinha perguntado.
Fontes
- AWS, aws/aws-emulator: o README, e a recusa cross-site no código.
- AWS Emulator User Guide: Pointing your AWS SDK at AWS Emulator, Getting started with Docker, Security.
- Amazon, anúncio do AWS Emulator (11 de novembro de 2026).
- Hacker News, AWS emulator (11 de novembro de 2026).
- Issues do aws-emulator #23 (nomes do certificado), #26 (requisições de browser) e #67 (16 MiB).
- StackPort, releases v0.4.7 a v0.4.11.