Helm values設計｜公開する値の決め方

第9回で届ける経路が決まりました。次に決めるのは、開発者に何を書かせるかです。

共通のHelm Chartを用意している組織では、こういう状況がよく起きます。開発チームから「このパラメータも公開してほしい」という要望が絶えず届き、断る基準がないため、要望が来るたびに個別に判断している。結果としてvaluesの項目が増え続け、何のために抽象化したのか分からなくなります。

本記事は、その基準を作ります。そして重要な点を先に述べます。公開・非公開の線は、本記事で新しく引くものではありません。第2回から第5回までで既に引かれています。本記事の作業は、それを対応表にして、機械が検証できる形にすることです。

なお本記事は、Helm や Kustomize、IDPを主題とするため、内容の大部分はクラウドに依存しません。

目次

1. 第2回で決めた所有権モデルが、この記事の仕事を決めている
   1. この記事で作る成果物
2. valuesの設計は「公開しない」ことの設計
   1. 非対称性が既定を決める
   2. 公開を求められたときの3つの問い
   3. 公開する場合は、範囲も決める
   4. 既定値は「考えずに使ったときに安全な値」にする
3. 公開・非公開の線は既に引かれている
   1. 対応表を作る
   2. 表に入らない項目が出てきたら
   3. 第3回のGateway APIが、そのまま公開範囲になる
4. インターフェースを実行可能にする
   1. 仕様書は読まれない
   2. Chartのバージョニングと、古いバージョンの寿命
   3. 共通部分をどこに置くか
5. リポジトリ構成 ― 第8回の保留を解く
   1. 第8回で決めた基準
   2. マニフェスト側に固有の2つの入力
   3. マニフェスト側のディレクトリ構成
   4. サービスごとに分けるか、1つにまとめるか
6. IDPは要否から判定する
   1. 第2回のSLAが守れているか
   2. 入れる場合、何を載せるか
   3. サービスカタログの単位
   4. 入れないと決めた場合に書くこと
7. 【実務テンプレート】マニフェスト抽象化・IDP設計書
8. 次回予告

第2回で決めた所有権モデルが、この記事の仕事を決めている#

最初に、自分の組織がどのモデルを選んだかを確認してください。

第2回で3つの所有権モデルを比較し、モデルB（共通Helm Chart型）を主軸として選びました。開発チームが4〜15の組織を想定した選択です。この分担では、運用チームがChartを所有し、開発チームがvaluesを書きます。

この選択が、本記事の作業を規定しています。

モデルAを選んだ組織が本記事の前半を読んでも、作るべき成果物がありません。設計書の目次は、前の回の決定によって変わります。本連載を通読している読者には、この構造が見えているはずです。

この記事で作る成果物#

2つです。

1. valuesのインターフェース仕様。公開するパラメータの一覧と、それぞれの制約
2. マニフェストリポジトリの構成。第8回で保留した「インフラコードと同じリポジトリに置くか」の判断を含みます

もう1つ、第9回からの引き継ぎがあります。第9回で「イメージは同一、環境の差は設定で表現する」と決めました。その設定の構造を決めるのが本記事です。イメージを同一にした結果、環境ごとの違いはすべてvaluesかoverlayに集まります。そこが設計対象になります。

逆に、本記事が扱わないものも明示します。ここで設計するのはインターフェースそのもので、その使い方を開発者に説明するガイドは第18回の管轄です。「開発者に提供するもの」という言葉が両方にまたがるため、この線を守ってください。設計書を書く相手は運用チーム、ガイドを書く相手は開発チームです。

valuesの設計は「公開しない」ことの設計#

公開するパラメータを選ぶ作業だと考えると、基準が作れません。公開しないことを既定にすると、基準が1つで足ります。

非対称性が既定を決める#

公開と非公開は対称ではありません。

第2回で運用チームのSLAを定めたとき、「Chartの破壊的変更は30日前に告知する」という項目を入れました。つまり一度公開したパラメータは、30日の告知期間を経なければ削除できない資産になります。

しかも、告知しても移行しないチームは出ます。すると古い形式を受け付ける互換コードがChartに残り、それがまた資産になります。公開は、テンプレートに1行足す作業ではなく、恒久的な保守対象を増やす作業です。

したがって既定はこうなります。

公開には理由が要る。非公開には理由が要らない。迷ったら公開しない。

この既定には運用上の利点があります。パラメータ追加の要望が来たときに、断る理由を毎回考える必要がなくなります。「公開すると恒久的な保守対象になるため、必要性の説明をお願いします」という一貫した応答ができます。そして説明を受けたうえで公開するなら、それは判断であって妥協ではありません。

