Helm / Advanced: compatibility, trust and delivery evidence / Lesson 13

CRDs, capabilities and extension lifecycle

Separate extension installation from custom-resource use and understand why capability checks and local renders cannot prove controller behavior.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish CRD declarations, custom resources and controllers.
Explain the special Helm 3 crds directory lifecycle.
Review capability branches without confusing discovery and policy.

Identify three extension parts

A CustomResourceDefinition adds an API type; a custom resource is an instance of that type; a controller interprets that instance and acts on it. Installing the schema does not install a functioning controller unless the package explicitly supplies one. Consider a synthetic CatalogPolicy extension: a policy object might be accepted but never influence an application because no reconciler watches it. Keep ownership of schema, controller and instances distinct in architecture notes. A namespace-scoped application release should not silently claim responsibility for a cluster-wide extension shared by unrelated teams.

Respect crds directory semantics

In the Helm 3 model, files in crds are not templated and are installed before ordinary templates during installation. Existing CRDs are skipped rather than treated as routine upgrade targets. Helm does not normally upgrade or delete these CRDs through the ordinary chart lifecycle. These deliberate limits protect against accidental data loss but require a separate extension evolution plan. The first example is a source layout, not a CRD to apply. The application chart holds only instance templates, while an explicit platform owner reviews schema evolution and controller compatibility independently.

text Separate extension and application ownership

extension-owner/
  crds/catalogpolicies.example.test.yaml
application-chart/
  templates/catalog-policy.yaml
review record:
  schema owner, controller version, accepted resource versions

example.test is a reserved teaching domain. The tree communicates ownership; no extension is installed or contacted.

Interpret capability checks narrowly

Capabilities exposes available API information used by templates to choose output. A Has check can detect a declared API version or resource in the supplied context. During local rendering, that context can be simulated and differs from live discovery. The second fragment fails deliberately when a required extension is absent, instead of silently dropping a mandatory policy object. A positive check still cannot establish that the controller is healthy, a conversion webhook works or admission will allow the particular resource. Capability detection chooses a template branch; acceptance and behavior remain separate claims.

gotemplate An explicit extension prerequisite

{{- if not (.Capabilities.APIVersions.Has "example.test/v1/CatalogPolicy") -}}
{{- fail "CatalogPolicy API is required by this chart configuration" -}}
{{- end -}}

This intentionally incomplete template guard is non-runnable. An authorized local render would need a documented capability fixture.

Plan schema evolution

Changing a CRD can affect stored objects and multiple applications, not only the release that carries the file. Served versions, storage versions, conversion and validation changes need coordinated migration evidence. A stricter schema may reject previously accepted objects; a removed version may break older clients and rollback candidates. Do not solve this by pretending crds behaves like templates or by adding a universal delete-and-recreate recipe. Identify affected data and clients, assign a qualified extension owner and plan compatibility transitions. This course explains the boundary without administering APIs, changing definitions or running a controller.

Review extension fixtures

Useful offline cases include the required API present, absent and present under an unsupported version. State whether absence should fail, disable an optional integration or select a documented alternative. Inspect custom-resource references and namespaces separately from the CRD’s cluster scope. A local render can show that a required resource is emitted, but dry-run cannot fully simulate adding a new API to the server’s discovery model. Keep platform installation validation outside the application render result and record the exact external prerequisite that an authorized environment check must later establish.

Common errors and fixes

A CRD file changes but installed schema stays old

Why it happens: Ordinary chart upgrade was assumed to manage crds evolution.
How to fix it: Use the separately owned extension upgrade process with data compatibility review.
Prevent it next time: Document CRD lifecycle limits in the application prerequisites.

A custom resource is accepted but has no effect

Why it happens: API registration was confused with controller reconciliation.
How to fix it: Identify the responsible controller and required behavior evidence.
Prevent it next time: Track schema, controller and instances as distinct components.

A required policy disappears during local render

Why it happens: A capability branch silently omitted a mandatory integration.
How to fix it: Fail with an explicit prerequisite message or supply the documented fixture.
Prevent it next time: Distinguish optional integrations from required security and behavior contracts.

Check your understanding

1. Why is a namespace application release a poor implicit owner for a shared CRD?

Show worked solution

The definition is cluster-scoped and can affect stored resources and clients beyond that application. Its upgrade and deletion risks therefore have a wider ownership boundary. Assign an explicit extension owner and compatibility process, and let the application document the required API and controller behavior instead of silently controlling shared platform state.

2. Capabilities reports the required API. What still prevents a guarantee that CatalogPolicy is enforced?