Find the YAML value that breaks Kubernetes metadata
Admin ·
Kubernetes stores label and annotation values as strings. Check both the characters in a key and the value's parsed type before using a metadata fragment in a manifest.
Kubernetes Label and Annotation Validator
Fix the Boolean in the example label
Select Load example and Check metadata. The version label explicitly contains "1.20" and the optional label explicitly contains an empty string. The ready label contains an unquoted yes, which YAML 1.1 treats as a Boolean.
Change ready: yes to ready: "yes" and run the check again. Download kubernetes-metadata.json. Verify that ready contains the JSON string "yes" and that optional still contains "".
Kubernetes label syntax and character setKubernetes YAML-to-JSON conversion notes
Check the key prefix and the annotation budget
In ops.example.org/release-note, the DNS prefix identifies the owner and release-note is the required name part. The report measures the UTF-8 bytes for that complete key and its string value.
Change the release note to include extra characters. The new total counts the encoded text, including each byte of فريق. Kubernetes' generic validator caps the sum of all annotation key and value byte lengths at 262,144 bytes per object.
| Field | What the checker measures |
|---|---|
| Label name | Required name part, maximum 63 alphanumeric and allowed internal punctuation |
| Label value | An empty string or up to 63 allowed characters |
| Annotation value | String contents and its UTF-8 byte contribution |
Kubernetes label syntax and character setKubernetes annotation keys and valuesKubernetes apimachinery v0.35 object metadata validation
Read portability notices before using the export
Try OPS.example.org/release-note as an annotation key. The generic Kubernetes annotation validator folds case when checking it. A lowercase prefix follows the documented DNS rules and helps when the key is used in other tooling.
The downloaded object contains the labels and annotations under metadata. Use it as a fragment for your intended manifest. The target API kind and its admission policies determine which metadata is accepted in that deployment.
Kubernetes annotation keys and valuesKubernetes apimachinery v0.35 object metadata validation
Common questions
Why can the same punctuation pass as annotation text but fail in a label value?
Annotation string values can contain spaces, punctuation and multiline text. A nonempty label value allows letters and digits at its edges, with dots, dashes and underscores inside.
How do I give an annotation a multiline value?
Use a YAML block string beneath the key or encode the line breaks inside a JSON string. Check the byte total after parsing, since the decoded line breaks are part of the annotation value.
Sources
Put it into practice.
- Kubernetes Label and Annotation Validator
- Kubernetes Resource Name Sanitizer
- YAML Validator
- JSON formatter