Platform Engineer

Platform Engineer

When to Use

• Design or operate an internal developer platform, developer portal, or service catalog
• Build golden paths, paved-road templates, scaffolders, and self-service workflows for engineering teams
• Standardize runtime, deployment, observability, and service ownership patterns across many teams
• Manage multi-tenant Kubernetes or platform abstractions as reusable products
• Measure developer experience, platform adoption, and platform SLOs

When NOT to Use

• Provision one-off cloud networking, IAM, compute, or Terraform modules → infrastructure-engineer
• Implement per-application CI/CD YAML or GitOps mechanics only → devops
• Choose release rollout strategy or cutover plan → deployment-strategist
• Implement security controls such as IdP, KMS, SIEM, or EDR → information-security-engineer
• Write enterprise-wide architecture ADRs and integration reviews → senior-system-architecture

Related skills

Core Workflows

1. Platform as product

Treat the platform like a product with internal customers:

1. Identify user journeys (create service, deploy, observe, rotate secrets) 2. Define thin platform APIs—hide complexity, expose safe defaults 3. Set platform SLOs (e.g., scaffold time, deploy success rate, portal uptime) 4. Roadmap from developer interviews and toil metrics 5. Deprecate with migration windows—not breaking teams silently

See `references/platform_product.md` for SLOs and adoption metrics.

2. Golden paths (paved roads)

Golden path properties:

• Opinionated defaults (language, observability, auth, CI template)
• Escape hatches documented for edge cases
• Versioned templates with changelog
• Same path for 80% of services; exceptions require review

scaffold → build (shared pipeline) → deploy (standard envs) → operate (shared dashboards/alerts)

See `references/golden_paths.md` for template and exception process.

3. Internal developer platform (IDP)

Layers:

Integrate catalog, docs, templates, and deployment in one discoverable flow.

See `references/idp_architecture.md` for component diagram and contracts.

4. Multi-tenant Kubernetes platform

• Namespace/tenant isolation; RBAC and network policies
• Quotas, priority classes, and cluster autoscaling
• Standard add-ons: ingress, cert-manager, external-dns, metrics, logging
• Cluster upgrades with tenant communication plan
• Policy admission (OPA/Kyverno) owned by platform

See `references/platform_kubernetes.md` for tenant checklist.

5. Developer portal and service catalog

• Register services: owner, tier, repo, on-call, dependencies
• Link runbooks, APIs, and SLIs from catalog entries
• Software templates (Cookiecutter, Yeoman, internal CLI) generate compliant repos
• Scorecards for maturity (tests, SLOs, security baseline)

See `references/developer_portal.md` for catalog fields and template standards.

6. Platform interfaces and versioning

• Publish platform contracts: breaking vs additive changes
• Semantic versioning for charts, modules, and templates
• Changelog and migration guides for each major bump
• Support window for N-1 template versions

When to load references

• IDP design → references/idp_architecture.md
• Templates and paved roads → references/golden_paths.md
• Backstage / catalog → references/developer_portal.md
• K8s multi-tenancy → references/platform_kubernetes.md
• SLOs and adoption → references/platform_product.md

Developer portal

Table of contents

1. Catalog entity 2. Templates 3. Scorecards

Catalog entity

Minimum fields per service:

Templates

• Software Templates create repos + register in catalog
• Parameters validated (naming, region, tier)
• Post-create checklist in PR (first deploy, SLO setup)

Scorecards

Example checks:

• Unit tests in CI
• SLO defined in monitoring
• Dependency updates < 90 days
• No critical CVEs on default branch

Use scorecards for guidance first; gates only for tier-0/1 when mature.

Golden paths

Table of contents

1. Template requirements 2. Standard pipeline bundle 3. Exception process

Template requirements

Every golden-path scaffold includes:

• [ ] CI workflow (test, build, scan)
• [ ] Container or runtime manifest with resource defaults
• [ ] Observability (metrics, logs, traces hooks)
• [ ] Health/readiness endpoints
• [ ] Secret injection pattern (no hardcoded creds)
• [ ] README with deploy and rollback commands

Standard pipeline bundle

Exception process

1. Team documents why golden path insufficient 2. Platform + security review 3. Time-bound exception with compensating controls 4. Backlog item to absorb into path or retire exception

IDP architecture

Table of contents

1. Component map 2. Platform contracts 3. Anti-patterns

Component map

Developers
    ↓
Portal (catalog, docs, create)
    ↓
Control plane (GitOps / IaC / APIs)
    ↓
Runtime (K8s, serverless, DB patterns)
    ↓
Observability + security baselines (automatic)

Platform contracts

Document for each capability:

• Inputs teams provide (name, tier, region)
• Outputs guaranteed (URLs, dashboards, IAM roles)
• SLAs and support channel
• Cost allocation model

Anti-patterns

• Platform team becomes ticket queue for raw Terraform
• No versioning on templates—silent drift
• Portal without working self-service (catalog-only)
• One giant cluster with no tenant guardrails

Platform Kubernetes

Table of contents

1. Tenant onboarding 2. Cluster operations 3. Add-on baseline

Tenant onboarding

• Namespace per team or env pattern documented
• RBAC: namespace admin vs read-only
• ResourceQuota and LimitRange defaults
• NetworkPolicy: deny-all + allowlist egress
• Pod Security Standards / admission policies

Cluster operations

• Upgrade cadence; test on non-prod first
• Node pool separation (system vs workload)
• Backup etcd/stateful workloads per policy
• Incident runbook for control plane degradation

Add-on baseline

Typical platform-managed add-ons:

• Ingress controller
• cert-manager
• metrics-server + Prometheus agent or managed equivalent
• log collector (DaemonSet or sidecar pattern)
• cluster-autoscaler or Karpenter

Teams consume via abstractions—not raw cluster-admin.

Platform product

Table of contents

1. Platform SLOs 2. Adoption metrics 3. Feedback loop

Platform SLOs

Examples (define per org):

Adoption metrics

• % services on golden path vs custom
• Weekly active developers using portal
• Support tickets per 100 deploys (toil proxy)
• Mean time to restore platform incidents

Feedback loop

• Monthly office hours
• Public roadmap in portal
• RFC process for breaking platform changes
• Celebrate teams who contribute template improvements