Values Schemas, CRDs and Library Charts

Guardrails for chart users

A values.schema.json file in the chart root describes allowed values with JSON Schema; Helm validates merged values against it during install, upgrade, lint and template, so a typo like replicaCont or a string where a number belongs fails immediately with a clear message. CRDs placed in the crds/ directory are installed before other resources on first install, but Helm never upgrades or deletes them, by design, because deleting a CRD deletes every custom resource of that type. Charts that must upgrade CRDs often ship them as templates or as a separate chart instead. A library chart (type: library) contains only named templates, such as standard labels or a common Deployment shape, for other charts to include; it cannot be installed itself. The annotation helm.sh/resource-policy: keep tells Helm to leave a resource (such as a PersistentVolumeClaim) in place on uninstall.

A small values schema

Wrong types, unknown keys and missing required fields fail before anything reaches the cluster.

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "apiUrl"],
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "apiUrl": { "type": "string", "pattern": "^https://" },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      },
      "additionalProperties": false
    }
  }
}

Uninstall can delete your data

PersistentVolumeClaims created by a release are deleted on helm uninstall unless they carry helm.sh/resource-policy: keep or come from a StatefulSet's volume claim templates. Check before uninstalling anything stateful.

Quick check: What happens to CRDs in a chart's crds/ directory when you run helm upgrade?

• They are upgraded to the new definition
• They are deleted and recreated
• They are not upgraded; Helm only installs them on first install
• They are converted to templates