The Platform Engineer's Guide: Building an Internal Developer Platform on Kubernetes

The organisation has decided: Kubernetes. Your CTO approved the budget. Your engineering manager set the timeline. Now you, the platform engineer, need to build something that 50+ developers will actually use — without hating it.

This isn't about cluster setup. You know how to run eksctl create cluster. This is about what comes after: building the Internal Developer Platform (IDP) layer that turns raw Kubernetes into a self-service, developer-friendly platform.

Principle: Pave Golden Paths, Don't Build Walls

The goal isn't to restrict what developers can do. It's to make the right thing the easy thing:

• Golden path: The default, opinionated way to do something that works for 90% of cases. It's easy, fast, and pre-configured with best practices.
• Not a wall: Developers CAN deviate from the golden path when they have a legitimate need. They just need to own the additional complexity.

If developers use your golden path, they get CI/CD, monitoring, alerting, security scanning, and compliance controls for free. If they deviate, they're responsible for providing those capabilities themselves.

Layer 1: Namespace-as-a-Service

The most impactful thing you can build first: self-service namespace provisioning with sensible defaults.

What a namespace template should include:

• ResourceQuota: CPU and memory limits per namespace. Prevents one team from consuming the entire cluster.
• LimitRange: Default resource requests and limits for pods. Developers don't need to think about it, but every pod is right-sized.
• NetworkPolicy: Default deny-all ingress, with explicit policies for allowed communication. Zero-trust by default.
• RBAC: Team-scoped roles. Developers can manage their own namespace but can't touch others.
• ServiceAccount: Workload identity with minimal permissions. No default service account token mounting.
• Monitoring: PodMonitor/ServiceMonitor for Prometheus. Every service is scraped automatically.
• Logging: Annotations or labels that configure log forwarding to the central logging stack.

Implementation options:

• Crossplane Compositions: Define a custom resource (Team) that provisions namespace + RBAC + quotas + network policies as a single operation
• Backstage Software Templates: Developer portal where teams click "New Service" and get a namespace + repo + pipeline
• Custom controller: A Kubernetes operator that watches a Tenant CRD and provisions everything. More control, more maintenance.
• GitOps (ArgoCD/Flux): Namespace definitions in a Git repo. PR to create a new namespace. Approval = merge = provisioned.

Layer 2: CI/CD Golden Path

A deployment pipeline that works for every service without per-service configuration:

The pipeline stages:

1. Build: Multi-stage Docker build from a standardised Dockerfile template (or Buildpacks for zero-config)
2. Test: Unit tests + integration tests (developers provide these)
3. Scan: Container image vulnerability scanning (Trivy, Grype). Fail the pipeline on critical CVEs.
4. Push: Push to internal registry with immutable tags (never latest in production)
5. Deploy to staging: Automatic deployment via GitOps or pipeline trigger
6. Smoke test: Health check endpoints. Basic functional validation.
7. Deploy to production: Rolling update with configurable strategy (canary, blue-green, progressive)
8. Verify: Post-deployment health checks. Automatic rollback if health checks fail.

Key decisions:

• GitOps vs. push-based: GitOps (ArgoCD/Flux) is the golden path. Git is the single source of truth. Auditable. Reproducible. Drift detection built in.
• Manifest management: Helm for complex, configurable deployments. Kustomize for simpler, overlay-based customisation. Pick one as the default.
• Progressive delivery: Argo Rollouts or Flagger for canary deployments. Start with rolling updates, add canary as the platform matures.

Layer 3: Observability Stack

Developers should get observability for free by deploying on the platform:

• Metrics: Prometheus + Grafana. Pre-built dashboards per namespace (request rate, error rate, latency — RED metrics). Custom metrics via annotations.
• Logs: Loki or ELK/OpenSearch. Structured JSON logging as the golden path. Auto-collected from stdout/stderr.
• Traces: OpenTelemetry Collector → Tempo/Jaeger. Auto-instrumentation where possible (Java agent, Python auto-instrumentation).
• Alerting: Default alerts for every service: high error rate, high latency, pod restart loops, approaching resource limits. Teams can customise thresholds.

The principle: zero-effort observability. If a developer deploys a service and does nothing else, they should still have dashboards, logs, and basic alerting.

Layer 4: Security Controls

Bake security into the platform so developers don't need to think about it:

• Pod Security Standards: Enforce restricted profile by default. No privileged containers. No root. Read-only root filesystem.
• Network Policies: Default deny. Explicit allow-listing for known communication patterns.
• Secrets management: External Secrets Operator syncing from Vault, AWS Secrets Manager, or Azure Key Vault. Developers reference secrets by name; the platform handles rotation and injection.
• Image policies: OPA/Gatekeeper or Kyverno policies that reject images from untrusted registries, images without vulnerability scans, or images running as root.
• mTLS: Service mesh (Istio, Linkerd) or Kubernetes-native mTLS for service-to-service encryption. Zero config for developers.

Layer 5: Developer Portal

The single pane of glass that ties everything together:

• Backstage is the dominant open-source option. Provides service catalog, software templates, documentation, and plugin ecosystem.
• Service catalog: Every service has an owner, documentation link, SLO, and dependency graph
• Software templates: "Create new service" wizard that generates repo + pipeline + namespace + monitoring
• TechDocs: Docs-as-code, rendered and searchable in one place

The portal is the UX layer. Without it, your platform is powerful but invisible.

Adoption Strategy: Don't Mandate, Attract

The biggest risk isn't technical — it's adoption. Developers will route around a platform they don't like.

• Start with one willing team: Find the team that's most frustrated with current infrastructure. They'll be your most enthusiastic early adopters and best feedback source.
• Make migration easy: If moving to the platform requires a 2-week rewrite, nobody will do it. Provide migration tools and templates.
• Measure and share wins: When the pilot team goes from deploying weekly to daily, publicise it. Success stories drive adoption.
• Treat developers as customers: Run surveys. Track NPS for the platform. Fix the friction points they report.
• Never mandate before you're ready: If the platform isn't reliably better than the current process, forcing migration creates enemies.

What Good Looks Like (Month 12)

• A developer creates a new service via Backstage template. Within 10 minutes: repo exists, pipeline is configured, namespace is provisioned, service is deploying to dev.
• Every service has metrics, logs, traces, and alerting without any per-service configuration.
• Security controls are enforced by the platform. Developers can't accidentally deploy insecure configurations.
• Infrastructure changes are reviewed via PR, applied via GitOps, auditable in Git history.
• The platform team has fewer than 10 support tickets per week because the golden paths handle 90% of use cases.

That's not a scam. That's what good platform engineering looks like.