Document YAML injection risks in chart templates

docs/chart_template_guide/yaml_techniques.md

@@ -100,6 +100,53 @@ All inline styles must be on one line.
   characters. The only escape sequence is `''`, which is decoded as a single
   `'`.
 
+### Strings in Templates
+
+When string values are inserted from `.Values`, they are parsed as part of the
+final YAML document. If a value can come from a user or another system,
+rendering it as a bare word can allow YAML syntax in the value to change the
+generated structure.
+
+```yaml
+data:
+  drink: {{ .Values.favorite.drink }}
+```
+
+For example, a string that contains a newline followed by another key could add
+unexpected data to the rendered manifest. Quote string values so YAML treats the
+rendered value as a scalar:
+
+```yaml
+data:
+  drink: {{ .Values.favorite.drink | quote }}
+```
+
+The same rule applies after constructing a string from multiple values. For
+example, apply `quote` to the final string produced by `printf` or `print`.
+
+This guidance is for string values. Other scalar types, such as integers and
+booleans, may need to remain unquoted when the Kubernetes field expects that
+type. Define the expected type in the chart values and render it accordingly.
+
+When a value is intentionally structured data, serialize the complete value and
+indent it for its location in the manifest:
+
+```yaml
+metadata:
+  annotations:
+    {{- .Values.podAnnotations | toYaml | nindent 4 }}
+```
+
+Using `toYaml` with the correct indentation preserves the intended YAML
+structure, but it does not make arbitrary content safe or validate that the
+result is appropriate for a particular Kubernetes field. For values that may
+come from untrusted sources, chart authors should constrain the accepted values.
+Helm can validate chart values with a
+[`values.schema.json`](/topics/charts.mdx#schema-files) schema, and templates can
+fail rendering with functions such as
+[`required`](/chart_template_guide/function_list.mdx#required) or
+[`fail`](/chart_template_guide/function_list.mdx#fail) for simple checks.
+
 In addition to the one-line strings, you can declare multi-line strings:
 
 ```yaml