A platform API contract defines what development teams can ask a platform to do and what behavior they can expect. It is the entry point to self-service workflows, not a catalog of the tools behind them. The platform team owns the API and evolves it as teams need new workflows. section 1.1.5 section 6.1
Start with a task teams actually need to perform. To request a development environment for the Conference application, a team needs an isolated application instance, its databases and other infrastructure, and a way to connect. The contract can express the requested environment while leaving provisioning and configuration to the platform. A different team may need a different workflow, so an environment API should not become the definition of everything a platform does. section 6.1.1
Listing 6.2 Environment definition as a Kubernetes resource
apiVersion: salaboy.com/v1alpha1
kind: Environment
metadata:
name: team-a-dev-env #1
spec:
compositionSelector:
matchLabels:
type: development #2
parameters: #3
installInfra: true
The Environment resource makes the request concrete: its name identifies the environment, while the development selector and infrastructure parameter describe what to provision. section 6.3.2
From request to usable environment
In the walking skeleton, a team submits an Environment resource to the platform’s Kubernetes API using kubectl. A Crossplane composition and its Helm provider create a vcluster and install the Conference application Helm chart. The team then connects to its isolated virtual cluster. The API exposes the request; Crossplane, Helm, and vcluster implement it. section 6.3.2
Kubernetes resources are one way to implement the contract, not a requirement for every consumer. A dashboard, CLI, SDK, user interface, or REST endpoint can offer a more tailored route to the same platform workflows. Keep access to underlying tools possible when a predefined workflow does not fit. section 1.2.1 section 6.4
Contracts can also sit closer to application code. HTTP or gRPC capability APIs let services use common infrastructure functions without taking on vendor-specific client dependencies. That separation lets the platform team change infrastructure independently, but it raises obligations: version contracts, avoid breaking consumers, support local development, and account for network latency and security. Leave a direct route for specialized requirements rather than complicating the common API for every edge case. section 7.2 section 7.2.1
