Kustomize 5.7.0 アップデートで出た警告を修正した話

ある日、PipeCD の plan-preview を実行すると、今まで見たことのない警告がログに出るようになりました。

Warning: 'commonLabels' is deprecated. Please use 'labels' instead.
Run 'kustomize edit fix' to update your Kustomization automatically.

原因はすぐに判明。

Kustomize を 5.7.0 以上にアップデートしたことで、以前から使っていた commonLabels フィールドが非推奨扱いになったためでした。

見て見ぬふりもできないので、影響範囲を確認して対処していきましょう。

commonLabels と labels の違いを理解する

そもそも commonLabels とは

commonLabels は Kustomize の kustomization.yaml で使えるフィールドで、管理するすべてのリソースに共通のラベルを付与できます。

# 変更前
commonLabels:
  app: my-app

シンプルに書けて便利なのですが、Kustomize 5.7.0 以降は非推奨となりました。

labels への移行で気をつけること

単純に commonLabels を labels に書き換えればよいわけではありません。

commonLabels には Deployment の selector.matchLabels にもラベルを付与するという挙動が存在します。

labels フィールドはデフォルトではその挙動を持たないため、includeSelectors: true を明示的に指定して対応する必要があります。

# 変更後
labels:
  - pairs:
      app: my-app
    includeSelectors: true

この点を見落とすと、既存の Deployment のセレクターが変わってしまい意図しない挙動になる可能性があるため注意が必要です。

変更前後を kustomize build で差分チェックする

ローカルで警告を再現する

わざわざ構成ドリフトの差分などを確認するのは手間がかかるので、ローカルで kustomize build して簡単に確認しちゃいましょう。

クラスターへの apply は行わないため、リモート環境には一切影響しません。

# kustomizeをインストールしていない場合
brew install kustomize

# 変更前
kustomize build ./manifests/my-app

diff で確認する

変更前後のマニフェストをそれぞれファイルに出力して diff を取ります。

# kustomization.yaml 変更前
kustomize build ./manifests/my-app > before.txt

# kustomization.yaml 変更後
kustomize build ./manifests/my-app > after.txt

diff -u before.txt after.txt | grep '^[+-]'

今回の変更では、結果は以下の1行だけでした。

-# Warning: 'commonLabels' is deprecated. Please use 'labels' instead. ...

警告の除去のみで、出力されるマニフェストに差分がないことを確認できました。

大量ファイルへの一括対応

影響範囲を把握する

まず grep で影響ファイルを洗い出します。

grep -rl commonLabels ./manifests

今回は100ファイル以上が対象と、なかなかのボリュームでした。

手動での修正は現実的ではないため、以下の Python スクリプトで一括変換しちゃいましょう。

Python スクリプトで一括変換する

import re
import glob

pattern = re.compile(r'^commonLabels:\n  app: (.+)$', re.MULTILINE)

for f in glob.glob("manifests/**/kustomization.yaml", recursive=True):
    with open(f, 'r') as fh:
        content = fh.read()
    if 'commonLabels:' not in content:
        continue
    def replace(m):
        app = m.group(1)
        return f"labels:\n  - pairs:\n      app: {app}\n    includeSelectors: true"
    new_content = pattern.sub(replace, content)
    with open(f, 'w') as fh:
        fh.write(new_content)

反映順序にも注意する

今回は manifest リポジトリと、それを参照する kubernetes リポジトリの 2 層構成の環境で問題に遭遇しました。

一部、kubernetes リポジトリ側で commonLabels を独自定義して上書きしているモジュールがあったため、kubernetes リポジトリ側を先にマージしてから manifest リポジトリ側を反映する順序にしました。

逆順にすると kubernetes 側の commonLabels が残ったままになり、警告が出続けてしまいます。

まとめ

• Kustomize 5.7.0 以降、commonLabels は非推奨。labels + includeSelectors: true に置き換える
• kustomize build でローカルに警告を再現でき、変更前後の差分チェックにも使える
• 複数リポジトリにまたがる場合は、参照先より参照元（上書き側）を先に反映する

kustomize edit fix コマンドによる自動変換も公式から提供されているので、Kustomize がインストールされていれば活用するのも手です。

saratoga

フリーランスエンジニア

XYouTube

仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。