KubeCon EU 2025 Recap - Kubernetes CRD Design for the Long Haul: Tips, Tricks, and Lessons Learned / Kubernetes Meetup Tokyo #70 / k8sjp70-crd-long-haul-recap

Kubernetes Meetup Tokyo #70 KubeCon EU 2025 Recapでの発表資料です

Transcript

1. Kubernetes CRD Design for the Long Haul: Tips, Tricks, and Lessons Learned Christian Schlotter, Broadcom & Fabrizio Pandini, VMware by Broadcom Shingo Omura @everpeace Kubernetes Meetup Tokyo #70 https://speakerdeck.com/everpeace/k8sjp70-crd-long-haul-recap KubeCon + CloudNativeCon Europe 2025 Recap Icons made by Freepik from www.flaticon.com スライド youtube
2. @everpeace Shingo OMURA / @everpeace ▶ AI Platform Engineer @ LINEヤフー株式会社 ▶ ex-Woven By Toyota, ex-PFN ▶ 主な活動SIG: sig-node, sig-scheduling ◦ KEP-3619: Fine-grained supplemental groups control (Beta) ◦ KEP-5055: DRA: device taints and tolerations (Alpha)
3. @everpeace なぜRecapするのか？ • CRD/Operatorは一度は書いたことのある人は多いはず • でも長期にわたって互換性を保ちつつAPIを進化させるのは難しい • そのためのアンチパターン, Tips, ベストプラクティスが詰まっていた • Operator開発者として発表にとても感銘を受けた • 他のトピック(AIとかマルチクラスタとか)もあるけどなぜこれ？ →より多くのKubernetes/Operator開発者に共有したいと感じた
4. Cluster APIメンテ ナのお二人です ☝
5. @everpeace 長期運用に一番大切なこと: 意図しないapiVersionのBumpを避けること できる限り同じ apiVersion を使い続ける apiVersionの Bumpは細心注意 かつ意図的に
6. @everpeace ミスの入り込む場所: Go, CRD生成, CRD Goの中 CRD生成 Yaml (ユーザが直接利 用) Icons made by Freepik from www.flaticon.com
7. @everpeace (まとめ) 長期運用に耐えるCRD設計のアンチパターン/ベストプラクティス 🙅 アンチパターンと回避策 ◦ (Go) 外部APIの型を自分の型に埋め込む → 必要部分だけコピーして独自に進化させる ◦ (Go) 複数のCRDで同じ型を使い回す → 別々の型を定義する ◦ (生成) CRD Markerつけわすれ → Kubernetes API Linter(KAL)で予防 ◦ (生成) GitOps(SSA)フレンドリじゃないAPI → SSA Marker(+listType,+listMapKey)つける ◦ (Yaml) 汎用的すぎるフィールド名 → 具体的な名前 (❌ready, ⭕provisioned) ◦ (Yaml) Camelケース繋げすぎのフィールド名 → 階層化する (❌nodeDrainTimeout ⭕nodeDrain.timeout) 🙆 ベストプラクティス ◦ APIは上から読んでいって意味がわかるように設計する ◦ プロジェクト内の用語(Glossary)を定義して一貫性を持って使う ◦ Kubernetes API Linter(KAL)を使ってミスを予防 ◦ 非互換/非推奨リリース時のルールを守る ◦ ピアレビューを活用したり他のプロジェクトを参考にする c.f. Christian Schlotter and Fabrizio Pandini “Kubernetes CRD Design for the Long Haul: Tips, Tricks, and Lessons Learned,” KubeCon+CloudNativeCon Europe 2025
9. @everpeace 🙅アンチパターン: 外部APIの型を自分の型に埋め込む(1) 🤔なぜだめ？ • 依存先apiVersionも進化する(最悪Drop) • 依存先がBumpされると引きづられて こちらもBumpする羽目に 💡どうする？ • "Copy, adapt and evolve" • コピーして内部で変換する • 独自に進化させる
10. @everpeace 🙅アンチパターン: 外部APIの型を自分の型に埋め込む(2) 🤔なぜだめ？ • 不要なフィールドが紛れ込む • 一度入れてしまったらフィールド 削除難しい 💡どうする？ • "Copy, adapt and evolve" • 必要なフィールドだけを持つ独自の 型を作って独自に進化させる (metav1.{Time,ObjectMeta}みた いなのは例外) 📝UpstreamでもObjectReferenceの新規利用は 非推奨
11. @everpeace 🙅アンチパターン: 複数のCRDで同じ型を使い回す 🤔なぜだめ？ • 文脈の異なるCRDで共用すると ◦ 不要なフィールドが混ざる ◦ 変更時がどちらにも波及する 💡どうする？ • "Copy, adapt and evolve" • 一見共用できるように見えてもそれぞれ個 別に型を作って進化させる
12. @everpeace ユーザ側に影響があるのはYaml側 開発者が多くの時間 を費やすのはこっち ユーザが依存する のはこっち だけど 💡 ユーザ影響はCRD(Yaml)側で起きることを覚えておく 💡 Go側に変更があった場合、Yaml側でどんな変更があったか ちゃんと確認すると良い
13. @everpeace 🙆ベストプラクティス: 非互換/非推奨リリース時の互換性ルールを守る 💡 Binaryバージョン • ~SemVerが良い • Breaking Changeは 要Minor Bump 💡 APIバージョン • Deprecationは 1年 or 3 release version猶予
14. CRD(Yaml)の生成 に関わる部分
15. @everpeace 🙅アンチパターン: CRD Markerつけ忘れ 🤔なぜだめ？ • OptionalなのにOptionalじゃなくなる • Validationがない/中途半端 • validation系のMarker追加はBreaking Change 💡どうする？ • Kubernetes API Linter(KAL)を 使って予防する
16. @everpeace 🙆ベストプラクティス: Kubernetes API Linter(KAL)を使う 📝 移行されていました kubernetes-sigs/kube-api-linter
17. @everpeace 🙅アンチパターン: GitOpsフレンドリーじゃないAPI(SSA Markerが適切じゃない) 🤔なぜだめ？ • 例えばリスト(defaultは+atomic) • GitOpsしたリストフィールドに 別Controllerが上書き→GitOps→ 上書き→・・・ 💡どうする？ • +listType=map,+listMapKey=name といったServerSideApply Markerを適 切つけて複数の主体が衝突なく更新でき るようにする