Platform Engineering is just API Design

Most internal developer platforms (IDPs) fail because they are built by people who hate developers.

They start with a ticket. Then they build a UI with thirty buttons. Then they wonder why everyone still pings @devops-oncall in Slack to ask why their pod is stuck in ImagePullBackOff.

We spent eighteen months building infra for teams that just wanted to ship code. Here is what we actually learned.

The Dashboard Fallacy

If you build a GUI for your platform, you’ve already lost.

UIs are impossible to version control. They don't compose. They favor the casual user over the power user, and your developers are, theoretically, power users.

Every time you add a dropdown menu to 'configure ingress,' you’re hiding a complexity that will eventually leak. When it leaks, the developer won't know how to fix it because they only know the dropdown.

Your platform should be a CLI and a set of YAML schemas that live in the repo. If a developer can't git grep their infrastructure configuration, your platform is a black box.

We spent three months on a React-based service catalog. Nobody used it. We replaced it with a catalog-info.yaml and a CLI tool called g11. Adoption went up 400% in a week.

Standards are not Suggestions

Fragmentation kills velocity. If one team uses Helm and another uses Kustomize, your shared platform isn't a platform. It's a museum of bad decisions.

Pick a stack. Enforce it.

At git11, we tell teams: you get GitHub Actions, Terraform, and EKS. You want to use Pulumi? Cool, do it on your own time, but we won't support it when your state file gets corrupted at 3 AM.

Internal platforms are about reducing cognitive load. You cannot reduce load if every service has a bespoke deployment pipeline.

A good platform is a set of guardrails, not a cage. But those guardrails need to be made of steel, not rope.

The 'Golden Path' is usually a swamp

Everyone talks about the Golden Path. It sounds great in a slide deck. In reality, it usually means 'the one way we know how to deploy a Hello World app.'

As soon as a team needs a specialized database or a custom sidecar, the Golden Path ends. They fall off a cliff into the 'Silver Swamp' where they have to write 500 lines of HCL manually.

Your platform needs to be an onion, not a path.

The core should handle the basics: IAM, networking, VPCs. The layers above should be composable modules.

If a developer needs a Redis instance, they shouldn't ask you for one. They should add redis: true to their app-config.yaml. If they need a specific version, they override it.

Don't build paths. Build APIs that scale from 'defaults' to 'expert mode' without breaking the mental model.

Your CI is your UI

The most important part of your platform is the output of your CI/CD runner.

If your build fails and spits out 400 lines of Jenkins logs that nobody can read, your platform is broken. Developers spend 80% of their infra time debugging why a build failed.

Invest in error messages. We wrote a wrapper around kubectl that parses common errors and suggests fixes.

Instead of OOMKilled, it says: 'Your memory limit is 512Mi, but your app tried to use 600Mi. Increase the limit in g11.yaml.' This saved us roughly 10 hours of support tickets per week.

Stop buying expensive monitoring tools and start writing better if/else blocks in your scripts to catch known failure modes.

The 'Dev' in DevOps is silent

Platform teams often forget they are building a product for humans.

We tracked our 'Time to First Hello World.' For a new hire, it was four days. That is an insult.

We audited the process. It involved joining six Google Groups, requesting access via a legacy Jira board, and installing a specific version of Python.

We automated the access requests through a single GitHub PR. We used Dev Containers to standardize the environment. High-fives all around.

If your onboarding takes more than an hour, your platform is a failure of empathy. Fix the friction, not the features.

Stop building, start deleting

The best platform engineers are lazy.

Every line of code you write for your platform is a line you have to maintain during an incident. If a cloud provider releases a managed service that does 80% of what your custom tool does, delete your tool.

We had a custom-built secrets management layer. It was beautiful. It was also a nightmare to patch. We ditched it for AWS Secrets Manager and a small CRD.

Your job isn't to be clever. Your job is to make the infrastructure disappear so the application engineers can focus on things that actually make money.

Don't build a platform because it's trendy. Build it because you're tired of answering the same questions twice.

Everything else is just noise.