Internal Developer Platform Design Patterns

How to design and build an internal developer platform. Covers golden paths, self-service infrastructure, developer experience metrics, and platform team operating models.

Internal Developer Platform Design Patterns

This page collects the recurring structural patterns that appear when engineering teams build or evolve an Internal Developer Platform (IDP). It matters when you find yourself repeating the same scaffolding steps, when onboarding latency creeps up, or when different teams independently converge on incompatible abstractions. The patterns below are not prescriptions; they are documented solutions to problems you will actually hit, written so you can map them to whatever runtime or workflow your platform uses.

Spin Up a New Service Template

What the reader is trying to do Create a minimal, consistent starting point for a new service so that individual teams don’t have to assemble base images, directory structures, and CI configs from scratch.

Concrete pattern A common approach is a version‑controlled “service scaffold” checked into the platform repo. Teams invoke it with a single command:

git clone https://platform.example.com/servicetemplates/go-service.git my-new-service
cd my-new-service
helm dependency build
helm install . --name my-new-service -n dev

The scaffold includes a Chart.yaml with appVersion set to the platform’s runtime baseline, a values.yaml that references platform‑managed secrets via {{ .Values.secrets.{{ .Release.Name }}.apiKey }}, and a Dockerfile that builds against the organization’s base image tag stored in a constants.yaml file consumed by the CI pipeline.

Sharp edges

Parameterize Across Environments

What the reader is trying to do Promote a single Helm chart or Docker image through dev, staging, and prod without copy‑pasting configuration or maintaining forked charts.

Concrete pattern Use kustomize patches layered over a base Helm chart. The base chart lives in platform/helm/charts/my-service/, and each environment has a kustomization.yaml:


resources:
  - ../helm/charts/my-service
patchesStrategicMerge:
  - values-prod.yaml
# environments/dev/values-prod.yaml
replicaCount: 1
image:
  tag: dev-1234
# environments/prod/values-prod.yaml
replicaCount: 3
image:
  tag: registry.example.com/my-service:1.4.0

Promotion is then a matter of applying the correct kustomize overlay:

cd environments/prod
kustomize edit set image my-service=registry.example.com/my-service:1.5.0
kubectl apply -k .

Sharp edges

Make the Service Discoverable

What the reader is trying to do Ensure that any new service registers itself with the platform’s DNS and service‑mesh routing without manual edits to ingress or config maps.

Concrete pattern Leverage a service‑mesh control plane (e.g., Istio, Linkerd) combined with automatic sidecar injection and a wildcard ingress. The platform sets a default ClusterIssuer for TLS and a Gateway resource that matches *.platform.example.com. A service’s Service definition uses metadata.labels that the mesh watches:

apiVersion: v1
kind: Service
metadata:
  name: my-service
  labels:
    app: my-service
    platform.example.com/ingress-host: my-service.platform.example.com
spec:
  selector:
    app: my-service
  ports:
    - port: 80
      targetPort: 8080

The ingress controller is configured with:

# Example using NGINX Ingress Controller with a platform‑managed values file
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install nginx-ingress ingress-nginx/ingress-nginx \
  --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path"/=/
  --set controller.extraArgs=--default-backend-service=default/nginx-backend

Sharp edges

Embed Observability Without Duplication

What the reader is trying to do Add structured logging, metrics, and tracing to every service with a single platform‑level configuration, avoiding per‑team SDK integration bugs.

Concrete pattern Deploy a cluster‑wide OpenTelemetry Collector as a DaemonSet, and configure the Kubernetes kube‑state‑metrics and prometheus‑adapter to scrape standard metrics. Services opt‑in by setting environment variables that the sidecar injector reads:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
        - name: my-service
          env:
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: service.name=my-service,deployment.environment=prod
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: http://otel-collector:4317
          image: o11y/base-image:latest

The collector itself is configured via a ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: otel-collector-config
data:
  config.yaml:
    receivers:
      otlp:
        protocols:
          grpc:
    processors:
      batch:
    exporters:
      logging:
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch]
          exporters: [logging]

Sharp edges

Gate Changes Through GitOps

What the reader is trying to do Ensure every configuration change passes through a review pipeline, is tracked in Git, and is applied automatically, reducing “shadow” changes made directly to clusters.

Concrete pattern Use Argo CD or Flux as the canonical source‑of‑truth engine. The platform repo contains applications.yaml objects that declaratively describe the desired state:

# platform/gitops/applications/my-service.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://platform.example.com/platform.git
    targetRevision: HEAD
    path: environments/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

A developer updates the Helm chart version in a feature branch, opens a PR, and Argo CD automatically syncs the application once the CI pipeline (e.g., gitlab-runner or github-actions) passes. The selfHeal flag ensures that if someone manually patches a Deployment outside Git, Argo CD reverts it on the next sync loop.

Sharp edges

Consolidated Sharp Edges

These patterns map to the structural decisions any IDP inevitably reaches. They are written generically—using standard CLI tools (kubectl, helm, git, Argo CD, Flux, OpenTelemetry Collector)—so you can translate each example to the runtime, secret‑store, and Git‑ops system your organization actually uses. The “sharp edges” sections capture the failure modes that surface only after a platform has been running at scale, because those are the details that separate a design that looks clean in documentation from one that survives production traffic.

This page was rewritten on 26 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at hello@thegarnetwiki.com and we will correct it.