APIs for Self-Service Platforms (CRDs): CNPA practice questions

A self-service platform needs an API that users can call without opening a ticket. Kubernetes offers a convenient way to build one: extend its own API with custom resources, so a request for a database, a preview environment or a message queue becomes an object that users create with kubectl, a pull request or a portal, and that a controller fulfills.

The Kubernetes documentation defines a resource as an endpoint in the API that stores a collection of objects of one kind, and a custom resource as an extension of that API which is not necessarily available in a default installation. A CustomResourceDefinition registers a new resource type with a name and schema that you specify; the API server then serves and stores those objects, so no separate API server has to be written. The alternative, API aggregation, places a custom API server behind the main one, which requires programming but gives more control over behavior such as storage and conversion between API versions. The documentation sums it up: CRDs are easier to use, aggregated APIs are more flexible.

On their own, custom resources only let you store and retrieve structured data. Combined with a custom controller they provide a true declarative API, in which users declare the desired state and the controller keeps the current state in sync; that pairing is the operator pattern. Because custom resources follow Kubernetes conventions, they inherit a lot: kubectl support, the usual RBAC rules, watches that automation can react to, and the metadata, spec and status structure. The documentation lists OpenAPI v3 validation and defaulting in the CRD schema, and a status subresource that allows fine-grained access control, where users write the spec and the controller writes the status.

Good platform APIs are abstractions, not mirrors of the underlying system. A small resource with an engine and a size field can hide dozens of provider-specific settings, which is how the platform reduces cognitive load and enforces its defaults. The Platforms White Paper lists Kubernetes, Crossplane, the Operator Framework, Helm and KubeVela as example projects for the provisioning API capability, and the maturity model's self-service level describes an API that abstracts the creation and maintenance of databases and gives users what they need, such as a connection string, a location for secret data and a dashboard.

The documentation also says when not to use a custom resource. A declarative API suits a relatively small number of small objects that describe configuration, change infrequently and are read and written by humans. It is a poor fit for high request rates, large amounts of data, or end-user data such as images or PII, and designs that store application data in the Kubernetes API are described as too closely coupled. When a program in a Pod just needs a configuration file, a ConfigMap is the better choice.

At associate level, expect questions on what a CRD adds, why a controller is needed, when to prefer a ConfigMap, and how custom resources give users a self-service interface with familiar tooling.