Helm Deployment Fail: One Quote Triggers Kubernetes Error — YAML Types Deep Dive

Incident Reproduction

During a Helmfile deployment of a microservice platform, a component installation failed with the error:

Error: 1 error occurred:
  * Deployment in version "v1" cannot be handled as a Deployment:
    json: cannot unmarshal string into Go struct field
    PodSpec.spec.template.spec.affinity of type v1.Affinity

The error indicates Kubernetes expected the affinity field to be an object (struct) but received a string. Inspection of the corresponding values.yaml revealed:

k8s:
  affinity: ""  # <-- the problem

Changing affinity: "" to affinity: {} resolved the issue. A single quote difference caused the entire service installation to fail.

Root Cause Analysis: YAML Types and Kubernetes Deserialization

2.1 YAML Type System

YAML is a strongly typed serialization format; different syntaxes produce distinct data types: affinity: "" → string → JSON equivalent:

"affinity": ""

affinity: ''

→ string → JSON equivalent:

"affinity": ""

affinity: {}

→ empty mapping → JSON equivalent:

"affinity": {}

affinity:

→ null → JSON equivalent:

"affinity": null

affinity: null

→ null → JSON equivalent:

"affinity": null

2.2 Kubernetes Deserialization Mechanism

The Kubernetes API server converts incoming YAML to JSON and uses Go's JSON deserializer to map to Go structs. The affinity field in PodSpec is defined as:

type PodSpec struct {
    // ...
    Affinity *v1.Affinity `json:"affinity,omitempty"`
    // ...
}

This is a struct pointer that accepts only an object ( {}) or null, never a string. The full failure chain:

values.yaml (affinity: "")
  ↓ Helm template rendering
Deployment Manifest (affinity: "")
  ↓ YAML → JSON conversion
{"spec":{"template":{"spec":{"affinity":""}}}}
  ↓ Go JSON deserialization
❌ cannot unmarshal string into ... v1.Affinity

Comparison of Three "Empty" Styles

3.1 Behavior in Templates

Assume a Helm template using with guard:

{{- with .Values.affinity }}
affinity:
  {{- toYaml . | nindent 8 }}
{{- end }}

Rendering results for different values:

values syntax: affinity: {} | .Values.affinity value: empty map {} | with evaluation: false (empty map is falsy) | Rendered output: Does not render affinity field ✅

values syntax: affinity: | .Values.affinity value: nil | with evaluation: false (nil is falsy) | Rendered output: Does not render affinity field ✅

values syntax: affinity: null | .Values.affinity value: nil | with evaluation: false (nil is falsy) | Rendered output: Does not render affinity field ✅

values syntax: affinity: "" | .Values.affinity value: empty string "" | with evaluation: false (empty string is falsy) | Rendered output: Does not render, but escapes by luck

All four appear to suppress rendering. However, not all templates use with for protection. If a template directly writes:

spec:
  template:
    spec:
      affinity: {{ toYaml .Values.affinity | nindent 8 }}

then "" gets rendered as a string, submitted to the API server, and immediately fails.

3.2 Conclusion

Both null and {} work, but {} is the superior choice for reasons detailed below.

Helm Chart Best Practices

4.1 Helm Official Best Practices

Helm documentation recommends: every property in values.yaml should have a default value using the type‑appropriate zero value. Practical rules:

# ✅ Standard values.yaml style

# Numeric → 0 or concrete number
replicaCount: 1

# String → ""
image:
  repository: nginx
  tag: ""
  pullPolicy: IfNotPresent

# Boolean → false
autoscaling:
  enabled: false

# Object/struct → {}
resources: {}
nodeSelector: {}
affinity: {}
podAnnotations: {}
podSecurityContext: {}
securityContext: {}

# Array/list → []
tolerations: []
extraEnvVars: []
imagePullSecrets: []

4.2 Why {} Beats null

Reason 1: Self‑documentation — Seeing affinity: {} instantly signals an object is expected; affinity: or affinity: null leaves the type ambiguous.

Reason 2: Template safety — In Go templates, operating on nil can panic (e.g., merge .Values.affinity .defaultAffinity fails if affinity is nil). An empty map {} safely participates in merge, range, etc.

Reason 3: Community consistency — Major Helm chart repositories (Bitnami, Prometheus Community, Ingress‑Nginx) uniformly use {} and [] for empty objects and arrays. Following this convention reduces collaboration friction.

4.3 Defensive Template Programming

Good chart templates guard with with so that regardless of whether the user supplies {}, null, or omits the key, no erroneous field is rendered:

# ✅ Recommended: wrap with `with` to suppress field on empty values
spec:
  template:
    spec:
      {{- with .Values.affinity }}
      affinity:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.nodeSelector }}
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.tolerations }}
      tolerations:
        {{- toYaml . | nindent 8 }}
      {{- end }}

Type Cheat Sheet for Common Kubernetes Fields

Quick reference for Kubernetes field types and correct empty‑value syntax:

affinity — K8s Type: v1.Affinity (object) — Empty syntax: {} — Wrong syntax: "" nodeSelector — K8s Type: map[string]string — Empty syntax: {} — Wrong syntax: "" tolerations — K8s Type: []v1.Toleration (array) — Empty syntax: [] — Wrong syntax: "" or {} resources — K8s Type: v1.ResourceRequirements (object) — Empty syntax: {} — Wrong syntax: "" securityContext — K8s Type: v1.SecurityContext (object) — Empty syntax: {} — Wrong syntax: "" env — K8s Type: []v1.EnvVar (array) — Empty syntax: [] — Wrong syntax: "" or {} volumeMounts — K8s Type: []v1.VolumeMount (array) — Empty syntax: [] — Wrong syntax: "" or {} annotations — K8s Type: map[string]string — Empty syntax: {} — Wrong syntax: "" labels — K8s Type: map[string]string — Empty syntax: {} — Wrong syntax: "" Rule of thumb: objects use {} , arrays use [] , never substitute "" for them.

Summary

YAML type system : "", {}, null are three completely different types.

Kubernetes deserialization : API server uses Go's strong‑typed JSON parsing; type mismatch causes immediate error.

Helm rendering chain : values → template → manifest → API server; each step can amplify a type error.

Industry standards : objects use {}, arrays use [], write defensive templates.

Seemingly trivial YAML format issues are frequent causes of production incidents. Standardizing values upfront — using correct type zero values — is a fundamental Helm engineering practice.