Custom Resource Definitions

This section of the Best Practices Guide deals with creating and using CustomResource Definition objects.

When working with Custom Resource Definitions (CRDs), it is important todistinguish two different pieces:

• There is a declaration of a CRD. This is the YAML file that has the kindCustomResourceDefinition
• Then there are resources that use the CRD. Say a CRD definesfoo.example.com/v1. Any resource that has apiVersion: example.com/v1 andkind Foo is a resource that uses the CRD.

Install a CRD Declaration Before Using the Resource

Helm is optimized to load as many resources into Kubernetes as fast as possible.By design, Kubernetes can take an entire set of manifests and bring them allonline (this is called the reconciliation loop).

But there’s a difference with CRDs.

For a CRD, the declaration must be registered before any resources of that CRDskind(s) can be used. And the registration process sometimes takes a few seconds.

Method 1: Let helm Do It For You

With the arrival of Helm 3, we removed the old crd-install hooks for a moresimple methodology. There is now a special directory called crds that you cancreate in your chart to hold your CRDs. These CRDs are not templated, but willbe installed by default when running a helm install for the chart. If the CRDalready exists, it will be skipped with a warning. If you wish to skip the CRDinstallation step, you can pass the —skip-crds flag.

Some caveats (and explanations)

There is not support at this time for upgrading or deleting CRDs using Helm.This was an explicit decision after much community discussion due to the dangerfor unintentional data loss. Furthermore, there is currently no communityconsensus around how to handle CRDs and their lifecycle. As this evolves, Helmwill add support for those use cases.

Another important point to consider in the discussion around CRD support is howthe rendering of templates is handled. One of the distinct disadvantages of thecrd-install method used in Helm 2 was the inability to properly validatecharts due to changing API availability (a CRD is actually adding anotheravailable API to your Kubernetes cluster). If a chart installed a CRD, helm nolonger had a valid set of API versions to work against. This is also the reasonbehind removing templating support from CRDs. With the new crds method of CRDinstallation, we now ensure that helm has completely valid information aboutthe current state of the cluster.

Method 2: Separate Charts

Another way to do this is to put the CRD definition in one chart, and then putany resources that use that CRD in another chart.

In this method, each chart must be installed separately. However, this workflowmay be more useful for cluster operators who have admin access to a cluster