Platform Architecture Best Practices

This list distills how to design an internal developer platform that shortens developer time-to-production without loosening safety.

The practices are grouped by theme so you can adopt them in order or cherry-pick the ones your platform is missing.

How to Use This List

Read the group headings first to find the area you are weakest in.

Treat each bold practice as a check against your current platform, and note where reality diverges from the ideal.

Adopt the security and delivery groups before the polish, since they set the guardrails everything else relies on.

Revisit the list quarterly, because a platform is a living product and its defaults drift as the stack evolves.

A - Product Mindset

Treat the platform as a product. Its customers are your developers, its metric is their time-to-production, and it needs a roadmap and support model.
Measure adoption and delivery. Track golden-path adoption and DORA-style metrics; low adoption signals a path that is too rigid or incomplete.
Avoid the ticket-queue trap. Deliver capability through self-service Git and policy, not through a platform team that manually fulfills requests.
Design escape hatches early. Give advanced teams a documented, reviewed way to extend a path so they never have to bypass the platform.
Gather feedback continuously. Fold developer pain points into the roadmap; a path nobody uses is a defect, not a preference.

B - Golden Paths and Abstraction

Cover the common case, not every case. Build two or three workload archetypes (web API, worker, cron) and push variation into values, not new templates.
Bake defaults into templates. Encode resource requests, probes, security context, and NetworkPolicy once so developers never hand-write them.
Version every path. Ship paths as semantically versioned charts or bases, with changelogs and a deprecation window for old versions.
Expose a small contract. Let developers set a handful of values and generate full manifests; the smaller the input, the higher the adoption.
Keep developer contracts cloud-neutral. Isolate provider specifics behind the platform so applications stay portable across clouds.

C - Security and Guardrails by Default

Enforce the restricted Pod Security Standard. Require runAsNonRoot, dropped capabilities, no privilege escalation, and RuntimeDefault seccomp on every workload.
Template plus policy, always. Templates make the safe config easy; admission policy (Kyverno or Gatekeeper) makes the unsafe config impossible after apply.
Default-deny the network. Ship a default-deny NetworkPolicy in every namespace and open only the flows each service needs.
Use hardened base images. Prefer distroless or minimal bases pinned by digest, and scan images with Trivy or Grype in CI.
Sign and verify images. Sign artifacts with cosign and verify signatures at admission so only trusted images run.

D - Delivery and Fleet Management

Deliver everything through GitOps. Reconcile clusters from Git with Argo CD or Flux so Git is the single source of truth and the audit log.
Ban manual cluster writes. Disable direct kubectl apply access to production so clusters stay reproducible rather than becoming snowflakes.
Provision clusters as code. Use Cluster API or managed control-plane APIs so a new cluster is repeatable, not hand-built.
Roll upgrades through environments. Upgrade dev, then staging, then production, staying inside supported minors (1.34 to 1.36; 1.33 is EOL).
Separate blast radius deliberately. Prefer a cluster per environment with namespaces per team, splitting production regionally only when required.

E - Operations and Cost

Set requests, limits, and autoscaling. Require resource requests, add HPAs, and use a node autoscaler like Karpenter so capacity follows demand.
Instrument the golden path. Wire OpenTelemetry, Prometheus, and Grafana into templates so every service is observable by default.
Buy the control plane. Use managed Kubernetes unless sovereignty, air-gap, or edge forces self-management; own the platform, not etcd.
Right-size before scaling out. Consolidate under-utilized nodes and non-production clusters before adding more infrastructure and more upgrades.
Own the shared-responsibility boundary. Document what the provider secures versus what you must, and close every gap on your side.

When You Are Done

You should be able to trace a developer's change from a small Git commit to a hardened, observable, policy-compliant deployment with no manual steps.

Every workload should carry requests, probes, a restricted security context, and default-deny networking without a developer remembering any of it.

Your clusters should be reproducible from Git, upgradable on a known cadence, and separated so a non-production incident cannot reach production.

If any of those is untrue, start with the security and delivery groups, since they are the foundation the rest depends on.

FAQs

Where should we start if the platform is greenfield?

Build one golden path with baked-in security defaults and GitOps delivery. Prove time-to-production on it before adding archetypes or clusters.

How do we stop teams from bypassing the platform?

Make the golden path the fastest safe option, back it with admission policy that blocks unsafe alternatives, and provide a real escape hatch.

How many clusters should we run?

Default to a cluster per environment with namespaces per team. Add regional or tenant clusters only when isolation or latency requirements demand it.

Do we need both templates and policy?

Yes. Templates set good defaults at creation time; policy keeps them enforced after apply, preventing drift toward unsafe configuration.

How often should we revisit these practices?

Quarterly. The stack and workloads evolve, so defaults, versions, and archetypes need periodic review to stay relevant.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).

Buscar en la documentación

Platform Architecture Best Practices