⌂ Home

Editors, validation, and fixing broken manifests

Make YAML editing pleasant: VS Code extensions, safe online validators, kubectl dry-run and diff, and a troubleshooting matrix for the errors learners hit most often in labs.

Prerequisites: Part 1 and Part 2. This part is about workflow and debugging—so you spend less time staring at parse errors and more time learning Kubernetes behavior.

Visual Studio Code (recommended setup)

Daily driver for labs

YAML (Red Hat)

Extension ID: redhat.vscode-yaml. Provides syntax highlighting, schema-based validation when configured, and hover help for many Kubernetes resources if you associate schemas or use the Kubernetes extension below.

Kubernetes (Microsoft)

Extension ID: ms-kubernetes-tools.vscode-kubernetes-tools. Snippets for resources, navigation between manifests, and cluster integration. Pairs well with the YAML extension for fewer “mystery indent” mistakes.

Editor habits that prevent pain

Enable Render Whitespace so tabs show as arrows—delete them immediately in YAML.
Set Files: Insert Final Newline for cleaner diffs and POSIX-friendly files.
Keep the integrated terminal beside the manifest: apply, read errors, fix line, repeat.
Use Fold Level (folding) to collapse deep spec trees while editing one section.

Online YAML validators (paste with care)

Never paste manifests that contain real credentials, live tokens, or production Secret data into third-party websites. Use scrubbed examples or lab-only values.

YAML Lint — yamllint.com: quick syntax check for plain YAML.
Code Beautify YAML Validator — codebeautify.org/yaml-validator: validates and can format.
JSON ↔ YAML — useful when you have JSON from an API and want a readable YAML starting point (still verify against kubectl explain).

Use these when the error says error converting YAML to JSON—that usually means the file is not valid YAML yet, before Kubernetes even checks resource fields.

Validate with kubectl (best signal for K8s YAML)

Client dry-run (fast, offline-friendly)

kubectl apply --dry-run=client -o yaml -f your-manifest.yaml

Checks that kubectl can parse the file and build the object. Does not talk to admission webhooks.

Server dry-run (stronger checks)

kubectl apply --dry-run=server -f your-manifest.yaml

Requires a cluster connection. Catches more validation, including some policy and admission issues.

See what would change

kubectl diff -f your-manifest.yaml

Compares your file to live objects—great after hand-editing exported YAML.

Schema discovery

kubectl explain deployment.spec.template.spec.containers --recursive

Troubleshooting matrix

Error or symptom	Likely cause	Fix
`found character that cannot start any token`	Tab character or stray character in column 1	Replace tabs with spaces; show invisible characters in the editor.
`did not find expected key`	List item or child key mis-indented	Align `-` list markers; ensure `name:` under a container is deeper than `-`.
`mapping values are not allowed here`	Missing newline after `:` or broken flow	Put value on same line or indent block correctly on next line.
`unknown field` in Pod spec	Field belongs under Deployment `template`	Move under `spec.template.spec` for workload templates.
Service has no Endpoints	Selector labels mismatch Pod labels	Compare `spec.selector` to `metadata.labels` on Pods.
Resource unchanged but behavior wrong	Edited file but applied wrong path	Confirm `kubectl apply -f` path; use `kubectl diff`.

Lab-safe recovery loop

Read the full error message (line/column if given).
Fix YAML structure first; then fix Kubernetes field names.
Run kubectl apply --dry-run=client -f ....
Apply for real; use kubectl describe / logs for runtime issues.
If stuck, revert the file from git and re-apply a known-good manifest.

Series complete

You now have syntax (Part 1), object patterns and editing (Part 2), and tooling plus troubleshooting (Part 3).