Platform Engineering Basics Cheat Sheet
Internal developer platform fundamentals covering golden paths, IDPs, self-service tooling, and platform-as-product concepts.
Core Concepts
Foundational vocabulary for platform engineering and internal developer platforms.
- IDP (Internal Developer Platform)- the self-service layer platform teams build on top of raw infra (Kubernetes, cloud, CI/CD)
- Golden path- an opinionated, supported way to do a common task (e.g. deploy a new service) that's easier than going off-road
- Platform as a product- treating internal developers as customers, with roadmaps, docs, and feedback loops
- Cognitive load reduction- the core value metric: how much infra/ops knowledge a developer needs to hold to ship
- Service/software catalog- a discoverable inventory of services, owners, and their metadata (e.g. Backstage catalog)
- Self-service provisioning- developers request infra (DBs, queues, envs) via templates without filing tickets
Backstage Software Template (Scaffolder)
A minimal golden-path template developers can invoke to create a new service.
apiVersion: scaffolder.backstage.io/v1beta3kind: Templatemetadata: name: node-service title: New Node.js Service description: Scaffolds a service with CI, Dockerfile, and a k8s manifestspec: owner: platform-team type: service parameters: - title: Service details properties: name: type: string owner: type: string steps: - id: fetch name: Fetch skeleton action: fetch:template input: url: ./skeletons/node-service values: name: ${{ parameters.name }} - id: publish name: Publish to GitHub action: publish:github input: repoUrl: github.com?owner=acme&repo=${{ parameters.name }} - id: register name: Register in catalog action: catalog:register input: catalogInfoUrl: '${{ steps.publish.output.repoContentsUrl }}/catalog-info.yaml'
Crossplane Claim (Self-Service Infra Provisioning)
A developer-facing claim that provisions cloud infra through a platform-defined abstraction.
apiVersion: platform.acme.com/v1alpha1kind: PostgresInstanceClaimmetadata: name: checkout-db namespace: team-checkoutspec: parameters: size: small version: "16" backupRetentionDays: 7 compositionSelector: matchLabels: provider: aws
Common Tooling
Tools frequently used to build an IDP.
- Backstage- CNCF open-source developer portal for catalogs, templates, and TechDocs
- Crossplane- Kubernetes-native control plane for composing cloud infra into self-service APIs
- Humanitec / Port / Cortex- commercial IDP and scorecarding platforms
- Score- a workload spec standard for describing app requirements independent of the target platform
- Argo CD / Flux- GitOps engines that reconcile the platform's declared state onto clusters
Crossplane XRD + Composition (Behind the Claim)
The platform-team-authored abstraction that turns a simple developer-facing claim into concrete cloud resources.
apiVersion: apiextensions.crossplane.io/v1kind: CompositeResourceDefinitionmetadata: name: xpostgresinstances.platform.acme.comspec: group: platform.acme.com names: kind: XPostgresInstance plural: xpostgresinstances claimNames: kind: PostgresInstanceClaim plural: postgresinstanceclaims versions: - name: v1alpha1 served: true referenceable: true schema: openAPIV3Schema: type: object properties: spec: type: object properties: parameters: type: object properties: size: { type: string, enum: [small, medium, large] } version: { type: string }---apiVersion: apiextensions.crossplane.io/v1kind: Compositionmetadata: name: postgres-aws-rds labels: { provider: aws }spec: compositeTypeRef: apiVersion: platform.acme.com/v1alpha1 kind: XPostgresInstance resources: - name: rdsinstance base: apiVersion: rds.aws.upbound.io/v1beta1 kind: Instance spec: forProvider: engine: postgres instanceClass: db.t3.micro
Backstage catalog-info.yaml with Relations
The metadata file every service repo ships so the platform catalog can render ownership, dependencies, and APIs automatically.
apiVersion: backstage.io/v1alpha1kind: Componentmetadata: name: checkout-service description: Handles cart checkout and payment orchestration annotations: backstage.io/techdocs-ref: dir:. github.com/project-slug: acme/checkout-service pagerduty.com/service-id: PXXXXX tags: [checkout, payments, tier-1]spec: type: service lifecycle: production owner: team-checkout system: ecommerce providesApis: [checkout-api] dependsOn: - resource:checkout-db - component:payments-gateway
Score Workload Spec
A platform-agnostic app description a developer writes once; a Score implementation (score-k8s, score-compose) generates the target manifests.
apiVersion: score.dev/v1b1metadata: name: checkout-servicecontainers: checkout: image: registry.acme.com/checkout-service:latest variables: DATABASE_URL: "${resources.db.connection_string}" resources: limits: { cpu: "500m", memory: "256Mi" }service: ports: web: { port: 8080, targetPort: 8080 }resources: db: type: postgres params: { version: "16" }# score-k8s generate score.yaml -o manifests.yaml# score-compose generate score.yaml -o compose.yaml
Scorecard / Maturity Dimensions
Common axes platforms like Cortex, Port, and OpenSLO-based dashboards use to grade service health beyond 'does it deploy'.
- Production readiness- has on-call rotation, runbooks, SLOs, and dashboards defined before go-live
- Ownership clarity- every catalog entity has a resolvable owner team, not a stale or missing one
- Golden-path conformance- percentage of services built from the supported template/CI pipeline vs. bespoke setups
- Security posture- dependency scanning enabled, secrets not hardcoded, image provenance signed
- Documentation freshness- TechDocs/README last updated within a defined window
- DORA metrics- deployment frequency, lead time for changes, change failure rate, MTTR, tracked per service
Policy Gate in the Golden Path Pipeline
Enforce platform guardrails (no root containers, required labels) automatically instead of via manual PR review.
# policy/no-root.regopackage maindeny[msg] { input.kind == "Deployment" container := input.spec.template.spec.containers[_] not container.securityContext.runAsNonRoot msg := sprintf("container %s must set runAsNonRoot: true", [container.name])}# In the golden-path CI template:# - name: policy-check# run: conftest test manifests/deployment.yaml -p policy/# # fails the pipeline before merge if any deny rule matches
Measure platform adoption by opt-in usage of the golden path, not by mandate compliance — if developers route around your paved road for a legitimate use case, that's a signal to widen the road, not to add more enforcement.