Skip to main content
Welcome to Section Three: Platform APIs and self-service capabilities. If you are a platform engineer, what is your actual product? It is not the Kubernetes cluster, and it is not a wiki page. Your product is an API — a self-service interface that lets developers get what they need without waiting on your team. In this lesson you’ll learn 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 also review the building blocks you’ll use: Custom Resource Definitions (CRDs), controllers/operators, and workflow engines. Think of your platform as a product, your developers as customers, and your APIs as the contract between them. Real-world problem: a platform team of five engineers was receiving ~40 provisioning tickets per week: namespaces, databases, SSL certs, service accounts. Tickets took between 30 minutes and two days to resolve. The backlog grew to more than 200 tickets.
The image highlights that a platform team processes 40 tickets per week, implying that ticket-driven infrastructure is not scalable.
When developers get tired of waiting, they bypass the platform team and spin up their own cloud accounts without IT approval. This is shadow IT. Shadow IT causes three major problems: security blind spots (environments aren’t reviewed), compliance violations (governance gaps), and unmanaged cloud spend.
The image illustrates how different development teams manage multiple AWS accounts under the concept of "Shadow IT," highlighting security blind spots and compliance violations.
Shadow IT is not just an organizational annoyance — it introduces real security, compliance, and cost risks. Preventing it requires replacing slow manual processes with fast, trustworthy self-service APIs.
The platform team itself isn’t the root cause — the ticket-driven process is. People need self-service, not more tickets. Reality check: here’s the common workflow at many enterprises. A developer needs a PostgreSQL instance and files a ticket (or a Jira request). The ticket joins a queue. Days or weeks later it’s assigned. An operations engineer provisions and configures the database manually, then emails the requester.
The image illustrates the typical request flow in a ticket-driven infrastructure, highlighting a process from submission to confirmation with potential delays. It suggests that this approach doesn't scale effectively.
This workflow creates predictable problems: long provisioning times, inconsistent handling (different engineers, different approaches), poor visibility into deployments/cost/ownership, and a platform team that becomes a bottleneck.
The image outlines challenges with ticket-driven infrastructure, highlighting issues such as long provisioning times, inconsistency in handling requests, and lack of visibility into deployments.
Every change that requires a human in the middle does not scale. The predictable result is developers will find workarounds — leading to shadow IT. This is not a people problem; it’s a system design problem. Compare two mindsets:
  • Ticket-driven: Developer files a ticket or emails platform; a human acts as a middleman and performs manual provisioning.
  • Platform-as-product: Developer calls a platform API that declares intent; automated systems provision resources without human intervention.
The image compares two mindsets: the "Infrastructure Team Mindset" involves manual communication and work via tickets/emails, while the "Platform as Product Mindset" emphasizes automation through API calls.
One human plus an API call beats three humans and a ticket queue. This mindset shift is the lesson’s core. Three guiding principles to internalize:
  • Developers are your customers: treat the developer experience as a product. If a developer must wait three days for a namespace, your product is broken.
  • APIs are contracts: a clear contract sets expectations — developers know what they can request and what they will receive; platform teams know what they must support and guarantee.
  • Automation needs interfaces: humans do not scale; APIs do. You can’t effectively automate a ticket queue, but you can automate an API endpoint.
The solution: define platform APIs that convert manual ticket work into a self-service portal.
The image is a graphic titled "A Platform Without an API Is Just Another Silo," emphasizing the importance of APIs through points on developers, contracts, and automation. The solution suggested is defining platform APIs to automate self-service.
Reference architecture for a platform API
  • Consumer layer: Developers request resources via platform APIs and only declare intent — they don’t need to know implementation details.
  • Contract layer: The platform API itself. CRDs define schema; validation enforces guardrails; defaults fill unspecified values. This layer separates intent (what to create) from execution (how to create it).
  • Platform logic layer: Reconciliation implemented by controllers/operators and workflow engines. These components translate the declared desired state into real infrastructure.
The contract layer should follow four principles:
  • Consumer-centric: design from the developer’s perspective.
  • Declarative: users declare what they want, not how to implement it.
  • Guardrails: enforce validation and policy at the API layer.
  • Self-documenting: schema should double as documentation.
The image illustrates design principles for a "Platform Contract Architecture," which include being consumer-centric, declarative, having built-in guardrails, and being self-documenting. Each principle is represented with a unique icon and brief description.
This architecture maps directly to real implementations: CRDs define the contract, controllers/operators encode reconciliation logic, and tooling such as Crossplane handles cloud provisioning and compositions. For hands-on practice, see Learn By Doing: Crossplane. API design approaches: comparing infrastructure-centric vs consumer-centric
  • Infrastructure-centric API: Forces developers to specify cloud-specific settings (instance class, storage class, AZs). This raises the risk of improper configuration, increases cognitive load, and leaks implementation details.
Example (infrastructure-centric):
  • Consumer-centric API: Exposes intent (e.g., “medium Postgres”), hides cloud specifics, and maps intent to platform-defined defaults (instance class, backups, networking, security). This reduces mistakes and simplifies the developer experience.
Good APIs ask “What do you need?” not “How should you configure it?” The platform should handle the underlying cloud-specific lines of configuration. Use this principle when designing CRD schemas, Crossplane compositions, and operator logic. Always evaluate whether the API exposes intent or implementation. Core building blocks
  • Custom Resource Definitions (CRDs): define your API schema and extend Kubernetes with domain-specific types (Database, Application, Team).
  • Operators and Controllers: watch custom resources and reconcile actual state to desired state; when a Database CR is created, the controller provisions the database.
  • Workflow Engines: orchestrate multi-step provisioning flows requiring retries, parallelism, and dependencies (e.g., create VPC → create DB → create Secret → notify team).
The image illustrates the building blocks of a platform API, covering Custom Resource Definitions, Operators and Controllers, and Workflow Engines, with examples and brief descriptions for each.
How these components fit together (self-service pipeline)
  1. Developer creates a Custom Resource (CR) via the platform API.
  2. The CRD validates input against the schema and policies (guardrails).
  3. A controller/operator reconciles the CR and triggers provisioning tasks.
  4. Infrastructure and related artifacts are created; the CR’s status is updated and notifications are sent to the developer.
This is the complete self-service pipeline: declarative intent → automated reconciliation → realized infrastructure. Quick comparison table
Design platform APIs with the developer experience in mind: provide concise intent-driven fields, sensible defaults, and clear validation errors. Think of the CRD schema as both the contract and the documentation.
Key takeaways
  • Treat your platform as a product: measure developer experience and iterate.
  • APIs enable self-service at scale: they prevent bottlenecks and reduce shadow IT.
  • Design consumer-centric contracts that hide infrastructure complexity and enforce guardrails.
  • Kubernetes gives you the building blocks: CRDs, controllers/operators, and workflow engines to implement self-service.
The image is a slide titled "Key Takeaways," listing four points on treating platforms as products, using APIs for scalability, designing consumer-focused interfaces, and utilizing Kubernetes building blocks.
Platform engineering is about making the right thing the easy thing. If filing a ticket is easier than using the platform, developers will keep filing tickets — so make the right thing the easy thing. References and further reading

Watch Video