How much should platform teams hide from developers?

Hide by default, but make it inspectable. Let people see the generated manifests even if they never write them.

The abstraction should leak on purpose for logs, events and metrics. Those are what people need when things fail.

We went through three versions of our internal platform and each one taught us something about this.

v1 hid everything. Developers wrote a 12-line service.yaml and got a deployment, service, ingress, HPA and dashboards. Adoption was great. Then the first incident happened and nobody on the product team could answer "is the pod even running?" because they'd never seen a pod.

v2 overcorrected and exposed raw Helm values "for flexibility". Within six months we had 40 services with 40 subtly different configurations and the platform team was debugging other people's Helm templates full-time.

v3, the one that works:

- The input stays small and opinionated. - platform describe <service> prints every generated manifest, with comments explaining where each field came from. - Logs, events and pod status are one click from the service page — no kubectl required, but kubectl still works. - There are exactly three escape hatches (extra env, extra volumes, custom probe), and each one is reviewed.

The lesson: hiding the authoring is good. Hiding the runtime state is not.