Helm values schema validation

Learn how Helm checks values against the Camunda 8 chart schema, how to bypass the check, and which deployment tools support the bypass.

The Camunda 8 Helm chart includes a values.schema.json file. Helm compares your values to this schema before it renders the chart templates. A value that doesn't match the schema stops the command.

How the validation works

• Helm checks the merged values against values.schema.json before it renders templates.
• A schema error stops helm install, helm upgrade, helm template, and helm lint.
• Helm has no warn-only mode. Each schema error is a hard failure. The chart also warns about unknown keys. See find unknown keys in your values.
• The chart documentation links and descriptions don't appear in Helm errors.
• The chart schema closes some objects. A closed object rejects any key that the schema doesn't list.

The error text depends on the Helm version. This example comes from a test chart that closes its root object, with the unknown key unk:

Helm version	Error text
3.10 to 3.19	- (root): Additional property unk is not allowed
3.20 and later, and 4.x	- at '': additional properties 'unk' not allowed

Find unknown keys in your values

Camunda 8.10 Helm chart versions 15.1.0+ warn about unknown keys in your values when Helm renders the chart templates. The warning doesn't stop the command.

• The chart compares your values to the keys that its schema declares. A key that the schema doesn't declare is an unknown key.
• For each unknown key, the chart adds a warning to the notes that helm install and helm upgrade print. The chart also writes the warnings to the <RELEASE-FULLNAME>-warnings ConfigMap.
• The check ignores global values, the values of dependency charts, and free-form maps such as annotations and labels.

The warning names the full path of the key:

[camunda][warning] UNKNOWN VALUES KEY: orchestration.foo. Helm ignores this key. Remove or correct it. A future chart version can reject unknown keys.

To fix the warning, remove the key or correct its name, then run the command again.

To read the warnings of an installed release, run:

kubectl get configmap <RELEASE-FULLNAME>-warnings --namespace <NAMESPACE> --output jsonpath='{.data.warnings}'

Replace <RELEASE-FULLNAME> with the chart's full name for your release. By default, the chart combines the Helm release name and camunda-platform, unless the release name already contains camunda-platform, in which case it uses the release name alone. For example, a release named camunda uses the ConfigMap camunda-camunda-platform-warnings.

The following top-level values affect the full name:

Setting	Effect
nameOverride	Replaces camunda-platform when deriving the full name, including the check for whether the release name already contains it.
fullnameOverride	Replaces the entire full name and takes precedence over nameOverride.

The chart truncates the full name to 63 characters and removes a trailing hyphen before appending -warnings.

To make unknown keys stop helm install, helm upgrade, and helm template, set global.strictValues: true. The command then fails with this error:

[camunda][error] Unknown values keys (global.strictValues=true): orchestration.foo

Setting	Default	Effect
global.strictValues	false	If true, unknown keys fail the render. If false, unknown keys only warn.

The --skip-schema-validation flag doesn't turn off this check, because the chart runs it during template rendering.

Fix the values first

Fix the values that the error names. This is the recommended action. The bypass removes a safety check.

To find problems before you run Helm, use the validate command of the Camunda Helm Toolkit. The toolkit page lists its exit codes.

Don't remove orchestration.fullnameOverride to fix a schema error. This change renames the StatefulSet. The brokers then start on new, empty volumes.

Bypass the validation

Validate your overrides before you bypass schema validation

Use the Camunda Helm Toolkit to check your values.yaml overrides for incorrect types, unsupported or deprecated settings, and configuration issues. Fix the findings before you turn off the schema validation.

Add the --skip-schema-validation flag to helm install, helm upgrade, helm template, or helm lint:

helm upgrade --install camunda camunda/camunda-platform \
  --values values.yaml \
  --skip-schema-validation

Keep these limits in mind:

• You need Helm 3.16.0 or later. Helm 3.15 returns Error: unknown flag: --skip-schema-validation. Helm 4 supports the same flag.
• The flag turns off all schema checks, including type checks. It doesn't only allow unknown keys.
• Camunda hasn't decided to turn on strict validation by default. This page describes the current behavior.

Check support in your deployment tool

Camunda tested these tools, except Pulumi, on a kind cluster with a test chart that has a strict schema.

Tool	Bypass possible	Setting	Tested version	Added in
Helm	Yes	--skip-schema-validation	3.16.0, 4.3.0	3.16.0
helm-diff	Yes	--skip-schema-validation	3.15.15	3.9.12
Helmfile	Yes	skipSchemaValidation: true for a release, or in helmDefaults	1.8.1	0.169.2 (host Helm 3.16 or later)
Argo CD	Yes	spec.source.helm.skipSchemaValidation: true	3.5.4	2.14.0
Flux helm-controller	Yes	spec.install.disableSchemaValidation and spec.upgrade.disableSchemaValidation	1.6.5	1.1.0 (Flux 2.4.0)
Terraform hashicorp/helm	No	No option. Terraform returns Unsupported argument.	3.3.0	Not applicable
Kustomize helmCharts	No	No option.	5.8.1	Not applicable
Pulumi Kubernetes	No documented option	Not tested. See pulumi-kubernetes#4635.	Not tested	Not applicable

For Terraform, a workaround is to use a local copy of the chart without values.schema.json. This workaround removes all schema checks.

For more information, see these upstream references:

• helm/helm#12743
• terraform-provider-helm#1609
• Argo CD Helm documentation
• Flux HelmRelease documentation

Known issues

Parent charts and global values

Helm passes the global values of a parent chart to each subchart. If a subchart schema closes its global object, Helm rejects the keys that the subchart doesn't list. The Camunda chart keeps its global object open, so this issue doesn't apply to the Camunda chart schema.

Choose a Helm version

Camunda recommends Helm CLI v4 and supports it for the full release cycles of Camunda 8.9 and 8.10. Camunda supports Helm CLI v3 (3.10 or later) until February 10, 2027, when upstream support ends. After February 10, 2027, Camunda no longer supports Helm CLI v3. Customers who continue to use Helm CLI v3 after that date do so at their own risk.

If you need the bypass, use Helm 3.16.0 or later.