公開を求められたときの3つの問い#

要望を受けたら、次の3つを確認します。

1. その値を環境ごとに変える必要が、本当にあるか
2. その値を間違えたときに、何が起きるか
3. それは運用チームが決めるべき値ではないか

1番目を補足します。第9回で「イメージは同一、環境の差は設定で表現する」と決めましたが、これは「環境ごとに変わらないものまで設定にする」という意味ではありません。全環境で同じ値なら、テンプレートに固定値として書けば足ります。設定にすると、環境ごとに違う値を書ける状態が生まれ、それは事故の余地です。

2番目が最も重要です。間違えると本番が止まる値は、公開しないか、範囲を厳しく縛ります。たとえば、レプリカ数を0にできる状態を公開すると、いつか誰かが0にします。開発者を疑うのではなく、手が滑る余地を残さないという設計の問題です。

3番目は、次章の対応表で機械的に判定できます。第4回と第5回で「運用チームが決める」と分類したものに該当するなら、公開しません。

3つとも「公開しない」に倒れる場合、選択肢は2つです。Chartのテンプレートに固定値として書くか、運用チームが管理する別の場所に置くか。後者は、たとえばNamespaceに付ける設定や、運用チームだけが変更できるConfigMapです。

公開する場合は、範囲も決める#

公開するという判断は、「自由に書ける」という意味ではありません。3つの制約を掛けられます。

範囲について、第4回との接続を確認してください。第4回でLimitRangeによるPod単位の上下限を決めました。valuesの側でも同じ範囲を表現しておくと、適用前に弾けます。

適用時に弾かれるのと、書いた時点で弾かれるのでは、直すまでの時間がまったく違います。適用時のエラーは、原因がLimitRangeであることに気づくまでに時間がかかります。valuesの検証で止まれば、書いた本人がその場で理解できます。

この制約を、機械が読める形にする方法は後半で扱います。

既定値は「考えずに使ったときに安全な値」にする#

公開すると決めたパラメータには、既定値を置くかどうかの判断が続きます。ここを軽く扱わないでください。

既定値は、開発者が何も考えなかったときに適用される値です。そして現実には、大半のパラメータは既定値のまま使われます。つまり既定値の設計は、大半のワークロードの設定を決めているのと同じです。

基準は1つです。既定値は、安全側に置きます。

Requestsについては、既定値を置くよりも必須にして省略できなくするほうが安全な場合があります。既定値があると、それが自分のアプリに合っているかを誰も検討しません。第11回で算出方法を扱うのは、この値を考えさせるためです。

そして、もう1つ判断が要ります。既定値の変更は破壊的変更かどうかです。

形式上は破壊的ではありません。valuesを書き換える必要がないためです。しかし挙動は変わります。既定値のまま使っていたチームは、Chartを上げただけで設定が変わったことになります。

したがって、規約として決めてください。既定値の変更は、破壊的変更として扱う。第2回で決めた30日前の告知の対象に含めます。「valuesを書き換えなくても済む変更」と「挙動が変わらない変更」は別物です。後者だけが非破壊です。

公開・非公開の線は既に引かれている#

ここが本記事で最も伝えたい点です。本記事で新しい判断はしません。

対応表を作る#

過去回の決定を転記すると、次の表になります。

この表を見て確認してください。新しい判断は1つも入っていません。すべて過去回で決めたことの転記です。

そして、ここから診断ができます。

線が引けないと感じるなら、それは過去回のどれかが未決だということです。「Requests/Limitsを公開すべきか迷う」という状態は、第11回で誰が値を決めるかが定まっていないことを意味します。本記事で迷うのではなく、該当する回に戻ってください。

イメージのダイジェストだけは、少し性質が違います。valuesの項目としては存在しますが、人間が書くものではありません。第9回で決めたとおり、パイプラインが更新します。「公開する／しない」の2択では表現できない第3の状態があるということです。設計書には「誰が書くか」の列を設けてください。

表に入らない項目が出てきたら#

実際に設計すると、過去回のどこにも出てこない項目が必ず出てきます。アプリケーション固有の設定、外部サービスの接続先、機能フラグ。

そのときその場で公開の可否を判断しないでください。先に決めるのは「これはどの回の管轄か」です。

理由があります。本記事で場当たり的に決めた線は、後の回の設計と矛盾します。たとえば外部サービスの接続先を安易に公開すると、第5回で決めたシークレット管理の方針（値はSecret Managerに置き、Terraformにも通さない）と衝突します。接続先が公開パラメータなら、開発者が任意の宛先を指定できることになり、第5回の層3で設計した通信制御の前提が崩れます。

