Resource APIs are the foundation of Kubernetes; they give a simple declarative model for creating large systems. You can create your own APIs using custom resources to give new abstractions and automation to reduce complexity and toil.

Because of its straightforward, declarative API architecture, Kubernetes has been a driving force in the container revolution.

Outside of the Kubernetes project, there is a trend toward creating proprietary resource APIs. People create these APIs as Kubernetes cluster extensions, resulting in APIs that look and feel just like the built-in kinds. For example, instead of specifying deployments and services that implement a Guestbook, you could construct a Guestbook resource type that allows users to declare Guestbooks directly as Kubernetes objects.

Traditional APIs are structured as requests on objects that have some intended state that you declare, whereas Kubernetes APIs are structured as requests on objects that contain some desired state that you declare. These items are known as resources, and they serve as the foundation for using Kubernetes (e.g., deployment, service, and ConfigMap.)

Here’s why Kubernetes resource APIs are unique, and how your team can make use of them.

Why invest in resource APIs?

What’s fueling this upward trend? There are numerous factors to consider. One important point is that the processes and tools required to manage apps and containerized workloads can be simplified. Resource APIs simplify things in two ways: they provide abstractions and they embed difficult or routine administration duties right into the API.


Resource APIs are simple abstractions for composing and configuring lower-level resources in order to build complicated applications.

  • They might, for example:
  • Create resource collections.
  • Connect your resources.

Lower-level resources, such as containers, init-containers, sidecar-containers, health/readiness checks, labels/selectors, and so on, must be configured.

Users can specify their application as a single Guestbook object rather than a collection of deployments, services, ConfigMaps, and so on. Furthermore, by deciding what to expose in the Guestbook API, authors of the Guestbook API can impose their opinions and best practices on how to configure lower-level resources.


By including difficult or ordinary administration tasks into the API, resource APIs can encapsulate them.

Automated management can execute chores such as backups; respond to user adjustments such as manual scaling or CPU resource tuning; perform self-healing when a replica fails; perform self-tuning when processes are CPU-throttled; and respond to external events such as when a new release is released.

Notably, when management logic is embedded directly into the API, there is no need for extra tooling or orchestration processes.

What types of projects should you develop as resource APIs?

As Kubernetes resource APIs, a variety of solutions are being created. Here are a few examples of different categories.


These are application-specific APIs. They embed human operational knowledge for configuring and administering the application in the API itself, automating processes and decreasing the need for orchestration software.

The Spark Operator and the Airflow Operator are two examples of operators.

By embedding cloud-native logic in the Kubernetes API, operators can provide cloud-native features for non-cloud-native apps.


These APIs offer functionality to other APIs rather than controlling collections of resources. Decorators provide standardized common logic that can be used with a variety of APIs.

The Horizontal Pod Autoscaler and the Vertical Pod Autoscaler are two examples of decorators.

New container-based APIs

New container-based abstractions are being developed, in which the fundamental functionality is included directly in the API rather than in a separate “wrapped” application.

Knative for serverless and Tekton for pipelines are two examples.

These APIs are designed to solve specific challenges and provide high-level, cloud-native abstractions for container execution.

The Kubernetes resource API architecture

What is the process for creating API extensions? You can put together a few atomic building parts to create APIs, including:

  • Declare the API and identify concerns such as API endpoints, schema, versions, and so on.
  • Controllers control the API and implement asynchronous level-based reconciliation loops.
  • Accept mutation requests and execute validation, defaults, and conversion via webhooks.

Resources: State definition

A user’s desired state, as well as observed status, are stored in resources. You can utilize them as built-in resources (deployments, services) or as bespoke resource definitions defined by the user.

The Kubernetes Discovery API and OpenAPI can be used to find resources, which have a common schema and endpoint structure. This makes commands as kubectl apply and kubectl get “simply work” no matter how the resource is implemented.

Here’s how those structural elements break down.

  • Metadata:
    • Resource: name, namespace, labels, annotations
    • API: kind, version, group
  • Spec:
    • The desired state is written by users and the control plane, actuated by controllers
    • Examples: replicas, a pod template
  • Status:
    • Observed state published by controllers, read by users
    • Examples: readyReplicas, availableReplicas

Resources do not contain any business logic or actuation because they simply store structured data. Instead, a loosely connected component called controllers is used to implement such functionality.

Controllers: Implementation

Controllers are reconciliation loops that monitor changes to a resource (data) and respond by altering the cluster or external state. The following are the controllers:

  • Asynchronous: After the create/update/delete resource activity is completed, reconciliation takes place.
  • While events trigger reconciliations, they are executed by reading the current state rather than looking at the contents of the event (for instance, they should be triggerable by a cron task, not just events).

Most controllers are built to control only one resource (for example, deployment), but they also produce (make) other resources. Deployments, for example, generate ReplicaSets.

Controllers perform modifications based on the resource standard and update the resource status to inform the user.

Webhooks: Admission

Webhooks are used to execute validation, defaulting, and converting resources between API versions and provide specific admission logic for resources (e.g., a v1beta1 object to a v1 object).

Webhooks can be utilized with or without resources or controllers. Administrators can use this to enforce advanced policy, define domain-specific defaults (for example, “all pods should have the standard sidecar for logging”), and implement custom logic.

Tools for developing custom APIs

It can be difficult to write a well-structured and well-designed Kubernetes resource API. Fortunately, if you’re familiar with the Go programming language, there are various libraries and tools to help you out.

Libraries: Controller-runtime

Controller runtime is a set of libraries for creating Kubernetes controllers that give high-level abstractions and easy defaults. They are published as a Kubernetes sub-project and written and maintained by Kubernetes project maintainers.

Frameworks: Kubebuilder and Operator SDK

Kubebuilder and Operator SDK are both frameworks for constructing APIs that are built on top of the controller-runtime libraries. The two frameworks share the majority of their viewpoints and are continuing to converge. The biggest noticeable distinction between them is that Operator SDK is more focused on operators and integrates with other operator-framework projects, whereas Kubebuilder is more generalist in its support for Kubernetes subprojects.

Build cloud-native abstractions that just work

Resource APIs allow you to create simple cloud-native abstractions that can be dropped into current Kubernetes workflows and only use Kubernetes tooling. By providing new abstractions and automating routine activities, you can create your own resource APIs to decrease complexity and toil. To get started building the APIs you’ve always wanted to use, get this free e-book.

For more info:

Also Read: