AWS Emulator : déployer son infrastructure Terraform en local, sans compte AWS
- Published on
- Authors

- Name
- Sylvain BRUAS
- @sylvain_bruas
Il y a une friction que tout le monde connaît quand on développe de l'infrastructure sur AWS : pour vérifier qu'un terraform apply passe, il faut un compte, des credentials, un backend d'état distant, et l'acceptation de voir apparaître (et facturer) de vraies ressources. Pour un site statique comme ce CV — un bucket Amazon Simple Storage Service (S3), une distribution Amazon CloudFront, une poignée de policies — c'est beaucoup de cérémonie juste pour valider que le code tient debout.
AWS Emulator répond précisément à ce besoin : une seule commande, aws-emulator, qui expose les API des services AWS en HTTPS sur 127.0.0.1:9297. L'AWS Command Line Interface (AWS CLI), les SDK et — ce qui nous intéresse ici — le provider Terraform fonctionnent sans modification, une fois pointés vers l'émulateur. Aucun compte AWS, aucune facture, un état entièrement local. Cet article raconte la mise en place de bout en bout sur ce projet, avec les commandes réelles et, surtout, les limites rencontrées en chemin.
Le problème : valider une infrastructure sans la déployer pour de vrai
L'infrastructure du site est du Terraform classique, découpé en deux modules :
- un module S3 : le bucket d'hébergement, le blocage d'accès public, la configuration de site statique et le versioning ;
- un module CloudFront : la distribution, un Origin Access Control, deux cache policies (HTML et assets statiques), et une CloudFront Function qui redirige
/vers/fr/au bord.
Le provider.tf pointe vers un backend S3 distant avec verrou Amazon DynamoDB, et un provider AWS Certificate Manager (ACM) en us-east-1 pour le certificat. Autrement dit : rien ne tourne sans un vrai compte AWS correctement configuré. Pour un simple contrôle « est-ce que mon plan est cohérent et mon apply passe », c'est disproportionné. L'émulateur permet de rejouer exactement ce cycle en local.
Ce qu'apporte AWS Emulator
L'idée est de substituer, au niveau du endpoint réseau, les vraies API AWS par un serveur local qui parle le même protocole (SigV4, mêmes formes de requêtes et de réponses). Concrètement :
- Une seule commande, un seul port.
aws-emulatorécoute sur127.0.0.1:9297et sert les API en HTTPS avec un certificat régénéré à chaque démarrage. - Natif Linux, conteneurisé ailleurs. L'émulateur tourne nativement uniquement sous Linux. Sur macOS et Windows, on le fait tourner dans un conteneur construit à partir du package Linux.
- Credentials d'émulateur. À chaque démarrage, il écrit un couple clé/secret jetable (les access keys commencent par
EMULATOR) et unca.pem. Toutes les requêtes s'exécutent dans le compte000000000000. - État en mémoire. Tout disparaît à l'arrêt du processus : pas de persistance, pas de nettoyage à faire.
- Compatibilité outillage. L'AWS CLI, les SDK et le provider Terraform
hashicorp/awsfonctionnent sans patch : il suffit de rediriger le endpoint et de fournir les credentials de l'émulateur.
Mise en place pas à pas
1. L'émulateur dans un conteneur (via Colima)
Sur macOS, pas de binaire natif : on construit une image à partir du package RPM de la dernière release, puis on lance le conteneur sur la boucle locale uniquement, télémétrie désactivée.
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ARG TARGETARCH
RUN case "$TARGETARCH" in arm64) a=aarch64 ;; amd64) a=x86_64 ;; *) exit 1 ;; esac \
&& curl -fsSLo /tmp/aws-emulator.rpm \
"https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-$a.rpm" \
&& rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
&& mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
ENV PATH=/opt/aws-emulator/bin:$PATH
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
Un détail qui coûte une première erreur : le builder Docker legacy (celui de Colima sans buildx) ne renseigne pas automatiquement TARGETARCH — c'est une fonctionnalité de BuildKit. Il faut donc passer l'architecture explicitement :
docker build --build-arg TARGETARCH=arm64 -t aws-emulator ~/.aws/emulator-build
Puis on démarre le conteneur, publié uniquement sur 127.0.0.1, et on attend le health check plutôt qu'un sleep arbitraire :
mkdir -p ~/.aws/emulator/9297
docker run -d --rm --name aws-emulator \
--network aws-emulator \
--cap-drop ALL --security-opt no-new-privileges --read-only \
-p 127.0.0.1:9297:9297 \
-e EMULATOR_TELEMETRY=off \
-v "$HOME/.aws/emulator/9297:/home/emulator/.aws/emulator/9297" \
aws-emulator
for i in $(seq 30); do
curl -sf --cacert ~/.aws/emulator/9297/ca.pem \
https://127.0.0.1:9297/__admin/health && break
sleep 1
done
On vérifie qu'on tape bien l'émulateur et pas le vrai AWS — le compte doit être 000000000000 :
( . ~/.aws/emulator/9297.env && aws sts get-caller-identity )
# {
# "Account": "000000000000",
# "Arn": "arn:aws:iam::000000000000:user/emulator"
# }
2. Rediriger Terraform vers l'émulateur, sans toucher au code versionné
Le code Terraform ne doit pas être modifié : on s'appuie sur le mécanisme des fichiers *_override.tf, qui fusionnent avec les blocs existants. Trois fichiers locaux, non commités, suffisent.
Backend local (backend_override.tf) — on remplace le backend S3/DynamoDB par un fichier d'état local, pour ne pas chercher à joindre le vrai AWS :
terraform {
backend "local" {
path = "emulator.tfstate"
}
}
Provider redirigé (provider_override.tf) — on pointe chaque service vers l'émulateur, avec les credentials jetables et les skip_* qui évitent les appels de validation vers AWS :
provider "aws" {
region = "us-east-1"
access_key = "EMULATOR...." # lu dans emulator_credentials
secret_key = "...."
custom_ca_bundle = "/Users/sbruas/.aws/emulator/9297/ca.pem"
skip_credentials_validation = true
skip_metadata_api_check = true
skip_region_validation = true
skip_requesting_account_id = true
endpoints {
s3 = "https://127.0.0.1:9297"
cloudfront = "https://127.0.0.1:9297"
acm = "https://127.0.0.1:9297"
sts = "https://127.0.0.1:9297"
iam = "https://127.0.0.1:9297"
}
}
Le provider aliasé us_east_1 (pour ACM/CloudFront) reçoit le même traitement. Enfin, un emulator.auto.tfvars fournit la variable obligatoire bucket_name.
3. init, plan, apply
Tout se joue dans un sous-shell qui source le fichier d'environnement de l'émulateur, pour qu'aucun credential réel ne fuite :
cd infrastructure
( . ~/.aws/emulator/9297.env && terraform init -reconfigure )
( . ~/.aws/emulator/9297.env && terraform plan -out=emulator.tfplan )
( . ~/.aws/emulator/9297.env && terraform apply -auto-approve emulator.tfplan )
Résultat :
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.
Outputs:
bucket_arn = "arn:aws:s3:::sylvain-bruas-cv-website"
cloudfront_distribution_url = "127.0.0.1:33947"
distribution_id = "E1MJV490Q2CKJ1"
Et on vérifie côté émulateur que les ressources existent vraiment, plutôt que de se fier au seul code de sortie de Terraform :
( . ~/.aws/emulator/9297.env && aws s3api list-buckets --query 'Buckets[].Name' )
( . ~/.aws/emulator/9297.env && aws cloudfront list-distributions \
--query 'DistributionList.Items[].{Id:Id,Status:Status}' --output table )
Le bucket sylvain-bruas-cv-website et la distribution E1MJV490Q2CKJ1 (statut Deployed) répondent présents. En quelques minutes, le cycle complet plan → apply → vérification tourne en local, sans compte AWS et sans un centime de facture.
Limites et points d'attention
C'est la partie la plus importante. L'émulateur est excellent pour valider un flux, mais il reproduit les API, pas l'intégralité du comportement d'AWS. Plusieurs limites sont voulues par conception et ne se contournent pas.
Le plafond de 1000 objets par bucket n'est pas configurable
En uploadant le build du site (aws s3 sync out/), l'upload s'est arrêté net :
An error occurred (ValidationException) when calling the PutObject operation:
the bucket "sylvain-bruas-cv-website" already holds the maximum of 1000 objects
this emulator keeps per bucket; delete an object before writing "robots.txt"
Sur 1543 fichiers locaux, 1000 seulement ont été acceptés. La question se pose naturellement : peut-on relever ce plafond ?
Réponse : non. Après revue de toutes les options de l'émulateur, ce plafond de 1000 objets par bucket est codé en dur dans le build et n'est exposé par aucun réglage :
- aucune option de ligne de commande (
aws-emulator -hne propose que le port-p, l'adresse de bind-b, les signatures-a, la télémétrie-tet--idle-timeout) ; - aucune variable d'environnement dédiée ;
- aucun fichier de configuration :
~/.aws/emulator/config.tomlne gère que la télémétrie, et leconfigécrit par run est réservé aux SDK.
C'est une limite de la même famille que les autres contraintes by-design : état en mémoire uniquement, un seul compte et une seule région par émulateur, pas d'évaluation des politiques de ressources. Le seul moyen de « libérer » de la place est de supprimer des objets existants du bucket. En pratique, pour un site volumineux, on teste donc le flux de déploiement sur un sous-ensemble (par exemple en excluant un dossier d'images lourd) plutôt que de viser un upload exhaustif. Ce plafond est propre à l'émulateur : un vrai bucket S3 n'a pas de limite de nombre d'objets.
Les politiques de ressources ne sont pas évaluées
La aws_s3_bucket_policy avec sa condition AWS:SourceArn est bien créée, mais sa restriction d'accès n'est pas réellement appliquée. L'émulateur ne refuse jamais une requête signée avec ses propres clés : il n'est pas conçu pour tester AWS Identity and Access Management (IAM), les bucket policies, les key policies d'AWS Key Management Service (KMS) ni les accès inter-comptes. Valider une logique d'autorisation reste du ressort d'un vrai compte (ou d'un outil d'analyse de politiques statique).
CloudFront + OAC : on ne teste pas le comportement, seulement la structure
C'est le corollaire concret des deux limites précédentes, et une question qui revient vite : puis-je, en local, servir les fichiers du bucket via CloudFront pour vérifier que l'Origin Access Control (OAC) est bien en place ? La réponse est non, pour deux raisons qui s'additionnent :
- Pas de plan de données CloudFront. L'émulateur implémente les API de contrôle (
CreateDistribution,GetDistribution,ListDistributions), ce qui suffit à Terraform pour créer la distribution et récupérer unDomainNameet unId. Mais il n'existe pas d'edge/CDN qui serve réellement le contenu : leDomainNamerenvoyé (ici127.0.0.1:33947) n'est qu'une valeur d'API, rien n'écoute dessus pour aller chercher un objet dans S3, appliquer les cache policies ou exécuter la CloudFront Function/ → /fr/. Uncurlsur ce domaine ne renvoie pas la page du site. - Pas d'évaluation des politiques de ressources. L'OAC repose entièrement sur l'autorisation : la bucket policy n'accorde
s3:GetObjectque si lePrincipalest le service CloudFront et queAWS:SourceArncorrespond à l'ARN de la distribution. Comme l'émulateur n'évalue jamais ces politiques, il ne peut pas vous dire si l'OAC « laisse passer » unGETvia CloudFront ni s'il « bloque » unGETdirect sur S3.
Ce que l'émulateur confirme malgré tout, c'est que la configuration est structurellement correcte : la distribution existe, l'OAC est créé (signing_behavior = "always", signing_protocol = "sigv4") et rattaché à l'origine, et la bucket policy est posée avec le bon Principal, la bonne Action et la bonne condition SourceArn. C'est déjà utile pour éliminer fautes de frappe et ARN mal câblés. Le comportement runtime, lui, ne se vérifie que contre un vrai compte. Le test de référence, à lancer sur un environnement réel (staging) :
#!/usr/bin/env bash
# verify-oac.sh — à exécuter contre un VRAI compte AWS, pas l'émulateur.
set -euo pipefail
DISTRIBUTION_ID="${1:?usage: verify-oac.sh <distribution-id> <bucket> <key>}"
BUCKET="${2:?bucket manquant}"
KEY="${3:-index.html}"
REGION="${AWS_REGION:-eu-west-1}"
DOMAIN=$(aws cloudfront get-distribution --id "$DISTRIBUTION_ID" \
--query 'Distribution.DomainName' --output text)
echo "== 1. Via CloudFront (doit répondre 200) =="
curl -s -o /dev/null -w " https://%{url_effective} -> %{http_code}\n" \
"https://$DOMAIN/$KEY"
echo "== 2. Accès direct S3 (doit répondre 403 grâce à l'OAC) =="
curl -s -o /dev/null -w " https://%{url_effective} -> %{http_code}\n" \
"https://$BUCKET.s3.$REGION.amazonaws.com/$KEY"
echo
echo "OAC OK si : étape 1 = 200 ET étape 2 = 403."
echo "Si l'étape 2 répond 200, le bucket est accessible directement : l'OAC ne protège rien."
En amont du déploiement, une analyse statique complète le tableau : relire que la bucket policy n'ouvre rien d'autre que CloudFront, et que le public_access_block est bien actif sans ACL publique résiduelle.
L'état est en mémoire, et il n'y a qu'un compte / une région
À l'arrêt du conteneur (docker stop aws-emulator), tout disparaît : aucune persistance, aucune route de reset — on redémarre le processus pour repartir propre. De même, l'émulateur accepte n'importe quelle région mais ne cloisonne pas les ressources par région ni par compte : pour tester plusieurs régions, on lance un émulateur par région, chacun sur son port.
Couverture par build, et le piège TLS
Une opération non implémentée renvoie NotImplemented (HTTP 501) : c'est une lacune de couverture du build installé, pas une erreur de configuration. Enfin, comme le conteneur réécrit le chemin du ca.pem en chemin interne, il faut garder AWS_CA_BUNDLE pointé sur le ca.pem côté hôte — et ne jamais désactiver la vérification TLS.
Recompiler l'émulateur ? Oui, mais pas pour contourner une limite
L'émulateur est open source (dépôt aws/aws-emulator, écrit en Rust) : on peut le cloner et le compiler avec cargo build. C'est pertinent pour contribuer, corriger une divergence de comportement, ou l'utiliser en mode embarqué dans des tests Rust (état par test, sans endpoint ni certificat). En revanche, recompiler une version patchée juste pour relever le plafond de 1000 objets est déconseillé : on s'écarte alors du build officiel, de ses corrections de sécurité et du périmètre de compatibilité garanti. Pour tester fidèlement un gros volume d'objets, c'est un vrai bucket S3 qu'il faut, pas une build maison.
Bonnes pratiques
- Isoler les overrides. Mettre toute la config spécifique à l'émulateur dans des fichiers
*_override.tf/*.auto.tfvarsnon commités, pour ne jamais toucher au code Terraform de production. - Toujours la dernière release. Ne pas épingler de version de l'émulateur : les corrections et les nouvelles couvertures n'arrivent que sur la dernière release. Reconstruire l'image avec
--no-cachepour la rafraîchir. - Loopback uniquement. Publier le port sur
127.0.0.1exclusivement, jamais sur0.0.0.0côté hôte. Garder les vrais credentials AWS hors de tout shell qui parle à l'émulateur (le fichier.envfait leunset). - Attendre le health check. Boucler sur
GET /__admin/healthavant le premier appel, pas unsleepfixe. - Vérifier la ressource, pas le code de sortie. Un
applyqui se termine sans erreur ne prouve rien : relister les ressources créées via l'API confirme le résultat. - Tester un sous-ensemble quand le volume dépasse les limites. Face au plafond de 1000 objets, cibler ce qui valide réellement le flux plutôt qu'un upload complet.
Comparaison : AWS Emulator face à Floci
AWS Emulator n'est pas seul sur ce créneau. Parmi les alternatives récentes, Floci se positionne sur le même besoin — un cloud local pour développer et tester sans compte réel — mais avec un périmètre et des partis pris sensiblement différents. La confronter aide à cadrer quand chacun est pertinent.
Ce que proposent les deux outils
Le point commun est net : un endpoint local qui parle le protocole AWS, des credentials jetables, un état éphémère, et la promesse de « pas de compte, pas de facture, pas de rayon d'impact ». Les deux visent explicitement les boucles de développement et d'intégration continue, et les deux se prêtent au dry run d'infrastructure-as-code (Terraform, OpenTofu, AWS CloudFormation) contre localhost avant de toucher un vrai compte.
Les différences qui comptent
- Périmètre cloud. AWS Emulator se concentre sur AWS. Floci est multicloud : il propose des émulateurs distincts pour AWS, Azure, GCP et OCI, chacun sur son propre port, utilisables isolément ou en parallèle. Si votre stack déborde d'AWS, c'est un argument.
- Largeur de couverture annoncée. Floci met en avant environ 135 services AWS et se présente comme un remplaçant direct de LocalStack (même override d'endpoint SDK, mêmes options CLI). AWS Emulator ne communique pas sur un décompte de services : sa couverture s'évalue par build, opération par opération, via un compatibility check.
- Approche « vrais moteurs ». Floci revendique l'exécution sur des moteurs réels pour certains services — AWS Lambda dans de vrais conteneurs Docker, Amazon Relational Database Service (RDS) sur de vrais PostgreSQL/MySQL, Amazon ElastiCache sur Redis — là où AWS Emulator reste une réimplémentation des API (et, on l'a vu, n'exécute pas les déclencheurs Lambda du flux Amazon Cognito, par exemple).
- Démarrage et empreinte. Floci annonce un démarrage de l'ordre de 24 ms et une empreinte mémoire très basse (image native GraalVM), pensés pour tenir dans la boucle d'édition. AWS Emulator démarre vite également, mais le premier lancement sur macOS passe par la construction de l'image conteneur.
- Licence et modèle. Floci se présente comme MIT, sans inscription, sans clé d'API, sans palier payant. AWS Emulator est également open source ; sa télémétrie est en revanche activée par défaut et se désactive explicitement (
-t off/EMULATOR_TELEMETRY=off), ce qu'on prend soin de faire ici. - Positionnement « agents ». Floci insiste sur l'usage par des agents de codage (un skill dédié, des règles à coller dans
AGENTS.md/CLAUDE.md) : donner à un agent un cloud « qu'il ne peut pas casser ». AWS Emulator sert le même objectif de bac à sable, mais sans ce discours produit centré agents.
Vérification sur machine : ce que Floci fait vraiment ici
Pour ne pas s'en tenir au discours commercial, Floci a été lancé en conteneur (image floci/floci, v2.5.0, via Colima) et confronté au même scénario que ci-dessus : terraform apply de l'infra S3 + CloudFront, upload du build, puis requêtes HTTP. Trois constats concrets ressortent, qui tranchent avec AWS Emulator sur ce cas précis.
-
Pas de plafond de 1000 objets. Là où AWS Emulator refuse au-delà de 1000 objets par bucket, Floci a accepté la totalité des 1543 fichiers du build sans broncher.
-
CloudFront sert réellement le contenu. C'est la différence décisive pour « tester son site ». Sur Floci, l'output
cloudfront_distribution_urlest un vrai nom de domaine (xxxx.cloudfront.net), et une requêteGET /index.htmlavec l'en-têteHostcorrespondant renvoie le HTML réel de la page servie depuis le bucket (HTTP 200, contenu<html lang="fr">…). Avec AWS Emulator, la même distribution n'est qu'une entrée d'API : rien n'est servi. Floci permet donc effectivement de voir le site s'afficher derrière un CloudFront local — pas AWS Emulator. -
Mais l'OAC n'est pas « vraiment » appliqué, et la CloudFront Function non plus. Deux nuances importantes :
- L'accès direct au bucket (hors CloudFront) renvoie lui aussi 200 au lieu du 403 attendu avec un OAC réel. Comme AWS Emulator, Floci n'évalue pas la bucket policy côté S3 : le test OAC « CloudFront=200 / S3 direct=403 » échoue des deux côtés sur ce point. Servir le contenu n'est pas prouver que l'accès direct est verrouillé.
- La CloudFront Function
/ → /fr/n'est pas exécutée :GET /renvoie directement le HTML (en-têtesx-amz-*d'un objet S3) au lieu d'un301vers/fr/.
-
Télémétrie : rien n'est sorti, vérification réseau à l'appui. Floci a été lancé derrière une règle
iptables(côté VM Colima) qui bloque et compte tout paquet du conteneur vers une IP publique, les plages privées restant autorisées. Après le scénario complet (AWS Security Token Service (STS), création des 10 ressources, upload de 1543 objets, nombreuxGETCloudFront) et une période d'inactivité, le compteur de paquets bloqués est resté à 0. Aucune tentative d'émission vers l'extérieur n'a été observée : sur cette version et ce scénario, Floci n'a envoyé aucune donnée de télémétrie. (La preuve est observationnelle — elle vaut pour ce qui a été exercé, pas une garantie absolue sur tous les chemins de code.)
Quand préférer l'un ou l'autre
Pour valider la structure Terraform d'une infra AWS simple (S3 + CloudFront) depuis un poste macOS avec Colima, AWS Emulator fait le travail sans dépendance supplémentaire. Mais pour réellement afficher le site derrière un CloudFront local — ou pour dépasser le plafond de 1000 objets — Floci a l'avantage net : il sert le contenu, AWS Emulator non. Floci est aussi pertinent si le besoin s'élargit (plusieurs clouds, couverture plus large, moteurs réels pour Lambda/RDS/Redis, intégration agents).
Dans les deux cas, la même règle d'or subsiste, et les tests ci-dessus la confirment : ces outils valident la structure et la mécanique d'appels, pas le comportement de sécurité. Ni l'un ni l'autre ne prouve qu'un OAC verrouille l'accès direct au bucket, ni n'exécute fidèlement une CloudFront Function. La validation finale de l'OAC et du edge se fait contre un vrai compte.
Conclusion
AWS Emulator transforme la boucle de validation d'infrastructure : on rejoue plan, apply et l'inspection des ressources en local, en quelques minutes, sans compte AWS, sans facture. Pour un projet comme ce CV statique, c'est le moyen le plus rapide de s'assurer qu'un changement Terraform tient la route avant de le pousser vers un vrai compte.
La clé est de garder en tête ce qu'il n'est pas : un substitut d'AWS. L'état est éphémère, les politiques de ressources ne sont pas évaluées, la couverture dépend du build, et certaines limites — comme le plafond non configurable de 1000 objets par bucket — sont codées en dur. Voyez-le comme un banc d'essai local haute fidélité : parfait pour cadrer et déboguer vite, mais la validation finale, elle, se fait toujours contre le vrai service.