判定に迷う項目の扱いを、設計書に欄として用意してください。「未決」と書けることが重要です。第6回でADRについて「空欄にしない」と書いたのと同じで、判断していないことを記録できる状態にします。

第3回のGateway APIが、そのまま公開範囲になる#

1つ、過去回の決定がそのまま使える例を挙げます。

第3回で GKE Gateway Controller の責務分割を確認しました。GatewayClass はインフラストラクチャ提供者、Gateway は運用チーム、HTTPRoute は開発チームという対応です。

この分割が、そのままvaluesの公開範囲になります。開発チームに公開するのは、HTTPRouteに相当する部分だけです。どのホスト名で受けるか、どのパスをどのServiceに振るか。Gateway自体の設定は公開しません。

第3回でこの分割を確認したときは、Gateway APIのリソースモデルの話でした。それが第10回でインターフェースの設計に直接使えます。過去回の決定が対応表に落ちるという構造の、分かりやすい例です。

インターフェースを実行可能にする#

対応表ができたら、次はそれを維持する仕組みです。

仕様書は読まれない#

インターフェース仕様を文書として書き、リポジトリのREADMEに置く。これは必要な作業ですが、これだけでは足りません。

文書は、読まなくても作業が進む場合には読まれません。valuesは既存のファイルをコピーして書き換えるのが普通なので、仕様書を開く理由がありません。そして書き間違いは、適用時まで、悪ければ本番まで届きます。

Helmには、これを機械的に検証する仕組みがあります。values.schema.json です。JSON Schemaで構造を宣言でき、検証は helm install、helm upgrade、helm lint、helm template の各操作で行われます。

前章で決めた3つの制約が、そのままスキーマになります。列挙は候補値の指定、範囲は最小値と最大値、必須は必須項目の宣言です。対応表を作る作業と、スキーマを書く作業は、ほぼ同じ内容になります。

そして注意点があります。

検証を回避するオプションが存在します。エアギャップ環境向けに --skip-schema-validation が用意されています。つまり、スキーマを書いただけでは強制になりません。

したがって設計に含めることが1つあります。CIでこのオプションが使われていないことを確認してください。第5回でポリシーの例外に期限を付け、第9回で「緊急の抜け道が恒久化する」と書いたのと同じ構造です。回避経路がある仕組みは、回避されていないことを確認するまで機能していません。

Chartのバージョニングと、古いバージョンの寿命#

第2回で「Chartの破壊的変更は30日前に告知する」と決めました。この約束を守るには、仕組みが必要です。

Chartには2つのバージョン欄があります。

SemVerに従うということは、破壊的変更をメジャーバージョンの上げに対応させられるということです。これを規約にしてください。パラメータを引っ込める、既定値の意味を変える、必須項目を増やす——これらはメジャーを上げます。

そして30日前告知の実効性は、ここで決まります。告知しても移行しないチームは出ます。そのとき古いメジャーバージョンを使い続けられるなら、移行の遅れはそのチームの問題に留まります。使い続けられないなら、告知は「30日後に壊します」という予告に過ぎません。

設計書に書くことは2つです。破壊的変更とメジャーバージョンの対応規約、そして古いメジャーをいつまでサポートするか。

サポート期間の決め方は、第6回でADRの見直しについて書いたのと同じ形にします。日付と条件の併用です。「メジャーを上げてから90日」という日付に加えて、「そのバージョンを使っているチームがゼロになったら」という条件を置きます。日付だけだと、まだ使われているのに切ることになります。

共通部分をどこに置くか#

Chartが増えると、共通のテンプレートを再利用したくなります。

Helmには type: library のチャートがあり、これは「インストールできず、通常はリソースオブジェクトを含まない」再利用のためのものです。Kustomizeを使う場合は、base と overlay の構成に加えて components による合成ができます。

どちらの仕組みを使うかは第6回の管轄です。本記事で決めるのは、ツールに依存しない2点です。

1. 共通部分をどこに置くか
2. それを変更できるのは誰か

2番目を軽く見ないでください。共通部分は、全チームに影響します。1つのChartのバグは1チームの問題ですが、共通ライブラリのバグは全チームの問題です。変更権限は、第2回のRACIで運用チームがAを持つ範囲に含めてください。

そして共通部分の変更も、破壊的変更の告知の対象です。影響範囲が広いぶん、告知の重要性は個別のChartより高くなります。

