API概要

• 1: Kubernetes非推奨ポリシー

1 - Kubernetes非推奨ポリシー

このドキュメントではシステムのさまざまな側面に関する非推奨ポリシーについて詳しく説明します。

Kubernetesは多くのコンポーネントと多くのコントリビュータを持つ大規模なシステムです。 このようなソフトウェアでは、機能セットは時間の経過とともに自然に進化し、時には機能を削除する必要がある場合があります。 これにはAPI、フラグ、または機能全体が含まれることもあります。 既存のユーザーへの影響を避けるため、Kubernetesは削除される予定のシステムの側面については非推奨ポリシーに従っています。

API

KubernetesはAPI駆動型のシステムであるため、問題領域の理解の進化を反映して時間の経過とともに進化してきました。 Kubernetes APIは実際は「APIグループ」と呼ばれる一連のAPIであり、各APIグループは個別にバージョン管理されています。 APIバージョンは主に3つのトラックに分類され、それぞれに異なる非推奨ポリシーがあります:

Kubernetesの特定のリリースでは任意の数のAPIグループと任意の数のそれぞれのバージョンをサポートすることができます。

次のルールはAPIの要素の非推奨を管理します。これには以下が含まれます:

• RESTリソース (別名 APIオブジェクト)
• RESTリソースのフィールド
• RESTリソースのアノテーション、"beta"アノテーションは含まれますが"alpha"アノテーションは含まれません
• 列挙された値や定数値
• コンポーネントの設定構造

これらのルールは、masterまたはリリースブランチへの任意のコミット間ではなく、公式リリース間に適用されます。

ルール #1: APIの要素はAPIグループのバージョンをインクリメントすることでもに削除することができます。

APIの要素が特定バージョンのAPIグループに追加されると、 トラックに関係なくそのバージョンから削除されたり、 大幅に挙動が変更されることはありません。

ルール #2: APIオブジェクトはいくつかのバージョンに存在しないRESTリソース全体を除き、 任意のリリース内のAPIバージョン間で情報を失うことなくラウンドトリップできる必要があります

例えば、あるオブジェクトがv1として書き込まれその後v2として読み取られv1に変換された場合、 結果として得られるv1リソースは元のリソースと同一である必要があります。 v2における表現はv1とは異なるかもしれませんが、システムは両方向にそれらを変換する方法を知っています。 さらに、v2で追加された新しいフィールドはv1にラウンドトリップできる必要があります。 つまりv1では同等のフィールドを追加するかアノテーションとして表現する必要があるかもしれません。

ルール #3: 特定のトラックのAPIバージョンは安定性の低いAPIバージョンを優先して非推奨になることはありません。

• GA APIバージョンは、betaおよびalpha APIバージョンに置き換えることができます。
• Beta APIバージョンは以前のbetaおよびalpha APIバージョンに置き換えることはできますが、GA APIバージョンに置き換えることはできません。
• Alpha APIバージョンは以前のalpha APIバージョンに置き換えることはできますが、GAまたはbeta APIバージョンに置き換えることはできません。

ルール #4a: APIの有効期間はAPIの安定性レベルによって決まります

• GA APIバージョンは非推奨としてマークされることがありますが、Kubernetesのメジャーバージョン内で削除されることはありません。
• Beta APIバージョンは導入後9ヶ月または3つのマイナーリリース(いずれか長い方)以内に非推奨にされ、 非推奨後9ヶ月または3つのマイナーリリース(いずれか長い方)以内に提供されなくなります。
• Alpha APIバージョンは事前の非推奨通知なしにリリースから削除される場合があります。

これによりbeta APIバージョンのサポートは 最大2つのリリースのバージョンの差異をカバーし、 APIが不安定なbetaバージョンで停滞し、beta APIのサポートが終了したときに本番稼働が中断されることはありません。

ルール #4b: 特定のグループの「優先」APIバージョンと「ストレージバージョン」は、 新しいバージョンと以前のバージョンの両方をサポートするリリースが行われるまで更新されない場合があります。

