Custom Resources
This page explains the concept of custom resources, which are extensions of the Kubernetes API.
Custom resources
A resource is an endpoint in the Kubernetes API that stores a collection of API objects of a certain kind. For example, the built-in pods resource contains a collection of Pod objects.
A custom resource is an extension of the Kubernetes API that is not necessarily available on every Kubernetes cluster. In other words, it represents a customization of a particular Kubernetes installation.
Custom resources can appear and disappear in a running cluster through dynamic registration, and cluster admins can update custom resources independently of the cluster itself. Once a custom resource is installed, users can create and access its objects with kubectl, just as they do for built-in resources like pods.
Custom controllers
On their own, custom resources simply let you store and retrieve structured data. It is only when combined with a controller that they become a true declarative API. The controller interprets the structured data as a record of the user’s desired state, and continually takes action to achieve and maintain that state.
A custom controller is a controller that users can deploy and update on a running cluster, independently of the cluster’s own lifecycle. Custom controllers can work with any kind of resource, but they are especially effective when combined with custom resources. The Operator pattern is one example of such a combination. It allows developers to encode domain knowledge for specific applications into an extension of the Kubernetes API.
CustomResourceDefinitions
CustomResourceDefinition (CRD) is a built-in API that offers a simple way to create custom resources. Deploying a CRD into the cluster causes the Kubernetes API server to begin serving the specified custom resource on your behalf.
This frees you from writing your own API server to handle the custom resource, but the generic nature of the implementation means you have less flexibility than with API server aggregation.
Refer to the Custom Resource Example for a demonstration of how to register a new custom resource, work with instances of your new resource type, and setup a controller to handle events.
Note: CRD is the successor to the deprecated ThirdPartyResource (TPR) API, and is available as of Kubernetes 1.7.
API server aggregation
Usually, each resource in the Kubernetes API requires code that handles REST requests and manages persistent storage of objects. The main Kubernetes API server handles built-in resources like pods and services, and can also handle custom resources in a generic way through CustomResourceDefinitions.
The aggregation layer allows you to provide specialized implementations for your custom resources by writing and deploying your own standalone API server. The main API server delegates requests to you for the custom resources that you handle, making them available to all of its clients.
What’s next
- Learn how to Extend the Kubernetes API with the aggregation layer.
- Learn how to Extend the Kubernetes API with CustomResourceDefinition.
- Learn how to Migrate a ThirdPartyResource to CustomResourceDefinition.