How work is performed
The computation itself — reusable, and identical regardless of where it runs.
Investigation 029 - Platform Evolution Principles
The identity returned.
Does it know its role?
Two copies of the same executable are running. Both reconnect successfully. Both carry a stable, recognized identity. One should behave as a web server. The other should process payments.
Begin the investigation downCopy A
identity confirmed
Copy B
identity confirmed
Intended role
unresolved
Prologue
Hundreds of identical servers. Hundreds of different jobs.
A software company runs the exact same executable on hundreds of machines. No source code differs. Yet some processes receive customer traffic, some execute background jobs, some process payments, some collect telemetry. The executable is identical; only the intended behavior differs.
Foundation
INV-028 gave every process stable, discoverable identity across replacement.
Assumption
Knowing who returned should be enough to know what it is meant to do.
Incident
Configuration values declare intent, not observed reality — a request to change one database endpoint quietly triggers a full software release.
Mystery
How does a process discover what it is supposed to do without making behavior inseparable from the software itself?
First Principles
An executable is a mechanism. Something must supply its intent.
A light switch does not choose whether it powers a lamp or a fan; its behavior depends on what it is wired to. An executable is similar: it can perform work, but it does not inherently know which work it should perform. There are only two places that intent can live.
Where, when, under what conditions
Declared values such as a database endpoint or cache size — stated intent, not observed reality.
Delivered, or merely declared?
Platform delivery or availability observations may be delayed and do not by themselves prove a process consumed a value. Every value in this investigation is treated uniformly as ordinary, non-confidential configuration; whether that simplification holds remains unresolved.
Changing how software performs work is a software problem. Changing what software should do is an operational problem.
Naive Architecture
One executable owns everything.
The database endpoint, the cache size, and every feature-behavior decision are compiled directly into the executable alongside its computation. Choose the artifact, run it, and nothing else is required.
Executablelogic + db endpoint + cache size + feature behavior
Running Processone self-contained artifact
The Architecture That Almost Worked
Self-contained. Reproducible. Simple — for one environment and one owner.
Every copy of the executable behaves identically. There is no external dependency that might be missing, no configuration service that might be unavailable. For a single application in one environment, owned by one team, this is a reasonable and even ideal design.
One artifact, one lifecycle
Nothing is externally coordinated; every change naturally belongs in the software.
Operational changes stay rare
The moment operational behavior must change, that change enters the executable's build, test, approval, release, and deployment lifecycle.
The first signs of change will not look like software bugs. They will look like ordinary operational requests.
Breaking Our Design
Four independent pressures test embedded operational intent.
Each experiment starts from its own clean state and stops at its assigned discovery.
EPISODE 01
The Software Release Trap
Pressure. The production database is being replaced. The executable's computation does not change — only the destination of that computation does.
Prediction. Changing one network address should be routine.
Experiment
Establish the executable performing unchanged computation, change the one production database endpoint, then force the software lifecycle to run.
Observation
The computation is identical to before. Only the operational destination changed.
Failure
A build, a test pass, a release, and a deployment are all required before the new address takes effect.
Discovery
Operational intent changes more frequently than executable logic — yet coupling them forces every operational change through the full software lifecycle.
Next pressure
If this cost repeats per environment, how many nearly identical artifacts result?
Boundary
Environment multiplication, ownership, and platform-wide scale are not tested here.
Change one production database endpoint and force a release.
Computationnot established
Database endpointnone
Release pipelineidle
Executable revision1
Prediction: changing one address should be routine. Establish the executable to find out.
EPISODE 02
The Environment Explosion
Pressure. The same computation must now run in development, staging, and production — then in customer, region, and disaster-recovery variants.
Prediction. A handful of environments should be manageable.
Experiment
Start from one production artifact, add development and staging, then add customer, region, and disaster-recovery variants.
Observation
The computation stays identical in every environment. Only the surrounding values differ.
Failure
Architecture's only response is to build another executable per environment; the artifact count grows past what anyone can track.
Discovery
Environments differ in intent, not software — and the artifact count grows with every environment variant.
Next pressure
Who should actually be allowed to change these environment-specific values?
Boundary
Ownership is not resolved here.
Add environment variants and count the resulting artifacts.
Computationnot established
Environmentsnone
Artifacts0
Phasenot started
Prediction: a handful of environments should be manageable. Establish production to find out.
EPISODE 03
The Ownership Problem
Pressure. The application team owns the executable carrying the embedded database endpoint. The platform operator needs that endpoint changed.
Prediction. The team operating the environment should be able to change an operational value directly.
Experiment
Establish the application team's ownership of the embedded value, have the platform operator request a change, then wait for the application team to release it.
Observation
The platform operator cannot make the change directly; the value is trapped inside application-owned software.
Failure
A simple infrastructure change now waits on tickets, coordination, and an application release.
Discovery
Operational intent belongs to the platform that operates the environment; the ownership mismatch between application and platform creates coordination overhead.
Next pressure
What happens when this same mismatch repeats across every application the platform serves?
Boundary
Organization-wide scale and the final contract are not derived here.
Request a platform change trapped inside application-owned software.
Endpoint ownernot established
Platform requestnone
Coordinationnone
Resolutionnot attempted
Prediction: the operator should be able to change this directly. Establish ownership to find out.
EPISODE 04
The Platform Bottleneck
Pressure. A platform supports 100 applications. A new security policy requires every application to trust a new certificate authority.
Prediction. A platform-wide policy change should not depend on 100 separate teams.
Experiment
Establish 100 applications trusting the current authority, trigger the policy change, and observe the fan-out across repositories, pipelines, and releases.
Observation
Business logic is unchanged in every application; only the operational environment evolved.
Failure
100 repositories become active, 100 pipelines run, and the platform's own progress now depends on the slowest application team.
Discovery
Independently changing responsibilities need independent lifecycles.
Next question
What contract would let the platform and the applications evolve without this dependency? Chapter 07 formalizes it only after all four episodes are complete.
Boundary
The final two-owner contract is not formalized in this episode.
Fan a single platform policy change across 100 applications.
Applicationsnot established
Policy changenone
Active pipelines0
Platform dependencynone
Prediction: a platform-wide change should not depend on 100 teams. Establish the fleet to find out.
Review the four experiments
- Operational intent changes more frequently than executable logic, yet coupling forces every operational change through the software lifecycle.
- Environments differ in intent, not software — the artifact count grows with every environment variant.
- Operational intent belongs to the platform that operates the environment; ownership mismatch creates coordination overhead.
- Independently changing responsibilities need independent lifecycles.
The Turning Point
The responsibilities change independently.
Must their ownership separate?
Executable Logichow work is performed
Operational Intentowner unresolved
Environmentchanges independently
Four failures have made shared lifecycle untenable. Chapter 07 must now determine the ownership boundary.
The Configuration Contract
Two responsibilities. Independent change.
Contract not yet earned. Complete all four experiments before formalizing the contract.
The executable owns how work is performed. The platform owns the operational intent that describes where, when, and under what conditions that work should be performed.
Immutable, reusable artifact
The same artifact executes in development, staging, and production without change.
Owns operational intent independently
Environment-specific values follow their own lifecycle, separate from software releases.
This contract does not specify how operational intent is stored, how it is delivered, whether updates apply live or only at restart, or how values are validated, templated, or composed. Whether every operational value deserves identical treatment is not decided here.
Only Now: Kubernetes
ConfigMap realizes the boundary — nothing more.
Kubernetes realizes the configuration contract through the ConfigMap API object: a platform-managed collection of non-confidential key-value pairs, owned and delivered independently of the executable. A Pod can consume a ConfigMap's data as environment variables, command-line arguments, or mounted files; the delivery mechanics beyond that are intentionally left high-level here.
Platform-managed resource
ConfigMap data is owned by the platform, not embedded inside the executable image.
Multiple delivery paths
Environment variables, command arguments, or mounted files can all expose the same values.
No guarantees implied
ConfigMap does not guarantee that an application consumed a value, that propagation is instant or current, that the value is schema-valid, or that a restart or reload occurred.
Immutable ConfigMaps exist as a platform option, but immutability is a policy and implementation choice, not something this contract requires. Not all configuration is necessarily delivered only at process startup. ConfigMap treats every value it holds as ordinary, non-confidential configuration; whether some operational values require a different architectural contract is reserved for INV-030.
Engineering Reflection
Timeless Engineering Principle
A system becomes easier to evolve when responsibilities that change for different reasons are owned independently. Executable logic describes how work is performed. Operational intent describes where, when, and under what conditions that work should be performed.
Architectural Honesty
Keep intent embedded
A single application in one environment, rarely changing behavior, owned by one team, where rebuilding is inexpensive — externalizing intent here adds complexity without solving a real problem.
Externalize operational intent
Operational behavior changing independently of software, across multiple environments and teams, is where the configuration contract becomes necessary rather than optional.
Costs Accepted
Configuration becomes another platform-managed resource with its own lifecycle.
Applications now require operational intent to be available before execution begins.
Configuration evolves on its own schedule, separate from software releases.
The platform must keep operational intent available, consistent, and appropriate for every process.
Investigation Exercise
One computation. Three environments. Count the artifacts.
An executable is deployed to development, staging, and production; only the database endpoint differs. Predict how many artifacts and releases changing only the production endpoint should require.
Compare an endpoint compiled into the executable with one supplied by the platform at startup.
Both architectures perform identical computation. Only one requires rebuilding, retesting, and redeploying software.
When the environment changes without the software changing, why should the software lifecycle be involved at all?
Complete all four experiments before running the synthesis trace.
Bridge to INV-030
Operational intent has an owner.
Does every value deserve equal trust?
A process no longer needs to carry its operational intent inside the executable.
The platform owns that responsibility, and Kubernetes realizes it through ConfigMap — key-value data owned and delivered independently of the executable.
Hostnames can often appear safely in logs. Cache sizes may be inspected by operators without consequence.
Would we treat a database password, or a private encryption key, with that same visibility?
Some configuration merely tells software how to operate. Some configuration grants the authority to operate at all — and that distinction remains unresolved.
Intellectual Lineage
This investigation inherits architectural decomposition and independent responsibility from earlier investigations. The Twelve-Factor App documents the source-grounded practice of separating configuration that varies between deployments from executable code. Kubernetes ConfigMap is one realization of the broader configuration boundary derived here; this investigation does not claim that ConfigMap invented separation between software and operational intent.
Deliberate Simplifications Ledger
Runtime delivery through environment variables, mounted files, or APIsFuture: Configuration Delivery (unassigned)
Different treatment for authority-bearing operational valuesINV-030 - The Secret Distribution Problem
Dynamic configuration updates and propagation across a running fleetFuture: Configuration Propagation (unassigned)
Consistency guarantees while configuration changes during a deploymentFuture: Configuration Consistency (unassigned)
Sources
- Kubernetes Documentation — ConfigMaps
- Kubernetes Documentation — Configure a Pod to Use a ConfigMap
- The Twelve-Factor App — Config
- Designing Data-Intensive Applications — Martin Kleppmann
- The Practice of System and Network Administration — Limoncelli, Hogan, Chalup