Tutorial: see markers work#

In about two minutes, a real VPC, subnet, security group, S3 bucket and log group will exist inside a local AWS emulator. choudoufu will build them, delete its own state file, and rebuild its bookkeeping from nothing but two tags read straight off those live resources. Then it will drift three of them behind its own back, out of band, and correct exactly what drifted and nothing else. Every claim in this walkthrough is checked by the same run, not described after the fact.

Before you start#

You need Docker, running. docker info must succeed. That’s the whole requirement: no AWS account, no credentials, no cloud spend. The estate stands up inside a pinned local emulator that speaks the AWS API on your own machine.

Run it#

From the root of a checkout of this repository:

bash live/e2e/run.sh --expect 5

The output should look something like this, with a couple of minutes between the first line and the last:

=== 0. choudoufu binary ===
...
=== 1. Floci on :4601 (floci/floci:latest) ===
...
=== 2. standup — init + apply with plain local state ===
...
=== 3. adopt — delete terraform.tfstate(.backup); the non-event is the demo ===
...
=== 6. drift-exact — one mutation per estate type, each exactly one attribute ===
...
=== 13. drift-reconverge — three simultaneous drifts under plain plan/apply ===
...
=== 14. lint-rejects — every limits fixture is refused by its own named rule ===
...
EXPECT 5: OK -- every step phase<=5 is pass, every step phase>5 is not_implemented
PASS: stateless-mode E2E harness reached the end.

Exit code 0 means every one of those steps checked out. Anything else, and the script names the step that didn’t on its way out.

Walk through what just happened#

Notice that step 2, standup, is the least interesting thing OpenTofu does: plain init and apply against a plain local state file, no markers anywhere yet. That’s the baseline every later step gets compared against.

Step 3 is the handover, and it’s almost anticlimactic: the script deletes terraform.tfstate in front of you, and nothing else changes, not the configuration, not the resources sitting in the emulator. That deletion is the entire migration to marker mode. From here on, choudoufu has no state file to read. It rebuilds what it needs to know by reading two tags, tofu-estate and tofu-address, straight off the live resources.

Steps 4 and 5 ask for a plan right after the handover, once with a -target, once for the whole estate. Both come back empty. The output should read this as proof, not assertion: an empty plan means every resource choudoufu just “forgot” was found again, correctly, by its tags alone.

Then the run tests what the tags are for. Step 6 changes one attribute on each of several resource types using the AWS CLI directly, behind choudoufu’s back, and each drift surfaces as exactly that resource and that attribute, with no noise on its neighbours. Step 7 creates a security group choudoufu never declared, and it shows up as foreign, never as something to delete. Step 8 removes a whole resource block from the configuration and watches exactly that live resource get destroyed. Step 13 does three differently-shaped drifts at once and reconverges all three in a single apply.

By step 14, the run turns to what choudoufu refuses. Every fixture under live/e2e/limits/ is a configuration this mode is not yet safe to accept, and the step confirms each one is rejected, by name, for the reason its own fixture claims and no other.

You have just watched choudoufu build a real, emulated AWS estate, hand its own bookkeeping over to tags on the live resources, survive three shapes of drift and a removal without losing track of anything, and refuse the constructs it isn’t ready for, all without touching a credential.

Next#

Backward Two runs at once Use it Forward