Skip to main content
Welcome to Section Three: Platform APIs and self-service capabilities. If you’re a platform engineer, what is your product? It’s not the Kubernetes cluster, and it’s not a wiki page. Your product is the API — a self-service interface that lets developers get what they need without waiting on your team. Platform engineering succeeds when that API makes the safe, compliant path the easiest path. This lesson explains why ticket-driven infrastructure fails at scale, how to adopt a platform-as-a-product mindset, and how to design consumer-centric platform APIs that hide infrastructure complexity. We’ll cover the essential building blocks: custom resource definitions (CRDs), controllers/operators, workflow engines, and tools like Crossplane for cloud provisioning. The goal: see your platform as a product, your developers as customers, and your APIs as the contract between you. Why ticket-driven infrastructure becomes a bottleneck At a large insurance company, a platform team of five handled ~40 provisioning tickets per week (new namespaces, databases, SSL certificates, service accounts). Each ticket required 30 minutes to two days of work. The backlog grew to 200+, and developers started creating their own accounts and resources outside central IT — the classic shadow IT problem.
A slide titled "Ticket-Driven Infrastructure Doesn't Scale" showing a vertical flowchart of a typical request flow. It lists steps: developer submits request → ticket created in queue → wait days/weeks for assignment → manual provisioning by ops → confirmation email sent to user.
Common problems in ticket-driven workflows:
  • Long lead times: days or weeks to get basic resources.
  • Inconsistent outcomes: different engineers make different choices.
  • Poor visibility and ownership: unclear who owns what.
  • Bottlenecked platform team: manual work doesn’t scale.
A presentation slide titled "Ticket-Driven Infrastructure Doesn't Scale" listing three challenges: slow provisioning (days or weeks), inconsistent handling of requests, and lack of visibility into deployed resources. Each challenge is shown in a numbered box with a brief explanation.
Shadow IT is a symptom of poor self-service. When the platform is hard to use, teams bypass it — creating security blind spots, governance gaps, and untracked costs.
Ticket-driven vs API-driven: the mindset shift Compare two approaches:
  • Ticket-driven model: developers file tickets or send emails; platform engineers manually provision resources, coordinate with infra teams, and process requests one-by-one.
  • API-driven model: developers call a platform API (declarative requests); controllers/operators and automation reconcile desired state into real infrastructure.
A slide titled "A Platform Without an API Is Just Another Silo" comparing two approaches. The left shows an "Infrastructure Team Mindset" where developers submit tickets/emails and the platform team does manual work on infrastructure, while the right shows a "Platform as Product Mindset" where developers use API calls to a platform API that automates infrastructure changes.
Treat developers as customers and the platform as a product. If requesting a namespace via ticket is easier than using your platform API, developers will choose tickets — or go rogue. APIs define contracts and set clear expectations for both sides: developers know what to request and what to expect; platform teams know what to support and what guarantees to maintain. Reference architecture for a platform contract The reference architecture is simple and maps directly to Kubernetes platform-building blocks:
A three-layer diagram titled "Platform Contract Architecture" showing Consumers (Developers) at the top, a Platform Contract (API) in the middle, and Platform Logic at the bottom. Arrows label the flow as "API Request" down to the API and "Reconcile" down to the platform logic, with notes about CRDs/schemas/validation and operators/controllers/workflows.
Layers and responsibilities:
  • Consumer layer: Developers declare intent (for example, “create a medium Postgres database”). They consume the platform API and do not need to understand implementation details.
  • Contract layer: The platform API — implemented as CRDs with schemas, defaults, validation and RBAC — defines the contract and guardrails.
  • Platform logic: Controllers, operators, workflow engines, and composition tools (e.g., Crossplane) reconcile the declared state into real resources and operational defaults.
Core principles for the contract layer
Design the API first as the product. The CRD schema is both the contract and the primary documentation for consumers — make it clear, opinionated, and discoverable.
API design styles: infrastructure-centric vs consumer-centric An infrastructure-centric API exposes implementation details and forces consumers to know cloud and cluster internals:
Downsides: higher chance of misconfiguration, increased cognitive load for developers, and fragility as infra changes. Contrast with a consumer-centric API: ask “What do you need?” and map that intent to concrete implementation. Example flow:
  • Developer request: “I need a medium Postgres database.”
  • Platform maps “medium” to the correct instance type, storage class, backup policy, network config, IAM rules, and secret management.
Good APIs hide implementation complexity while exposing clear, testable intent.
A presentation slide titled "API Design: Hide Complexity, Expose Intent" with icons for an API and a developer. It contrasts a clear developer intent ("I need a medium PostgreSQL database") with the lower-level infrastructure question ("How should we configure the infrastructure?").
Key platform components and how they work together How these pieces interact (high-level flow):
  1. Developer creates a Custom Resource (CR) that expresses intent.
  2. The CRD validates the CR (schema, defaults, validations).
  3. A controller/operator reconciles the CR into platform actions.
  4. Crossplane or the operator provisions cloud resources and updates CR status.
  5. The platform returns self-service outputs (endpoints, credentials, notifications) to the developer.
Practical takeaways
  • Treat your platform as a product: build, measure, and iterate on the API.
  • APIs enable self-service and scale; tickets do not.
  • Design consumer-centric, declarative contracts that hide complexity and enforce guardrails.
  • Use Kubernetes primitives (CRDs, controllers/operators) and composition tools (Crossplane) to implement the platform logic.
  • Make the safe and supported path the easiest option for developers.
Further reading and references Platform engineering is about making the right thing the easy thing. If a ticket is easier than the API, the contract — and the product — needs improvement.

Watch Video