TIL: Debugging Helm Charts with Sparse Documentation

03 May 2026

Date: 2026-05-03 Context: NetBird Helm chart management.configmap was empty — pod failed with “unexpected end of JSON input”

The Problem Pattern

helm show values gives you field names and types but not always what the values mean or what format they expect. The NetBird chart had:

management:
  configmap: |- # Placeholder for ConfigMap data

No example, no schema — just a comment saying “placeholder”.

Step 1 — Pull and Inspect the Chart Templates

helm pull <repo>/<chart> --untar --untardir /tmp/chart-inspect

Then find which templates use the field you’re confused about:

grep -rl "configmap\|management.json" /tmp/chart-inspect/

Reading the template directly shows exactly how the value is used:

# management-cm.yaml
data:
  management.json: |-
    {{- .Values.management.configmap | nindent 4 }}

This confirmed: the chart renders management.configmap verbatim as the file content. No generation, no templating — you provide the full JSON yourself.

Step 2 — Check the Chart’s Own Examples

Charts often ship example values files that aren’t shown by helm show values:

ls /tmp/chart-inspect/<chart>/examples/

Find the example closest to your setup (same ingress controller, same IdP type):

cat /tmp/chart-inspect/<chart>/examples/traefik-ingress/authentik/values.yaml

Examples show the real field names, real JSON structure, and real env var names — far more useful than the default values file.

Step 3 — Cross-Reference with a Known-Working IdP

If your IdP isn’t in the examples (e.g. Keycloak when only Authentik/Auth0 examples exist), map field by field:

Authentik field	Keycloak equivalent
`https://idp.example.com/application/o/netbird/jwks/`	`https://keycloak.../realms/netbird/protocol/openid-connect/certs`
`https://idp.example.com/application/o/token/`	`https://keycloak.../realms/netbird/protocol/openid-connect/token`
`https://idp.example.com/application/o/device/`	`https://keycloak.../realms/netbird/protocol/openid-connect/auth/device`
`https://idp.example.com/application/o/authorize/`	`https://keycloak.../realms/netbird/protocol/openid-connect/auth`

Keycloak’s OIDC discovery endpoint (/.well-known/openid-configuration) lists all these URLs — use it to verify.

Step 4 — Validate the ConfigMap Before Deploying

After updating values, dry-run the render to check the output before touching the cluster:

helm template netbird netbird/netbird \
  --values config/netbird-values-local.yaml \
  | grep -A50 "management.json"

Confirm the JSON is valid and not empty before deploying.

Summary

helm pull --untar → read the actual templates
Check examples/ in the unpacked chart
Map your IdP’s endpoints from the OIDC discovery URL
helm template to validate rendering before deploy