What category
What category of thing does this record represent?
Investigation 031 - Platform Evolution Principles
Every new kind of state
waits on the platform's release.
The platform understands workloads, network identities, storage claims, configuration, and authority-bearing material. A database team now needs to represent a replicated database as desired state. A security team needs a certificate request. Neither shares the platform's release schedule.
Begin the investigation downWorkload
built in
Storage claim
built in
ReplicatedDatabase
unmodeled?
Prologue
The platform understands the things it accepts.
The platform already knows how to represent resources through one mechanism, and every new kind can use it without anything fundamental changing — as long as the platform team is the one deciding what belongs inside its vocabulary.
Foundation
The platform represents kind identity, instance identity, declared representation, and domain meaning through one existing mechanism.
Assumption
Every request can keep being absorbed as long as the platform remains the one party deciding what belongs inside its vocabulary.
Incident
A database team needs a replicated database. A security team needs a certificate request. A hardware team needs a device allocation. None shares the platform's release schedule.
Mystery
How can new kinds of typed desired state become authoritative without modifying the platform core for every new type?
First Principles
A resource is more than stored bytes.
A resource becomes significant when participants can rely on the platform to preserve certain properties about it: a stable kind identity, an instance identity, a declared representation, authoritative persistence, concurrency rules, discovery, ownership, and observable change.
Which record
Which particular stored record of that kind is this?
Which declared shape
Which declared shape is this instance currently expressed through?
Domain concern
The domain understands what the represented state means.
Platform concern
The platform preserves the accepted record according to its own rules.
Authority vs. meaning
Whether the platform can own the first without ever owning the second is what the rest of this investigation must earn.
Meaning and representation differ. The platform may judge structural form without understanding database replication, failover, or health.
Naive Architecture
Embed every resource type in the platform core.
The new kind becomes an ordinary platform resource. One owner controls every definition, and every resource receives the same common guarantees — no second storage system, no second discovery mechanism, no second concurrency model.
Domain RequirementReplicatedDatabase
Platform Core Changedefinition embedded
Platform Releasekind becomes available
The Architecture That Almost Worked
Keep the store. Stop understanding every field.
Let a domain submit a kind label, an instance identity, and an opaque payload. The platform preserves it without embedding the complete definition in core. One source of truth remains. The domain no longer needs a platform release merely to introduce a new kind of state.
One source of truth
The platform's existing authoritative store, ownership metadata, and observation machinery continue to apply without a second system.
Identity without shape
A kind label and an instance identity are treated as enough to accept a payload, with no declared structure to check it against.
The architecture holds only until someone asks the platform to tell a well-formed payload apart from a malformed one.
Breaking Our Design
Four independent pressures test one assumption.
Each experiment starts from its own clean state and tests one prediction. Read the pressure and prediction, then run the experiment to find out what actually happens.
EPISODE 01
The Release Bottleneck
Pressure. One core type is added to the platform. Independent domains begin submitting domain-local changes to it.
Prediction. If the platform team reviews and releases each change promptly, coupling every domain to the platform's release lifecycle should be tolerable indefinitely.
Add a core type, then push a domain-local change through the platform's release boundary.
Core typenot added
Domain-local changenone
Release gatenot required
Outcomenot observed
Prediction: prompt platform review should make this coupling tolerable indefinitely. Add the core type to test it.
EPISODE 02
The Opaque Object Trap
Pressure. Assume release coupling is removed. A domain submits a kind label, an instance identity, and an opaque payload directly into the authoritative store.
Prediction. If the kind label and instance identity are stable, the platform should already have what it needs to tell a conforming payload from a malformed one.
Submit a payload, then submit a malformed one, then attempt a structural check.
Payload submittednone
Malformed payloadnot tried
Structural checknot attempted
Outcomenot observed
Prediction: kind label and instance identity should be enough to judge a payload. Submit a conforming payload to test it.
EPISODE 03
The Parallel Source of Truth
Pressure. Assume the domain owns a separate authoritative store entirely. The platform still records an owning relationship to a record in that store.
Prediction. If each authority stays locally correct, the relationship between them should remain valid without further coordination.
Create the cross-authority relationship, delay observation, then change the record independently.
Owning relationshipnot created
Observationcurrent
Domain recordunchanged
Invariant checknot attempted
Prediction: local correctness in each authority should be enough. Create the relationship to test it.
EPISODE 04
The Shape Is Not the Identity
Pressure. ReplicatedDatabase instance orders-production already has a v1 representation, history, an owner, and watchers. Its declared shape changes.
Prediction. If the resource kind is identified by its current representation, adding a field should be a harmless detail.
Establish the v1 instance, add a field to reach v2, then treat shape as kind and test continuity.
orders-productionnot established
Representationnone
Shape treated as kindnot tested
Continuitynot observed
Prediction: representation is just a detail of the kind. Establish the v1 instance to test it.
Review the four experiments
The Turning Point
Stop asking who owns everything.
Ask for the smallest boundary.
Domain Meaningowned somewhere
Extension Boundary?undetermined split
Platform Guaranteesowned somewhere
Four failures point at a boundary, not yet its exact split. Chapter 07 formalizes the contract once all four experiments are complete.
The Extensible Resource Contract
What is the smallest boundary that survives?
Contract not yet earned. Complete all four experiments before formalizing the contract.
A domain may introduce a new resource kind without modifying the platform core, while instances remain participants in the platform's authoritative resource model. The domain owns what the resource means; the platform owns the narrow contract that makes it a legitimate resource.
Meaning & definition
Resource meaning, definition, declared structure, representation evolution, and domain-specific behaviour.
Authoritative guarantees
Authoritative persistence, structural conformance, discovery, resourceVersion-checked updates, ownership metadata, and bounded observable change.
Not universal inheritance
A custom resource does not automatically receive every capability available to every built-in resource.
ReplicatedDatabase
orders-production
v1 / v2
Kind, instance, and representation identities remain separate. Representation can evolve without redefining the identity of the resource kind.
Only Now: Kubernetes
CustomResourceDefinition is one realization.
A CustomResourceDefinition, or CRD, declares a custom resource kind: its API group, plural and singular names, scope, one or more versions, exactly one version designated for storage, and an OpenAPI v3 structural schema for each version. Any version may independently be marked as served. Once registered, the API server can serve and store instances of that resource through the same common machinery used by built-in resources.
Custom resource instances carry metadata and a resourceVersion, and participate in the platform's common watch machinery exactly as built-in resources do. That watch history remains bounded, and clients may need to relist rather than assume every prior change is retrievable — the same limit established earlier in the book.
A CRD does not automatically grant every capability available to built-in resources: arbitrary storage backends, subresources, semantic transactions across resources, domain behaviour, conversion between versions, and admission policy over proposed instances remain separate mechanisms, and separate investigations. Declaring and storing a custom resource does not make its desired state real.
Group, names, versions
CustomResourceDefinition names the kind, its API group, scope, and one or more versions.
OpenAPI v3 schema
Each version can declare a structural schema the API server enforces before storage.
Common API machinery
Custom resource instances use the same resourceVersion-checked updates and bounded watch mechanism as built-in resources.
Engineering Reflection
Timeless Engineering Principle
Extend the vocabulary without destabilising the guarantees.
Architectural Honesty
Keep a closed vocabulary
One team owns the platform and its resource definitions, the platform has a narrow purpose, resource kinds change infrequently, and no independent release cadences exist.
Open an extension boundary
Domains evolve independently, definitions need declared structure, resources need common platform guarantees, and kind identity must survive representation change.
Costs Accepted
Externally defined resources now enter the authoritative model.
Opaque payloads are no longer sufficient; conformance must be judged.
Kind, instance, and representation identities remain separate concerns to maintain.
Custom resources do not inherit every built-in capability automatically.
Investigation Exercise
Keep kind, instance, and representation distinct.
Design three representations of the same resource kind — replicas and storage, then add a backup policy, then add an encryption policy — while keeping the resource kind and instance identity constant.
Trace ReplicatedDatabase / orders-production through each representation change, noting what the platform records at each step.
Notice that the representation changes while the kind and instance identities remain stable throughout.
Compare this against treating every version as a new kind, or every representation as an opaque payload.
Run the synthesis trace after writing your prediction.
Bridge to INV-032
The declaration exists.
Nothing acts on it.
The domain defined a resource kind.
The platform preserved common guarantees for it.
ReplicatedDatabase remains desired state without domain behaviour.
Representation alone does not change the world.
Who owns the behaviour that makes this desired state become reality?
Intellectual Lineage
This investigation inherits the reconciliation and controller contract from INV-002 and INV-003, and the authoritative resource model from INV-007 and INV-009. Extending a stable core with independently defined types is a long-standing pattern in software architecture; CustomResourceDefinition is one realization of the broader extensible-resource contract derived here.
Deliberate Simplifications Ledger
Reconciliation / controller contractInherited: INV-003
Domain behaviour that makes state realINV-032 - The Automation Problem
Admission decisions beyond structural conformanceINV-033 - The Admission Problem
Cross-resource transactionsFuture (unassigned)
Controller frameworks & implementationFuture (unassigned)