ユーザーはKubernetesの新しいリリースにアップグレードした後、 (新しいバージョンでのみ利用可能な機能を明示的に使用していない限り) 何も新しいAPIバージョンに変換することなく、また破損が発生することなく、 以前のリリースにロールバックできる必要があります。 これはオブジェクトの保存された表現において特に顕著です。

これらはすべて例を挙げて説明するのが最も適切です。新しいAPIグループを導入する Kubernetesリリース、バージョンXを想像してください。 新しいKubernetesリリースは約4ヶ月ごと(1年に3回)に行われます。 以下の表は一連の後続リリースでサポートされるAPIバージョンを示しています。

REST resources (別名APIオブジェクト)

上記のタイムラインではAPI v1に存在し、非推奨化される必要があるWidgetという仮想のRESTリソースを考えてみましょう。 私たちはリリースX+1と同期して非推奨をドキュメント化とアナウンスを行います。 WidgetリソースはAPIバージョンv1(非推奨)にはまだ存在しますがv2alpha1には存在しません。 WidgetリソースはX+8までのリリースに引き続き存在して機能します。 API v1が期限切れになるX+9でのみ、Widgetリソースは存在しなくなり、その動作が削除されます。

Kubernetes v1.19以降は、非推奨のREST APIエンドポイントへのAPIリクエストを行うと、以下のようになります:

1. APIレスポンスにおいてWarningヘッダー(RFC7234, Section 5.5で定義)を返します。

2. リクエストに対して記録された監査イベントに"k8s.io/deprecated":"true"というアノテーションを追加します。

3. kube-apiserverプロセスでapiserver_requested_deprecated_apisゲージメトリクスに1を設定します。 このメトリクスにはapiserver_request_totalメトリクスに結合することができる group、version、resource、subresourceラベルと、APIが提供されなくなるKubernetesリリースを表すremoved_releaseがあります。 次のPrometheusクエリはv1.22で削除される非推奨APIへのリクエストに関する情報を返します:

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

RESTリソースのフィールド

すべてのRESTリソースと同様に、API v1に存在していた個々のフィールドはAPI v1が削除されるまで存在して機能する必要があります。 リソース全体と異なり、v2 APIはフィールドをラウンドトリップできる限り、異なる表現を選択することができます。 例えば非推奨になった「magnitude」という名前のv1フィールドは、API v2では「deprecatedMagnitude」という名前になる可能性があります。 最終的にv1が削除されると、v2から非推奨のフィールドも削除することができます。

列挙された値や定数値

すべてのRESTリソースとそのフィールドと同様にAPI v1でサポートされていた定数値はAPI v0が削除されるまで存在して機能する必要があります。

コンポーネント設定の構造

コンポーネント設定はRESTリソースと同様にバージョン付けされて管理されています。

今後の取り組み

時間の経過とともに、Kubernetesはよりきめ細かいAPIバージョンを導入し、これらのルールは必要に応じて調整されます。

フラグまたはCLIの非推奨化

Kubernetesシステムは複数の異なるプログラムが連携して構成されています。 KubernetesリリースではこれらのプログラムのフラグやCLIコマンド(総称して「CLI要素」)が削除されることがしばしばあります。 個々のプログラムは、非推奨ポリシーが若干異なる、ユーザー向けプログラムと管理者向けプログラムの2つの主要グループに分類されます。 フラグに明示的に接頭辞が付けられていないか、「alpha」または「beta」としてドキュメント化されない限り、そのフラグはGAとみなされます。

CLI要素は事実上システムに対するAPIの一部ですが、REST APIと同じ方法ではバージョン管理されておらず、非推奨のルールは次のようになっています:

ルール #5a: ユーザー向けのコンポーネントのCLI要素(例: kubectl)は 非推奨がアナウンスされてから以下の期間は機能しなければなりません:

• GA: 12ヶ月または2リリース(いずれか長い方)
• Beta: 3ヶ月または1リリース(いずれか長い方)
• Alpha: 0リリース

ルール #5b: 管理者向けのコンポーネントのCLI要素(例: kubelet)は 非推奨がアナウンスされてから以下の期間は機能しなければなりません:

