Configuration guides

Find the YAML value that breaks Kubernetes metadata

·

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.

Check the key prefix and the annotation budget
FieldWhat the checker measures
Label nameRequired name part, maximum 63 alphanumeric and allowed internal punctuation
Label valueAn empty string or up to 63 allowed characters
Annotation valueString 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.

Related guides