Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ All notable changes to this project are documented here. The format follows
- `scripts/chaos.py` and a nightly workflow: kill the emulator, keepstack, or everything at once in the middle of
`terraform apply` and require Terraform to converge. Documented in [how it works](docs/how-it-works.md#crash-safety).

### Changed
- README: leads with Terraform validation (locally and in every pull request), with persistence as the engine;
example of the pull request comment.

## [0.3.0] - 2026-11-13

keepstack becomes a pull-request validator for Terraform: apply every change on the official AWS Emulator, on top of
Expand Down
144 changes: 105 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,12 @@
</picture>
</p>

<h3 align="center">Your local AWS survives restarts.</h3>
<h3 align="center">Test your Terraform on local AWS before it touches the real one.</h3>

<p align="center">
Persistent state for <a href="https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html">AWS Emulator</a>.
Reboot, come back days later, and <code>terraform plan</code> still says <em>No changes</em>.
keepstack gives the official <a href="https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html">AWS Emulator</a> a memory.
Your local infrastructure survives restarts with the same IDs, and every pull request is applied on top of what
<code>main</code> already built. No AWS account, no tokens.
</p>

<p align="center">
Expand All @@ -21,6 +22,7 @@

<p align="center">
<a href="#quick-start">Quick start</a> ·
<a href="#validate-pull-requests">Validate pull requests</a> ·
<a href="docs/how-it-works.md">How it works</a> ·
<a href="docs/compatibility.md">Compatibility</a> ·
<a href="CONTRIBUTING.md">Contributing</a>
Expand All @@ -30,6 +32,33 @@

<br>

## Two ways to use it

<table>
<tr>
<th width="50%">💻 On your machine</th>
<th width="50%">🔁 In every pull request</th>
</tr>
<tr>
<td>

The official AWS Emulator, with a memory. Apply, reboot, come back days later: `terraform plan` still says
*No changes*, with the same VPC IDs, ARNs and data. Add one resource and the plan shows exactly that one.

**→ [Quick start](#quick-start)**

</td>
<td>

One step in GitHub Actions applies the pull request on top of the environment `main` already built and comments the
incremental plan and every problem on the PR: config errors, emulator gaps, non-idempotent resources.

**→ [Validate pull requests](#validate-pull-requests)**

</td>
</tr>
</table>

## The problem

AWS Emulator is AWS's official local emulator: fast and faithful, but **everything lives in memory**.
Expand Down Expand Up @@ -100,6 +129,74 @@ Try the full loop with [`examples/quickstart`](examples/quickstart/main.tf).
> Use **AWS CLI v2**: v1 ignores `AWS_ENDPOINT_URL` for some services (e.g. SQS) and would call real AWS.
> In Terraform, copy the `provider` block from the [quickstart example](examples/quickstart/main.tf).

## Validate pull requests


Add one step and every pull request that touches your infrastructure gets applied on the official AWS Emulator, with
no AWS account and no tokens:

```yaml
# .github/workflows/infra.yml
on:
push:
branches: [main]
pull_request:

jobs:
validate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # for the PR comment
steps:
- uses: actions/checkout@v7
- uses: sanlega/keepstack@v0.3.0
with:
validate: infra/ # your Terraform directory
baseline: true # validate PRs on top of main's environment
shims: true
run: pytest tests/smoke # optional: check the resources really work
```

- **Job summary and a sticky PR comment** with the plan, the steps and every problem found.
- **Inline annotations** on the `.tf` lines that fail.
- **Baseline:** pushes to `main` save the resulting environment; pull requests restore it and are applied on top, so
the report shows the real incremental plan (replacements, destroys, `moved` blocks) instead of a greenfield apply.
Other local emulators start from an empty account on every run.

The comment it leaves on the pull request (this one caught a replacement and a resource that is not idempotent):


> ### keepstack validate: `infra` ❌ failed
>
> | Step | Result |
> |---|---|
> | init | ✅ ok |
> | plan | ✅ ok |
> | apply | ✅ ok |
> | idempotency | ❌ failed |
> | smoke | ✅ ok |
>
> **Plan:** 1 to add, 1 to change, 1 to replace, 0 to destroy
>
> > [!WARNING]
> > Destructive changes:
> > - `aws_sqs_queue.jobs` will be **replaced**
>
> | | Kind | Resource | Message |
> |---|---|---|---|
> | 🔁 | not idempotent | `aws_dynamodb_table.items` `main.tf:58` | plan is not empty after apply (update)<br>*Hint:* keepstack up --shims, or lifecycle { ignore_changes = [on_demand_throughput] } |
>
> <details><summary>Planned changes</summary>
>
> - `create` aws_subnet.b
> - `replace` aws_sqs_queue.jobs
> - `update` aws_dynamodb_table.items
>
> </details>
>
> <sub>keepstack · 52.3 s · AWS Emulator, no AWS account used</sub>

## Everyday commands

| Command | What it does |
Expand Down Expand Up @@ -204,42 +301,10 @@ translations and your snapshots. It only answers on `127.0.0.1`.

## In GitHub Actions

### Validate every pull request

Add one step and every pull request that touches your infrastructure gets applied on the official AWS Emulator, with
no AWS account and no tokens:

```yaml
# .github/workflows/infra.yml
on:
push:
branches: [main]
pull_request:

jobs:
validate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # for the PR comment
steps:
- uses: actions/checkout@v7
- uses: sanlega/keepstack@v0.3.0
with:
validate: infra/ # your Terraform directory
baseline: true # validate PRs on top of main's environment
shims: true
run: pytest tests/smoke # optional: check the resources really work
```

- **Job summary and a sticky PR comment** with the plan, the steps and every problem found.
- **Inline annotations** on the `.tf` lines that fail.
- **Baseline:** pushes to `main` save the resulting environment; pull requests restore it and are applied on top, so
the report shows the real incremental plan (replacements, destroys, `moved` blocks) instead of a greenfield apply.
Other local emulators start from an empty account on every run.

### Just a local AWS

Pull-request validation is described [above](#validate-pull-requests).

Without `validate`, the action only starts keepstack and points the AWS CLI, SDKs and Terraform at it:

```yaml
Expand Down Expand Up @@ -272,10 +337,11 @@ needs a Linux runner (Docker with Linux containers) and installs Terraform if th

| | |
|---|---|
| 🔁 **Survives everything** | Ctrl+C, `docker kill`, Docker restarts, reboots. If the container dies, keepstack restores it on its own. |
| 🧪 **Validate pull requests** | `keepstack validate` applies your Terraform locally and tells config errors apart from emulator gaps and non-idempotent resources, with file and line. |
| 🧱 **Incremental, like production** | Pull requests are applied on top of `main`'s environment, so replacements and destroys show up before they reach AWS. |
| 🔁 **Survives everything** | Ctrl+C, `docker kill`, Docker restarts, reboots, even a crash in the middle of `terraform apply`. Exercised every night by a [chaos suite](docs/how-it-works.md#crash-safety). |
| 🪪 **Stable IDs** | `vpc-…`, KMS UUIDs, Secrets Manager ARNs, Route 53 zone IDs… keep their original values across restarts. |
| 🔍 **Know before you apply** | `keepstack check` tells you what will break on the emulator before you run Terraform. |
| 🧪 **Validate pull requests** | `keepstack validate` applies your Terraform locally and tells config errors apart from emulator gaps and non-idempotent resources. |
| 📸 **Snapshots** | Save, restore and share whole environments, Terraform state included. |
| 🩹 **Compatibility shims** | `--shims` works around known emulator bugs (e.g. `aws_security_group`), off by default. |
| ⚡ **Zero setup** | One command, no config. The emulator image builds itself (x86_64 and Apple silicon). |
Expand Down
144 changes: 105 additions & 39 deletions docs/i18n/README.es.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,12 @@
</picture>
</p>

<h3 align="center">Tu AWS local sobrevive a los reinicios.</h3>
<h3 align="center">Prueba tu Terraform en un AWS local antes de tocar el real.</h3>

<p align="center">
Estado persistente para <a href="https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html">AWS Emulator</a>:
reinicia, vuelve días después y <code>terraform plan</code> sigue diciendo <em>No changes</em>.
keepstack le da memoria al <a href="https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html">AWS Emulator</a> oficial.
Tu infraestructura local sobrevive a los reinicios con los mismos IDs, y cada pull request se aplica sobre lo que
<code>main</code> ya construyó. Sin cuenta de AWS ni tokens.
</p>

<p align="center">
Expand All @@ -21,6 +22,7 @@

<p align="center">
<a href="#inicio-rápido">Inicio rápido</a> ·
<a href="#valida-pull-requests">Valida pull requests</a> ·
<a href="../how-it-works.md">Cómo funciona</a> ·
<a href="../compatibility.md">Compatibilidad</a> ·
<a href="../../CONTRIBUTING.md">Contribuir</a>
Expand All @@ -32,6 +34,33 @@

<br>

## Dos formas de usarlo

<table>
<tr>
<th width="50%">💻 En tu máquina</th>
<th width="50%">🔁 En cada pull request</th>
</tr>
<tr>
<td>

El AWS Emulator oficial, con memoria. Aplica, reinicia, vuelve días después: `terraform plan` sigue diciendo
*No changes*, con los mismos IDs de VPC, ARN y datos. Añade un recurso y el plan muestra exactamente ese.

**→ [Inicio rápido](#inicio-rápido)**

</td>
<td>

Un paso en GitHub Actions aplica el pull request sobre el entorno que `main` ya construyó y comenta en el PR el plan
incremental y cada problema: errores de configuración, carencias del emulador, recursos no idempotentes.

**→ [Valida pull requests](#valida-pull-requests)**

</td>
</tr>
</table>

## El problema

AWS Emulator es el emulador local oficial de AWS: rápido y fiel, pero **todo vive en memoria**.
Expand Down Expand Up @@ -102,6 +131,74 @@ Prueba el ciclo completo con [`examples/quickstart`](../../examples/quickstart/m
> Usa **AWS CLI v2**: la v1 ignora `AWS_ENDPOINT_URL` en algunos servicios (p. ej. SQS) y llamaría a AWS de verdad.
> En Terraform, copia el bloque `provider` del [ejemplo quickstart](../../examples/quickstart/main.tf).

## Valida pull requests


Con un solo paso, cada pull request que toque tu infraestructura se aplica en el emulador oficial de AWS, sin cuenta de
AWS ni tokens:

```yaml
# .github/workflows/infra.yml
on:
push:
branches: [main]
pull_request:

jobs:
validate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # para el comentario en el PR
steps:
- uses: actions/checkout@v7
- uses: sanlega/keepstack@v0.3.0
with:
validate: infra/ # tu directorio Terraform
baseline: true # valida los PR sobre el entorno de main
shims: true
run: pytest tests/smoke # opcional: comprueba que los recursos funcionan
```

- **Resumen del job y un comentario fijo en el PR** con el plan, los pasos y cada problema encontrado.
- **Anotaciones en línea** sobre las líneas `.tf` que fallan.
- **Baseline:** los push a `main` guardan el entorno resultante; los pull requests lo restauran y se aplican encima, así
que el informe muestra el plan incremental real (reemplazos, borrados, bloques `moved`) en vez de un apply desde cero.
Los demás emuladores locales empiezan con una cuenta vacía en cada ejecución.

El comentario que deja en el pull request (este detectó un reemplazo y un recurso no idempotente):


> ### keepstack validate: `infra` ❌ failed
>
> | Step | Result |
> |---|---|
> | init | ✅ ok |
> | plan | ✅ ok |
> | apply | ✅ ok |
> | idempotency | ❌ failed |
> | smoke | ✅ ok |
>
> **Plan:** 1 to add, 1 to change, 1 to replace, 0 to destroy
>
> > [!WARNING]
> > Destructive changes:
> > - `aws_sqs_queue.jobs` will be **replaced**
>
> | | Kind | Resource | Message |
> |---|---|---|---|
> | 🔁 | not idempotent | `aws_dynamodb_table.items` `main.tf:58` | plan is not empty after apply (update)<br>*Hint:* keepstack up --shims, or lifecycle { ignore_changes = [on_demand_throughput] } |
>
> <details><summary>Planned changes</summary>
>
> - `create` aws_subnet.b
> - `replace` aws_sqs_queue.jobs
> - `update` aws_dynamodb_table.items
>
> </details>
>
> <sub>keepstack · 52.3 s · AWS Emulator, no AWS account used</sub>

## Comandos del día a día

| Comando | Qué hace |
Expand Down Expand Up @@ -206,42 +303,10 @@ de IDs y tus snapshots. Solo responde en `127.0.0.1`.

## En GitHub Actions

### Valida cada pull request

Con un solo paso, cada pull request que toque tu infraestructura se aplica en el emulador oficial de AWS, sin cuenta de
AWS ni tokens:

```yaml
# .github/workflows/infra.yml
on:
push:
branches: [main]
pull_request:

jobs:
validate:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # para el comentario en el PR
steps:
- uses: actions/checkout@v7
- uses: sanlega/keepstack@v0.3.0
with:
validate: infra/ # tu directorio Terraform
baseline: true # valida los PR sobre el entorno de main
shims: true
run: pytest tests/smoke # opcional: comprueba que los recursos funcionan
```

- **Resumen del job y un comentario fijo en el PR** con el plan, los pasos y cada problema encontrado.
- **Anotaciones en línea** sobre las líneas `.tf` que fallan.
- **Baseline:** los push a `main` guardan el entorno resultante; los pull requests lo restauran y se aplican encima, así
que el informe muestra el plan incremental real (reemplazos, borrados, bloques `moved`) en vez de un apply desde cero.
Los demás emuladores locales empiezan con una cuenta vacía en cada ejecución.

### Solo un AWS local

La validación de pull requests está descrita [más arriba](#valida-pull-requests).

Sin `validate`, la acción solo arranca keepstack y apunta a él la AWS CLI, los SDK y Terraform:

```yaml
Expand Down Expand Up @@ -274,10 +339,11 @@ acción necesita un runner Linux (Docker con contenedores Linux) e instala Terra

| | |
|---|---|
| 🔁 **Sobrevive a todo** | Ctrl+C, `docker kill`, reinicios de Docker, reinicios del equipo. Si el contenedor muere, keepstack lo restaura por su cuenta. |
| 🧪 **Valida pull requests** | `keepstack validate` aplica tu Terraform en local y distingue errores de configuración, carencias del emulador y recursos no idempotentes, con fichero y línea. |
| 🧱 **Incremental, como en producción** | Los pull requests se aplican sobre el entorno de `main`, así que los reemplazos y borrados aparecen antes de llegar a AWS. |
| 🔁 **Sobrevive a todo** | Ctrl+C, `docker kill`, reinicios de Docker, reinicios del equipo, incluso un crash en mitad de un `terraform apply`. Lo comprueba cada noche una [suite de caos](../how-it-works.md#crash-safety). |
| 🪪 **IDs estables** | `vpc-…`, UUID de KMS, ARN de Secrets Manager, IDs de zona de Route 53… conservan su valor original tras los reinicios. |
| 🔍 **Sabes antes de aplicar** | `keepstack check` te dice qué fallará en el emulador antes de ejecutar Terraform. |
| 🧪 **Valida pull requests** | `keepstack validate` aplica tu Terraform en local y distingue errores de configuración, carencias del emulador y recursos no idempotentes. |
| 📸 **Snapshots** | Guarda, restaura y comparte entornos completos, estado de Terraform incluido. |
| 🩹 **Shims de compatibilidad** | `--shims` esquiva errores conocidos del emulador (p. ej. `aws_security_group`), desactivado por defecto. |
| ⚡ **Cero configuración** | Un solo comando, sin config. La imagen del emulador se construye sola (x86_64 y Apple silicon). |
Expand Down
Loading
Loading