リポジトリ構成 ― 第8回の保留を解く#

第8回で1つ判断を保留しました。「インフラコードとマニフェストを同じリポジトリに置くか」です。片方の要件だけで決めると誤るため、両方の要件が揃う本記事まで持ち越しました。

第8回で決めた基準#

第8回では、こう決めました。リポジトリの単位は、レビューする人の単位に合わせる。

別々の人がレビューすべきコードを1つのリポジトリに置くと、レビュー要求の設定が複雑になり、結局「誰でもマージできる」状態に落ち着きます。逆に、同じ人が常に一緒にレビューするコードを分けると、関連する変更が2つのプルリクエストに割れ、片方だけマージされる事故が起きます。

この基準は有効ですが、マニフェスト側には追加の入力があります。

マニフェスト側に固有の2つの入力#

1つ目、変更の頻度が違います。

マニフェストは、インフラコードよりはるかに頻繁に変わります。第9回で決めたとおり、デプロイのたびにイメージのダイジェストが更新されるためです。一方、VPCやクラスタの構成は滅多に変わりません。第8回で「VPCとノードプールを同じモジュールに入れると、めったに変えたくないものを頻繁に触ることになる」と書いたのと同じ問題が、リポジトリの単位でも起きます。

頻度の違うものを同じリポジトリに置くと、履歴が一方に埋もれます。インフラの変更履歴を追いたいのに、ダイジェスト更新のコミットが大量に挟まる状態です。

2つ目、適用の主体が違います。

インフラコードはパイプラインが apply し（第8回）、マニフェストはGitOpsのコントローラが同期します（第9回）。同期対象のリポジトリに、同期対象でないものを混ぜると、コントローラの監視範囲の設計が複雑になります。そしてこのコントローラは、第9回で確認したとおり実質的にどの人間よりも強い権限を持ちます。その監視範囲を単純に保つことには、セキュリティ上の意味があります。

2つとも「分ける」に倒れます。ただし小規模な組織では、1つのリポジトリにディレクトリで分けるほうが管理が単純です。第2回で想定した開発チーム数（4〜15）が判断の目安になります。数が少ないうちは同居、増えたら分離、という段階的な判断も成立します。

マニフェスト側のディレクトリ構成#

環境ごとの分離方式を決めます。ここでも第3回の決定が効きます。

第3回で ProdとStgは同構成、Devは別構成と決めました。第8回で、この非対称性をディレクトリ分割とパラメータ差の使い分けで表現しました。マニフェスト側でも同じ判断をします。ProdとStgの差はパラメータで、Devとの差はディレクトリで表現する形です。

そして、第8回のIaC側と方式を揃えるかどうかを決めてください。揃える利点は認知コストの低減です。2つのリポジトリで環境の表現方法が違うと、読む人が毎回切り替えることになります。揃えない理由があるなら、それを設計書に書きます。

Kustomizeを使う場合、1つ知っておくべき挙動があります。configMapGenerator と secretGenerator は、生成したリソースに自動でハッシュのサフィックスを付けます。

これは意図された挙動です。設定が変わればリソース名が変わり、参照しているPodが再作成されます。設定変更が確実に反映されるための仕組みです。ただし知らないと「設定を書き換えただけなのにPodが再起動した」と見えます。設計書に、この挙動を前提にしていることを明記してください。

サービスごとに分けるか、1つにまとめるか#

環境の軸を決めたら、もう1つの軸が残ります。サービスの軸です。マニフェストリポジトリを、サービスごとに分けるか、1つにまとめるか。

ここでも第8回の基準が使えます。レビューする人の単位に合わせる。そして第2回のRACIを見れば、その単位は決まっています。開発チームがAを持つ単位です。

ただし、マニフェスト側に固有の判断材料が2つあります。

1つ目、GitOpsのコントローラの設定の複雑さです。リポジトリを分けるほど、コントローラに登録する対象が増えます。数十のリポジトリを個別に登録する構成は、登録漏れが起きたときに気づきにくくなります。「デプロイしたのに反映されない」という報告の原因が、登録漏れであるケースです。

2つ目、権限の分離のしやすさです。1つのリポジトリにまとめると、あるチームが他チームのマニフェストを変更できる状態になります。ディレクトリ単位でレビュー要求を設定できますが、設定の複雑さは第8回で指摘したとおりで、複雑な設定は形式化します。

2つは逆方向に働きます。まとめるほどコントローラの設定は単純になり、権限の分離は難しくなります。どちらを重く見るかは、第2回で決めた運開分離の要求の強さで決まります。