• GA: 6ヶ月または1リリース(いずれか長い方)
• Beta: 3ヶ月または1リリース(いずれか長い方)
• Alpha: 0リリース

ルール #5c: コマンドラインインターフェース(CLI)の要素は より不安定なCLI要素の代わりに廃止されることはありません

APIに関するルール#3と同様、コマンドラインインターフェースの要素が代替実装にリプレイスされる、 例えば既存の要素名の変更やコマンドライン引数の代わりにファイルから取得した設定を使用するように切り替える場合、 推奨される代替案は同じかそれ以上の安定性レベルでなければなりません。

ルール #6: 非推奨のCLI要素は使用時に警告を表示しなければなりません(オプションで無効化可能)

機能や動作の非推奨化

時には、KubernetesリリースではAPIやCLIによって制御されないシステムの機能や動作を非推奨にする必要があります。 その場合、非推奨に関するルールは以下の通りです:

ルール #7: 非推奨となる動作はアナウンスされてから最低1年間は機能しなければなりません。

機能や動作が、変更を取り込む作業が必要な代替実装に置き換えられる場合、 可能な限り移行を簡素化する努力が必要です。 代替実装がKubernetes organizationの管理下にある場合、以下のルールが適用されます:

ルール #8: 安定性の低い代替実装を優先して、動作の機能を非推奨にしてはなりません

例えば、一般提供されている機能がBeta版にリプレイスために非推奨にされることはありません。 ただし、Kubernetesプロジェクトは同じ成熟度に達する前であっても、ユーザーが代替実装を採用して移行することを推奨しています。 これは、機能の新しいユースケースを検討したり、リプレイスについての早期フィードバックを得るために特に重要です。

代替実装は、外部のツールや製品である場合があります。 例えば、機能がkubeletからKubernetesプロジェクト管理外のコンテナランタイムに移行することがあります。 このような場合、ルールを適用することはできませんが、コンポーネントの成熟度を損なわない移行方法を確保するための努力が必要です。 コンテナランタイムを例に挙げると、一般的なコンテナランタイムが、リプレイスする動作を実装しながら同等の安定性を提供するバージョンを持つように取り組む必要があるかもしれません。

機能と動作の非推奨ルールは、システムに対するすべての変更がこのポリシーによって管理されることを意味するものではありません。 これらのルールはKubernetes上で実行されているアプリケーションの正確性やKubernetesクラスターの管理に影響する、また完全に削除されるものにのみ適用されます。

上記のルールの例外は フィーチャーゲート です。 フィーチャーゲートはユーザーが実験的な機能を有効/無効にできるようにするキー=バリューのペアです。

フィーチャーゲートは機能の開発ライフサイクルをカバーすることを目的としており、 長期的なAPIを目的としたものではありません。 そのため、機能がGAになるが削除された後は、非推奨となり削除されることが期待されます。

機能が段階を踏むにつれて、関連するフィーチャーゲートも進化します。 機能のライフサイクルと対応するフィーチャーゲートの関係は以下の通りです:

• Alpha: フィーチャーゲートはデフォルトで無効化されており、ユーザーによって有効化できます。
• Beta: フィーチャーゲートはデフォルトで有効化されており、ユーザーによって無効化できます。
• GA: フィーチャーゲートは非推奨となり("非推奨"を参照)動作しなくなります。
• GA、非推奨期間終了後: フィーチャーゲートは削除され、呼び出しは受け付けられなくなります。

非推奨

機能はGA前のライフサイクルのどの時点でも削除できます。 GA前に機能が削除されると、それに関連するフィーチャーゲートも非推奨になります。

動作しないフィーチャーゲートを無効化するために呼び出そうとすると、 サイレントに実行される可能性あるサポートされていないシナリオを避けるため呼び出しは失敗します。

場合によっては、GA前の機能を削除にかなりの時間がかかることがあります。 フィーチャーゲートは、関連する機能が完全に削除されるまで機能し続け、 その時点でフィーチャーゲート自体が非推奨になる可能性があります。

GAされた機能のフィーチャーゲートの削除にも時間がかかる場合、 フィーチャーゲートが機能に影響を与えず、エラーも引き起こさない場合、 フィーチャーゲートへの呼び出しは動作し続けることがあります。

