The platform is more than the manifests
It is satisfying to put a service into a repository.
The configuration is versioned. The deployment can be reviewed. There is a place to record why something changed. Compared with a collection of half-remembered commands, that is a substantial improvement.
But the repository is not the platform.
Working on my own operations platform keeps bringing me back to that distinction. A manifest can describe what should run. It does not, by itself, explain who is allowed to change it, which state must survive, how to tell whether users can actually use it, or what happens when the deployment needs to be reversed.
Those are not finishing touches. They are part of the thing being built.
Desired state is only one part of the story
I find it useful to separate three things:
- Desired state: what the configuration says should exist.
- Observed state: what is running and what it is doing.
- Operational knowledge: how to change, diagnose, and recover it.
Each can be correct while another is missing.
A deployment can converge successfully while a user cannot sign in. A dashboard can be available while showing only part of the system. The application can look healthy while depending on a configuration file that exists on exactly one machine.
None of those problems is solved by adding another YAML file unless the file addresses the missing relationship.
The question is not just, "Can I deploy this?" It is, "Can I explain how this behaves when the happy path ends?"
Give each service a small operating contract
I do not think every service needs a large operations manual. I do think it needs a few explicit answers.
What does it own? Which other services does it depend on? Where does its durable state live? How are credentials supplied? What evidence counts as healthy? What is the approved way to change it?
Then there is the question that tends to expose the gaps: how would someone recover it without relying on the person who originally installed it?
Consider a dashboard service as a hypothetical example. A useful contract would distinguish the dashboards generated from configuration from the preferences and accounts stored in its database. It would also distinguish an HTTP health check from a successful sign-in and a working data source.
That is a much more useful description than "the dashboard is deployed."
Make the change path obvious
A repository can still contain several competing versions of the truth.
There may be a current deployment method, an older script that mostly works, an emergency command in a chat transcript, and a set of values copied from the last successful release.
The goal is not to pretend that manual intervention never happens. It is to make the normal path clear and the exceptional path deliberate.
For a change, I want to know:
- What will be affected?
- Which checks can run before anything changes?
- What runtime evidence will confirm the intended result?
- What is the recovery plan if that evidence does not appear?
The size of the change matters too. Updating one service should not quietly become an opportunity to reapply unrelated configuration across the platform.
Review becomes more useful when the scope is understandable.
Rollback is a question, not a button
It is tempting to equate rollback with restoring an earlier configuration revision.
That may be sufficient for a stateless change. It may be completely insufficient after a database migration, a credential rotation, or a change to stored application state.
Before making a change, ask what the old version would need to run again. Is the data still compatible? Does the previous credential still exist? Would a restore overwrite changes made since the backup?
Sometimes the answer is a forward fix rather than a rollback. That is fine, provided it is an intentional recovery strategy rather than a surprise discovered during an outage.
Measure the reduction in guesswork
The business value of platform work is not the number of services running or the number of manifests committed.
It is the friction removed from the next useful activity.
Can someone understand a change without reverse-engineering the environment? Can a routine upgrade stay routine? Can an incident be investigated without first reconstructing how the application was deployed?
Those are questions worth measuring: time to diagnose a failed change, manual steps required for recovery, and repeated incidents caused by undocumented dependencies.
I am not presenting a set of measured improvements here. These are the outcomes I want the engineering work to support.
The manifests matter. They are just the beginning of the conversation.