Kubernetes のマニフェストを書いていて error: error validating や error: error parsing に遭遇した経験は一度はあると思う。YAML はインデントで構造を表現するので、スペース 1 つのズレで壊れる。
この記事では、K8s YAML のデバッグを効率的に進める手順をまとめる。
ステップ 1: YAML の構文自体が正しいか確認する
K8s のバリデーションエラーの前に、そもそも YAML として壊れていることが多い。
よくある構文エラー
タブ文字の混入:
# NG: タブ文字を使っている
spec:
replicas: 3
YAML ではタブは使えない。スペースのみ。エディタの設定で「タブをスペースに変換」を有効にしておく。
インデントのズレ:
# NG: containers のインデントが 1 つ足りない
spec:
template:
spec:
containers:
- name: nginx
正しくは:
spec:
template:
spec:
containers:
- name: nginx
YAML → JSON 変換で構造を確認する
YAML のインデントが正しいかどうかは、JSON に変換すると一目瞭然になる。ネストが意図通りになっているかを JSON のブレースで確認できる。
FormatArc の YAML to JSON ツール にマニフェストを貼ると、構文エラーがあれば行番号付きで教えてくれる。エラーがなければ JSON として正しい構造が表示される。
ステップ 2: kubectl でドライランする
YAML の構文が正しいことを確認したら、次は K8s のスキーマバリデーション。
kubectl apply -f deployment.yaml --dry-run=client
--dry-run=client はクラスタに適用せず、マニフェストの妥当性だけをチェックする。サーバー側のバリデーションも含めたい場合は --dry-run=server を使う。
ステップ 3: kubectl diff で差分を確認する
既存リソースとの差分を確認してから適用する。
kubectl diff -f deployment.yaml
意図しないフィールドが変わっていないかをここで確認できる。
ステップ 4: よくあるハマりパターン
コンテナポートの書き方
# NG: ポートを文字列で書いている
ports:
- containerPort: "80"
# OK: 数値で書く
ports:
- containerPort: 80
YAML は "80" を文字列として解釈する。K8s のスキーマは integer を期待するのでエラーになる。
ラベルセレクタの不一致
metadata:
labels:
app: nginx
spec:
selector:
matchLabels:
app: ngnix # typo
selector.matchLabels と template.metadata.labels が一致しないと Pod が見つからない。地味だが頻発する。
複数ドキュメントの区切り
---
apiVersion: v1
kind: Service
# ...
---
apiVersion: apps/v1
kind: Deployment
# ...
--- を忘れると 2 つ目のリソースが無視される。
デバッグの流れまとめ
1. YAML 構文チェック（JSON 変換で構造確認）
2. kubectl --dry-run で K8s スキーマチェック
3. kubectl diff で差分確認
4. kubectl apply で適用
YAML の構文エラーは K8s のエラーメッセージだけだと原因がわかりにくいので、まず JSON に変換して構造を確認するステップを挟むと効率がいい。
ブラウザでサクッと変換したい場合は FormatArc が便利: https://formatarc.com/ja/yaml-to-json/