ユーザーによって無効化されることを意図した機能には、関連するフィーチャーゲートで その機能を無効化するためにメカニズムが含まれている必要があります。

フィーチャーゲートのバージョニングは、前述のコンポーネントとは異なるため、 非推奨に関するルールは次のとおりです:

ルール #9: フィーチャーゲートは、対応する機能が次のようにライフサイクルステージを移行する際に非推奨にする必要があります。 フィーチャーゲートは以下の期間は機能しなければなりません:

• Beta機能からGA: 6ヶ月または2リリース(どちらか長い方)
• Beta機能からEOL: 3ヶ月または1リリース(どちらか長い方)
• Alpha機能からEOL: 0リリース

ルール #10: 非推奨となったフィーチャーゲートは使用時に警告を返す必要があります。 フィーチャーゲートが非推奨になる場合には、リリースノートと対応するCLIヘルプの両方にドキュメント化される必要があります。 警告とドキュメントの両方には、フィーチャーゲートが動作しないかどうかを明記する必要があります。

メトリクスの非推奨化

Kubernetesコントロールプレーンの各コンポーネントはメトリクス(通常は/metricsエンドポイント)を公開しており、 通常はクラスター管理者によって収集されます。 すべてのメトリクスが同じというわけではありません。一部のメトリクスは一般的にSLIとして使用されたり、 SLOを決定するために使用されるため、より重要な役割を持つ傾向があります。 他のメトリクスは、事実上実験的なものであるか、主にKubernetesの開発プロセスで使用されます。

そのため、メトリクスは3つの安定性クラス(ALPHA、BETA、STABLE)に分類され、 Kubernetesリリース間のメトリクスの削除に影響します。 これらのクラスは、メトリクスの重要性に基づいて決定されます。 メトリクスの非推奨と削除に関するルールは次のとおりです:

ルール #11a: メトリクスは、対応する安定性クラスに応じて、以下の期間は機能しなければなりません:

• STABLE: 4リリースまたは12ヶ月(いずれか長い方)
• BETA: 2リリースまたは8ヶ月(いずれか長い方)
• ALPHA: 0リリース

ルール #11b: メトリクスは、非推奨がアナウンスされた後も、以下の期間は機能しなければなりません:

• STABLE: 3リリースまたは9ヶ月(いずれか長い方)
• BETA: 1リリースまたは4ヶ月(いずれか長い方)
• ALPHA: 0リリース

非推奨となったメトリクスの説明テキストには、先頭に非推奨を通知する文字列「(Deprecated from x.y)」が付けられ、 メトリクスの登録時に警告ログが出力されます。 非推奨でない安定版のメトリクスと同様に、非推奨となったメトリクスも自動的にメトリクスエンドポイントに登録されるため、表示されます。

後続のリリース(メトリクスのdeprecatedVersionが current_kubernetes_version - 3 に等しい場合)で、 非推奨となったメトリクスは 非表示 になります。 非推奨となったメトリクス とは異なり 、非表示のメトリクスは自動的にメトリクスエンドポイントに登録されなくなります(それゆえに非表示になります)。 ただし、バイナリのコマンドラインフラグ(--show-hidden-metrics-for-version=)を使用して明示的に有効化することができます。 これによりクラスター管理者は、以前の非推奨の警告に対応できなかった場合でも、 非推奨となったメトリクスから適切に移行するための回避策を取ることができます。 非表示のメトリクスは、1リリース後に削除される必要があります。

例外

想定し得るすべての状況を網羅するポリシーはありません。 このポリシーは生きたドキュメントであり、時間の経過とともに改善されます。 実際には、このポリシーにうまく適合しない状況や、このポリシーが重大な障害となる状況が発生する可能性があります。 そのような状況では、特定のケースに対して最適な解決策を見つけるためにSIGやプロジェクトリーダーと協議するべきであり、 Kubernetesが可能な限りユーザーに影響を与えない安定したシステムであることを常に念頭に置いておくべきです。 例外は、関連するすべてのリリースノートで常にアナウンスされます。