Custom Resource Definitions in Charts

Custom Resource Definitions in Charts are Kubernetes resource specifications included within Helm charts that enable the extension of the Kubernetes API by defining custom resource types. These definitions allow users to create, manage, and interact with new resource kinds that are not part of the default Kubernetes API, thereby facilitating custom workflows, operators, or domain-specific abstractions. Integrating CRDs within Helm charts ensures that the custom resource types required by an application or operator are installed and managed consistently alongside related Kubernetes objects.

Overview of Custom Resource Definitions in Helm Charts

Definition and Purpose

Custom Resource Definitions (CRDs) are Kubernetes API extensions that declare new resource types. Including CRDs in Helm charts allows the chart to provision these new resource types automatically, enabling the deployment of custom controllers or operators that rely on them. This mechanism extends Kubernetes in a declarative way and allows users to manage complex applications with custom behaviors.

Placement of CRDs in Helm Charts

Helm charts have a special directory named crds/ intended to hold CRD manifests. Files placed in this directory are installed by Helm during the chart installation process before any other chart resources. This separation ensures CRDs are created first, making the custom resource kinds available for subsequent resources that may depend on them.

Structure and Content of CRD Manifests in Charts

CRD Manifest Format

A CRD manifest is a Kubernetes YAML file that defines the schema and behavior of a new resource type. The manifest typically contains the following fields:

• apiVersion: Usually apiextensions.k8s.io/v1 for Kubernetes versions 1.16 and later.
• kind: Always CustomResourceDefinition.
• metadata: Contains metadata like name which must be the plural resource name combined with the API group (e.g., crontabs.stable.example.com).
• spec: Defines the resource group, versions, scope (Namespaced or Cluster), and names (plural, singular, kind, shortNames).
• versions: Specifies one or more versions with schema validation, subresources, and additional printer columns.
• validation: JSON schema that validates the custom resource's structure.
• subresources: Optional fields like status and scale enabling additional Kubernetes features.
• additionalPrinterColumns: Defines extra columns visible in kubectl get output.

Example CRD Manifest Snippet

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                cronSpec:
                  type: string
                image:
                  type: string
                replicas:
                  type: integer
      subresources:
        status: {}
      additionalPrinterColumns:
        - name: Schedule
          type: string
          jsonPath: .spec.cronSpec
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
      - ct

Best Practices for Managing CRDs in Helm Charts

Using the crds/ Directory

Helm automatically processes manifests in the crds/ directory differently by installing them before other templates and never deleting them on chart uninstall. This behavior prevents accidental removal of CRDs that may be shared by multiple releases.

Avoid Managing CRDs with Templates

CRDs should not be templated or managed in the templates/ directory because Helm does not guarantee the order of resource creation required for CRDs and their dependent Custom Resources (CR). Instead, CRDs belong in the crds/ folder to ensure proper installation ordering.

Handling CRD Upgrades

Upgrading CRDs can be complex because Helm does not manage updates to CRDs automatically. To update CRDs, manual intervention or dedicated tooling is often necessary. Strategies include:

• Applying CRD updates via kubectl outside Helm.
• Using Helm hooks or separate charts for CRDs.
• Keeping backward compatibility in CRD schemas.

Versioning and Stability

Define multiple versions inside the CRD manifest to allow smooth API evolution and migration. Mark one version as the storage version used internally by Kubernetes and serve others for compatibility.

Integrating CRDs and Custom Resources in Charts

Deploying Custom Resources

After CRDs are installed, Helm charts can deploy instances of these custom resource types using templated manifests within the templates/ directory. These manifests reference the CRD’s kind and apiVersion and provide configuration specific to the deployed application.

Managing Dependencies

Charts that depend on CRDs provided by other charts can declare them as dependencies. In such cases, the CRDs are installed by the dependency chart, and the consuming chart only needs to deploy the custom resources.

Example Chart Layout with CRDs

mychart/
  Chart.yaml
  values.yaml
  crds/
    myresource.crd.yaml
  templates/
    myresource.yaml
    deployment.yaml

Here, myresource.crd.yaml defines the custom resource type, while myresource.yaml creates instances of that resource.

Limitations and Considerations

• Helm does not delete CRDs automatically on uninstall to avoid data loss.
• CRDs must be installed before any custom resources referencing them.
• Careful schema design and versioning is essential to avoid breaking changes.
• Some Kubernetes features like validation and defaulting fields require Kubernetes 1.16+ with apiextensions.k8s.io/v1.

Summary of Key Points

• Custom Resource Definitions extend Kubernetes API with new resource types.
• Helm charts include CRDs in the crds/ directory for proper installation order.
• CRDs are YAML manifests defining schema, versions, scope, and metadata.
• CRDs should not be templated or managed in templates/ to avoid lifecycle issues.
• Managing CRD upgrades requires special attention and outside-Helm processes.
• Custom resources relying on CRDs are deployed as regular templates after CRD installation.
• Proper versioning and schema design ensure API evolution without disruption.

This comprehensive approach ensures that Helm charts can reliably install and manage Kubernetes custom resource types alongside applications that depend on them.