Everything You Need to Know About Generated Infrastructure and Drift

Generated infrastructure is configuration that a tool writes from a higher-level description: a Dockerfile from a service definition, a routing file from a list of services, a build config from a project manifest. The generator is the source of truth, and the output is a build artifact.

Drift happens when someone changes the output by hand. The next generation overwrites the change, or the output and the description stop agreeing. Either way, the system behaves differently from what the team thinks it does.

Why people edit generated files

Usually the reason is reasonable. The generated file is missing one setting, the fix is obvious, and editing the output is faster than changing the generator. The change works, and nobody records it.

The cost arrives later, when the next generation silently removes the fix, or when a different machine generates a different file from the same input.

The rule

Edit the input or the generator. Regenerate the output. Never treat the output as the place to make changes.

Generated files usually carry a header saying so. Read it, and respect it.

Detecting drift

A robust setup detects drift automatically:

1. Record a snapshot of each generated file when the generator writes it.
2. Compare the current files with the snapshots before the system starts or the build runs.
3. Fail with the name of the file that changed, rather than starting with an unknown configuration.
4. Offer a fix, which is usually regenerating from the input.

This turns a silent problem into a loud one, at the point where it is cheapest to fix.

Where generation fits

Generation is most useful when the same description produces many outputs that must agree. A port declared once appears correctly in the Dockerfile, the routing config, and the build config. Changing it in one place is safer than keeping three files in step by hand.

TDK CLI works this way for local stacks. Each service has a service.json, and TDK writes its runtime files under .autogenerated/. Before tdk up starts Tilt, it compares those files with saved snapshots. A hand edit blocks startup and names the file. tdk up --dry-run runs the same comparison without starting containers, and tdk config verify checks the wider project.

Limits

Drift detection catches changes to generated files. It does not catch a wrong description. If the input is wrong, the output is consistently wrong, and the check passes.

Summary

Treat generated output as a build artifact. Edit the source, regenerate, and detect drift with snapshots before anything runs. Drift checks protect the system from silent hand edits, but the input still needs review.