第2回で運開分離をPCI DSSの要求として扱った組織なら、権限の分離を優先します。要求がない組織なら、コントローラの設定の単純さを優先してかまいません。ここでも新しい判断はしていません。第2回の結論の適用です。

IDPは要否から判定する#

最後にIDP（Internal Developer Platform）です。第6回で確立した原則をここでも適用します。要否を先に判定します。

第2回のSLAが守れているか#

第2回で運用チームのSLAを定めました。Namespaceの払い出しは2営業日、一次応答は4時間です。

IDPが解決するのは、「運用チームに依頼して待つ」という時間です。開発者が自分で払い出せるようになれば、待ち時間はなくなります。

したがって判断基準はこうなります。そのSLAが守れていて、開発者が待ち時間に不満を持っていないなら、IDPを入れる理由は薄くなります。解決すべき課題が存在しないためです。

逆に、次のような状態ならIDPの検討に入ります。払い出しのSLAが守れていない。依頼が特定の担当者に集中している。同種の依頼が月に何十件も来ている。

第6回の成熟度の話も適用してください。Backstage は CNCF Incubating であり、Graduated ではありません。第6回で「本番の基盤にSandboxのプロジェクトを採用するなら、その理由をADRに明記する」と書きました。Incubatingについても、同じ確認をする価値があります。「少数の利用者が本番で使うことに成功しており、健全な貢献者層を持つ」という段階です。

入れる場合、何を載せるか#

IDPの設計は、抽象的な議論になりがちです。次の問いに還元してください。

運用チームがいま対応している依頼のうち、どれを自動化するか。

依頼の種類を数え、頻度の高いものから載せます。頻度が測れないなら、まず数えることから始めます。「開発者体験の向上」という目的で設計を始めると、何を作れば終わりなのかが定まりません。

典型的な候補は3つです。

• Namespaceの払い出し。第2回でSLAを定めた対象そのもの
• 新規サービスの雛形作成。本記事の前半で設計したvaluesの初期値を含む
• デプロイ状況の参照。第9回で「Argo CDのUIが要るか」を判断軸に挙げたのと同じ論点

3番目について補足します。第9回で、GitOpsツールの選定において「UIが要るなら、そのUIを誰が使うのかを第2回のRACIで確認する」と書きました。開発者が使うなら、それはIDPの機能として提供する選択肢もあります。2つのツールで同じ情報を見せる構成になっていないかを確認してください。

サービスカタログの単位#

カタログに載せる単位は、第2回のRACIで「開発チームがAを持つ」単位に合わせてください。

カタログの単位と責任の単位がずれると、「このサービスは誰のものか」が曖昧になります。そしてカタログは、障害時に最初に見られる場所になりがちです。そこに書かれた所有者が実際の責任者と違うと、第16回で設計するエスカレーションが機能しません。

第4回で決めた必須ラベル（チーム、サービス）とも揃えてください。カタログの単位、ラベルの単位、責任の単位。この3つが一致していると、費用の按分と障害時の連絡先とカタログが同じ軸で並びます。ずれていると、3つの対応表を人間が突き合わせることになります。

入れないと決めた場合に書くこと#

導入しないという判断も、記録します。第6回で決めたとおり、ADRを空欄にしないでください。

再検討のトリガーは、日付ではなく条件で書きます。

• 払い出しのSLAが守れなくなったとき
• 開発チーム数が一定を超えたとき（第2回で想定した範囲の上限を根拠にする）
• 同種の依頼が月に一定件数を超えたとき

3つとも測定可能です。「開発者から要望が強くなったら」のような条件にしないでください。測れない条件は、次の見直しで誰も判定できません。第6回で見直しトリガーを条件で書くと決めたときの理由が、そのままここに当てはまります。

【実務テンプレート】マニフェスト抽象化・IDP設計書#

第2回から第9回の成果物が入力になります。

次回予告#

開発者に何を書かせるかが決まりました。次に決めるのは、その値をどう算出するかです。

次回の第11回「Podリソース・耐障害性設計書」では、Requests/Limitsの算出方法論、HPAのトリガーメトリクスと閾値、Liveness・Readiness・Startup Probeの設計、Graceful Shutdownの実装、PodDisruptionBudget、そして topologySpreadConstraints によるマルチゾーン分散を扱います。

本記事で「開発チームが決める」と分類したパラメータの、値の決め方が第11回です。そして第1回の条件2で確定した15秒の猶予、第4回のSpot採否の判定が、第11回のGraceful Shutdown設計に直結します。10回分の設計が、ようやく1つのPodスペックに収束します。