This page explains custom resources, which are extensions of the Kubernetes API, including when to add a custom resource to your Kubernetes cluster and when to use a standalone service. It describes the two methods for adding custom resources and how to choose between them.
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.
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. A declarative API allows you to declare or specify the desired state of your resource and tries to match the actual state to this desired state. Here, the controller interprets the structured data as a record of the user’s desired state, and continually takes action to achieve and maintain this 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.
When creating a new API, consider whether to aggregate your API with the Kubernetes cluster APIs or let your API stand alone.
|Consider API aggregation if:||Prefer a stand-alone API if:|
|Your API is Declarative.||Your API does not fit the Declarative model.|
|You want your new types to be readable and writable using
|You want to view your new types in a Kubernetes UI, such as dashboard, alongside built-in types.||Kubernetes UI support is not required.|
|You are developing a new API.||You already have a program that serves your API and works well.|
|You are willing to accept the format restriction that Kubernetes puts on REST resource paths, such as API Groups and Namespaces. (See the API Overview.)||You need to have specific REST paths to be compatible with an already defined REST API.|
|Your resources are naturally scoped to a cluster or to namespaces of a cluster.||Cluster or namespace scoped resources are a poor fit; you need control over the specifics of resource paths.|
|You want to reuse Kubernetes API support features.||You don’t need those features.|
In a Declarative API, typically:
Imperative APIs are not declarative. Signs that your API might not be declarative include:
Use a ConfigMap if any of the following apply:
Note: Use a secret for sensitive data, which is similar to a configMap but more secure.
Use a custom resource (CRD or Aggregated API) if most of the following apply:
kubectl get my-object object-name).
Kubernetes provides two ways to add custom resources to your cluster:
Kubernetes provides these two options to meet the needs of different users, so that neither ease of use nor flexibility are compromised.
Aggregated APIs are subordinate APIServers that sit behind the primary API server, which acts as a proxy. This arrangement is called API Aggregation (AA). To users, it simply appears that the Kubernetes API is extended.
CRDs allow users to create new types of resources without adding another APIserver. You do not need to understand API Aggregation to use CRDs.
Regardless of how they are installed, the new resources are referred to as Custom Resources to distinguish them from built-in Kubernetes resources (like pods).
The CustomResourceDefinition API resource allows you to define custom resources. Defining a CRD object creates a new custom resource with a name and schema that you specify. The Kubernetes API serves and handles the storage of your custom resource.
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 Controller example, which uses Custom Resources 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.
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 CRDs.
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.
CRDs are easier to use. Aggregated APIs are more flexible. Choose the method that best meets your needs.
Typically, CRDs are a good fit if:
CRDs are easier to create than Aggregated APIs.
|Do not require programming. Users can choose any language for a CRD controller.||Requires programming in Go and building binary and image. Users can choose any language for a CRD controller.|
|No additional service to run; CRs are handled by API Server.||An additional service to create and that could fail.|
|No ongoing support once the CRD is created. Any bug fixes are picked up as part of normal Kubernetes Master upgrades.||May need to periodically pickup bug fixes from upstream and rebuild and update the Aggregated APIserver.|
|No need to handle multiple versions of your API. For example: when you control the client for this resource, you can upgrade it in sync with the API.||You need to handle multiple versions of your API, for example: when developing an extension to share with the world.|
Aggregated APIs offer more advanced API features and customization of other features, for example: the storage layer.
|Validation||Help users prevent errors and allow you to evolve your API independently of your clients. These features are most useful when there are many clients who can’t all update at the same time.||Yes. Most validation can be specified in the CRD using OpenAPI v3.0 validation. Any other validations supported by addition of a Validating Webhook.||Yes, arbitrary validation checks|
|Defaulting||See above||Yes, via a Mutating Webhook; Planned, via CRD OpenAPI schema.||Yes|
|Multi-versioning||Allows serving the same object through two API versions. Can help ease API changes like renaming fields. Less important if you control your client versions.||No, but planned||Yes|
|Custom Storage||If you need storage with a different performance mode (for example, time-series database instead of key-value store) or isolation for security (for example, encryption secrets or different||No||Yes|
|Custom Business Logic||Perform arbitrary checks or actions when creating, reading, updating or deleting an object||Yes, using Webhooks.||Yes|
|Scale Subresource||Allows systems like HorizontalPodAutoscaler and PodDisruptionBudget interact with your new resource||Yes||Yes|
|Other Subresources||Add operations other than CRUD, such as “logs” or “exec”.||No||Yes|
|strategic-merge-patch||The new endpoints support PATCH with
||No, but similar functionality planned||Yes|
|Protocol Buffers||The new resource supports clients that want to use Protocol Buffers||No||Yes|
|OpenAPI Schema||Is there an OpenAPI (swagger) schema for the types that can be dynamically fetched from the server? Is the user protected from misspelling field names by ensuring only allowed fields are set? Are types enforced (in other words, don’t put an
||No, but planned||Yes|
When you create a custom resource, either via a CRDs or an AA, you get many features for your API, compared to implementing it outside the Kubernetes platform:
|Feature||What it does|
|CRUD||The new endpoints support CRUD basic operations via HTTP and
|Watch||The new endpoints support Kubernetes Watch operations via HTTP|
|Discovery||Clients like kubectl and dashboard automatically offer list, display, and field edit operations on your resources|
|json-patch||The new endpoints support PATCH with
|merge-patch||The new endpoints support PATCH with
|HTTPS||The new endpoints uses HTTPS|
|Built-in Authentication||Access to the extension uses the core apiserver (aggregation layer) for authentication|
|Built-in Authorization||Access to the extension can reuse the authorization used by the core apiserver (e.g. RBAC)|
|Finalizers||Block deletion of extension resources until external cleanup happens.|
|Admission Webhooks||Set default values and validate extension resources during any create/update/delete operation.|
|UI/CLI Display||Kubectl, dashboard can display extension resources.|
|Unset vs Empty||Clients can distinguish unset fields from zero-valued fields.|
|Client Libraries Generation||Kubernetes provides generic client libraries, as well as tools to generate type-specific client libraries.|
|Labels and annotations||Common metadata across objects that tools know how to edit for core and custom resources.|
There are several points to be aware of before adding a custom resource to your cluster.
While creating a CRD does not automatically add any new points of failure (for example, by causing third party code to run on your API server), packages (for example, Charts) or other installation bundles often include CRDs as well as a Deployment of third-party code that implements the business logic for a new custom resource.
Installing an Aggregated APIserver always involves running a new Deployment.
Custom resources consume storage space in the same way that ConfigMaps do. Creating too many custom resources may overload your API server’s storage space.
Aggregated API servers may use the same storage as the main API server, in which case the same warning applies.
CRDs always use the same authentication, authorization, and audit logging as the built-in resources of your API Server.
If you use RBAC for authorization, most RBAC roles will not grant access to the new resources (except the cluster-admin role or any role created with wildcard rules). You’ll need to explicitly grant access to the new resources. CRDs and Aggregated APIs often come bundled with new role definitions for the types they add.
Aggregated API servers may or may not use the same authentication, authorization, and auditing as the primary API server.
Kubernetes client libraries can be used to access custom resources. Not all client libraries support custom resources. The go and python client libraries do.
When you add a custom resource, you can access it using: