Use it on choudoufu

Compatibility reference

Mon, 01 Jan 0001 00:00:00 +0000

Compatibility reference#

What choudoufu admits and refuses: the provider and resource types, how a configuration must be written, and how it may be run.

This is the enumerated list. For why static evaluability is the rule behind most of it, see Identity. To check your own configuration against this list, see How to check a configuration before migrating.

Your provider#

AWS only. Every google_*, azurerm_*, kubernetes_* and helm_* resource is refused. There is no second cloud on the roadmap (#5).

How to check a configuration before migrating

Mon, 01 Jan 0001 00:00:00 +0000

How to check a configuration before migrating#

Run choudoufu live-check against any OpenTofu configuration:

choudoufu live-check ./

Point it at any OpenTofu configuration. No live block, no cloud calls, no requirement that the directory has heard of this fork. It prints a verdict, then every refusal that fired with its site count, the types responsible, and what to do about each.

Run choudoufu init first if you can. With provider schemas available it judges types from the provider’s own identity schema as well as the built-in table, and admits more. Without them it says the answer is pessimistic.

Migrate an existing estate

Mon, 01 Jan 0001 00:00:00 +0000

Migrate an existing estate#

Most people arrive here, with an OpenTofu configuration already managing live AWS resources.

Migrating means binding those resources to your configuration, one marker at a time, until each carries its own ownership record. It does not happen automatically and the failure mode is quiet.

Turning on live markers does not bind resources you already manage. A resource with no marker is not yours yet, so the first plan reads it as absent and proposes a second one beside it. Applying that plan does not fail. It creates the duplicate.

Day-2 operations

Mon, 01 Jan 0001 00:00:00 +0000

Day-2 operations#

Running an estate after the first apply. Renaming, removing, recording effects the cloud cannot report, and working with other people.

Task	Page
Rename a resource	How to rename a resource
Stop managing or destroy a resource	How to stop managing or destroy a resource
Record an effect the cloud cannot report	How to record an effect the cloud cannot report
Look up what a `policy` setting does	The ownership policy matrix
Understand what happens when two runs overlap	Two runs at once

There is no remote state to read. live/OUTPUTS.md covers the cross-estate pattern, and data "terraform_remote_state" is refused.

How to rename a resource

Mon, 01 Jan 0001 00:00:00 +0000

How to rename a resource#

Rename the resource block, then rewrite the marker.

choudoufu live-mv aws_vpc.old aws_vpc.new

That rewrites the tofu-address tag on the live resource carrying the old address. The tag write is the move, so moved blocks are refused. Resources never adopted are left alone.

A destination address absent from your configuration is refused unless you pass -allow-missing-config. -dry-run shows what it would write. Full options in choudoufu live-mv -help.

Start a new estate

Mon, 01 Jan 0001 00:00:00 +0000

Start a new estate#

For an estate with nothing in it yet, where choudoufu creates every resource.

If AWS already holds resources this configuration should manage, read Migrate an existing estate first. Nothing binds a live resource to your configuration until its markers are on it, so applying against unmarked resources creates a second copy beside them.

Install#

Every tagged release carries prebuilt binaries for macOS, Linux and Windows on amd64 and arm64, plus a SHA256SUMS file.

Questions

Mon, 01 Jan 0001 00:00:00 +0000

Questions#

Two questions with no other home. Everything else that used to live on this page has a real page now: what changes for you is in The three pieces, self-service tagging and IAM in Scoping a role, storage in Where things are stored, migration in Migrate an existing estate, marker stripping in Identity, and concurrent applies in Two runs at once.

Why is it called choudoufu?#

Stinky tofu. Off-putting at first, and people who like it like it a lot.

How to stop managing or destroy a resource

Mon, 01 Jan 0001 00:00:00 +0000

How to stop managing or destroy a resource#

Deleting a resource block leaves its marker on the live object, and the sweep destroys a marked, undeclared, taggable resource on the next plan. That matches upstream without a removed block.

To stop managing something without destroying it, change what happens to a resource you no longer declare.

# estate.chdf.hcl
estate = "my-estate"

policy {
 undeclared_tagged = "untag"
}

untag removes this estate’s marker and leaves the resource running. keep leaves both alone. The ownership policy matrix has the rest of the verbs.

How to write markers inside a for_each'd module

Mon, 01 Jan 0001 00:00:00 +0000

How to write markers inside a for_each’d module#

Instances of a for_each’d module share one HCL body for tags, so no single literal address is correct for all of them and auto-stamping cannot reach inside. choudoufu leaves such a resource alone when it already declares tags, and raises a must-stamp error when it declares none and its type needs discovery.

Thread the module’s own each.key through and build the address from it.

How to record an effect the cloud cannot report

Mon, 01 Jan 0001 00:00:00 +0000

How to record an effect the cloud cannot report#

Nothing in the live system records that a database migration, a script, or a one-shot API call happened, so no marker reads back.

null_resource, terraform_data, time_* and non-secret random_* work once the live configuration declares a record_store.

# estate.chdf.hcl
estate = "my-estate"

record_store "ssm" {}

The label picks the backend, one of local, ssm or s3. Where things are stored has “Choosing a record store backend” for which one to pick, what each holds, and why a receipt must not go in there. Those resources then run the stock provider lifecycle exactly as upstream.

Where things are stored

Mon, 01 Jan 0001 00:00:00 +0000

Where things are stored#

choudoufu writes in three places. Two can both end up as SSM parameters, which is why they get confused. They do different jobs and have different owners.

What	Where it lives	Who reads it	Losing it costs
Ownership markers	Two tags on the resource itself	choudoufu, and you, with any cloud tool	The resource goes invisible and the next plan proposes a duplicate
Micro-state records	A local directory beside the module unless you declare a `record_store` on SSM or S3	choudoufu only	Churn, since the effect re-runs or its value regenerates
Receipts	Ordinary resources you declare, by convention SSM parameters	You, your reviewers, your incident responder	Nothing structural. It is your data, in your configuration

The first is the product. The second is plumbing that is there by default and that you point somewhere else when a team needs to share it. The third you write yourself, and choudoufu only lints it.

How the compatibility numbers are measured

Mon, 01 Jan 0001 00:00:00 +0000

How the compatibility numbers are measured#

live/corpus-refusals.json measures which refusals fire and how often across the corpus. Compatibility reference copies no count from it, because a copied count goes stale the moment the corpus re-runs.

That measured ranking is why the static-evaluability rule (see Identity) leads the reference page. Several of the most frequent refusals are that one rule under different diagnostics.

Do not read the fixture or module-example populations as a compatibility rate. Module examples/ directories demonstrate a module’s full surface, so they lean far harder on variables, conditionals and dynamic blocks than a configuration describing one deployment, and refuse almost across the board. Those populations are marked as a ranking, settled by #118. One population can honestly carry a rate since #147, whole deployment root modules published by their operators, pinned by commit, marked reads_as: rate.

The ownership policy matrix

Mon, 01 Jan 0001 00:00:00 +0000

The ownership policy matrix#

Every resource choudoufu sees falls into one of four situations, decided by whether your configuration declares it and whether it carries this estate’s marker. The policy block sets what happens in each.

With no policy block you get the defaults below, which are today’s behaviour.

The situation you are in	Setting	Default	What the default does
You declare it, and it carries your marker. The ordinary case.	`declared_tagged`	`converge`	Plans and applies it against your configuration, like any resource.
You declare it, but no live resource carries your marker for it.	`declared_untagged`	`refuse`	Declines to touch it until you adopt it.
You removed it from your configuration, and it still carries your marker.	`undeclared_tagged`	`delete`	Destroys it on the next plan.
It carries no marker, and you never declared it. Somebody else’s.	`undeclared_untagged`	`keep`	Leaves it alone.

The third row is the one to know before deleting a resource block. Removing the block does not mean “stop managing this”, it means “destroy this”, which is also what upstream does without a removed block. Set undeclared_tagged to untag or keep first if the resource should survive. How to stop managing or destroy a resource walks through it.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Reference#

The normative specifications live in the repository beside the code and the tests holding them to it. This page indexes them.

They are for people integrating with choudoufu or working on it. To get an estate running, use the path pages.

Specifications#

Document	What it settles
`live/MARKERS.md`	The marker tag spec. Key names, the escaping rule, continuation tags, ownership semantics, the rename rule, and what protects the tags. The one surface external tooling can rely on.
`live/LIMITATIONS.md`	Every construct the mode bounds or rejects, per rule, each with its lint rule and fixture.
`live/RECEIPTS.md`	Recording an effect that leaves nothing in the live system to read back, and the guards on the pattern.
`live/OUTPUTS.md`	Sharing values between estates with no remote state.

Coverage and evidence#

Document	What it settles
`live/COVERAGE.md`	Which AWS resource types are covered, in layers, and what each layer means.
`live/SURVEY.md`	How admission is decided per type, the method, and the raw signals behind it.

The demo, which is also the test suite#

live/e2e/README.md documents the harness, what each step proves, the environment knobs, and each exit code.

Use it on choudoufu

Compatibility reference

Compatibility reference#

Your provider#

How to check a configuration before migrating

How to check a configuration before migrating#

Migrate an existing estate

Migrate an existing estate#

Day-2 operations

Day-2 operations#

Sharing values between estates#

How to rename a resource

How to rename a resource#

Start a new estate

Start a new estate#

Install#

Questions

Questions#

Why is it called choudoufu?#

How to stop managing or destroy a resource

How to stop managing or destroy a resource#

How to write markers inside a for_each'd module

How to write markers inside a for_each’d module#

How to record an effect the cloud cannot report

How to record an effect the cloud cannot report#

Where things are stored

Where things are stored#

How the compatibility numbers are measured

How the compatibility numbers are measured#

The ownership policy matrix

The ownership policy matrix#

Reference

Reference#

Specifications#

Coverage and evidence#

The demo, which is also the test suite#