Drawing the Boundary: The Hard Type-Split with Terraform

An app team can create only a resource whose lifecycle belongs to that app; a platform team retains network, cluster, and shared IAM foundations. The implementation enforces one owner per cloud object, so controllers cannot reconcile each other’s changes forever.

The type split is a data-ownership rule. Terraform state is the foundation record; etcd is the claim/controller record; provider state is the real cloud record. No cache can arbitrate ownership.

Documentation cannot stop a reconcile war. Label every managed object and reject a Crossplane claim that requests a foundation type; the admission controller interprets this before any provider API call.

metadata:
  labels:
    platform.example.com/owner: crossplane
    platform.example.com/scope: app
spec:
  parameters: { resourceClass: app-bucket }

Declared intent: mark this resource as app-scoped and Crossplane-owned. Interpreter: admission policy and composition controller. Software effect: an invalid foundation class is denied before managed-resource creation. Hardware effect: only controller/API-server CPU is used on denial; successful reconciliation later allocates cloud capacity. Evidence: policy denial log for foundation-network and a successful inventory query for the labelled bucket.

Terraform and an in-cluster controller both reconcile continuously. If a single cloud object is ever owned by both, each will revert the other's changes in an endless loop — a reconcile war with no winner. So the boundary is not documentation; it is the invariant that keeps the system stable. The safe configuration is two disjoint domains, no cloud object owned by both.

Rule of thumb: the type-split is not a style preference, it is the precondition that prevents two reconcilers from co-managing one object — design it as an invariant you can enforce, not a convention you hope people follow.

The classification collapses to a single question about lifecycle and sharing. Everything else is noise.

Owned by one app, created and destroyed with it, referenced only by it → app-scoped (controller). Shared across apps, part of the network/security/account perimeter, or longer-lived than any single app → foundation (Terraform).

The messy case is not classification — it is a grant that crosses the line. An app-scoped identity (controller-owned) frequently needs access to a foundation resource: permission to decrypt with a shared KMS key, or to read a shared bucket. The dangerous shortcut is to let the controller write a policy attachment onto the foundation object. Now two systems manage one object again, and the boundary has leaked.

The convention that keeps the split clean: the controller owns the app-side principal; Terraform owns any grant on a foundation resource. The app requests access through its claim; the foundation plane issues the grant on its own object. The controller never writes policy onto something Terraform owns.

Rule of thumb: when access must cross the boundary, split the two halves — the requesting principal belongs to the self-service plane, the grant on the shared resource belongs to the foundation plane — so that no single cloud object ever has two owners.

There is a reason to start app-scoped and greenfield: if you never migrate an existing Terraform-managed resource, there are no shared objects at all during the pilot, so boundary leakage cannot physically happen yet. New app-scoped resources are created fresh under the controller; everything Terraform holds today stays exactly where it is. Migration of existing resources is explicitly out of scope — you don't move a service's current role out of Terraform state into the controller, you mint a new per-service identity and bind the workload to it.

A clean split on day one erodes unless something enforces it, because every tempting shortcut involves the self-service layer reaching across the line. The defence is layered, each layer independent so a gap in one is caught by the next.

When Terraform and Crossplane can both reconcile the same cloud object, each controller can undo the other's work and neither state record remains trustworthy. The target state assigns foundation resources to Terraform and single-service resources to Crossplane, with explicit grants crossing the boundary without transferring ownership.

On the right, each object has exactly one lifecycle owner and one authoritative state record. The access grant is intentionally visible as a relationship between the planes: it permits use of a shared foundation capability without letting the application claim create, update, or delete that foundation resource.

• Two continuously-reconciling systems make disjoint object ownership the only stable configuration; the type-split is that invariant.
• The classification is one axis — lifecycle plus sharing: single-app-and-dies-with-it → controller; shared/perimeter/long-lived → Terraform; ambiguous → default to foundation and raise it.
• The hard case is the cross-boundary grant: the controller owns the app-side principal, Terraform issues the grant on its own foundation object — never the reverse.
• Greenfield-first makes boundary leakage impossible during the pilot because nothing is migrated and no object has two owners.
• Keep the boundary honest with layered enforcement (schema, composition, admission, cloud permission boundary) and, eventually, a machine-checkable ownership registry.

• [ ] I can explain why overlapping ownership causes a reconcile war and why disjoint ownership is the only stable state.
• [ ] I can apply the lifecycle-plus-sharing test to a new resource and say what to do when the answer is ambiguous.
• [ ] I can describe a cross-boundary grant and split it correctly: app-side principal to the controller, grant-on-foundation to Terraform.
• [ ] I can explain why greenfield-first removes the worst boundary failure mode during the pilot.
• [ ] I can list the layered enforcement controls and explain why one control is not enough to keep the boundary honest.