API概要

このセクションでは、Kubernetes APIのリファレンス情報を提供します。

REST APIはKubernetesの基本的な構造です。すべての操作とコンポーネント間の通信、および外部ユーザーのコマンドは、REST API呼び出しでありAPIサーバーが処理します。

その結果、Kubernetesプラットフォーム内のすべてのものは、APIオブジェクトとして扱われ、APIに対応するエントリーがあります。

Kubernetes APIリファレンスは、Kubernetesバージョンv1.30のAPI一覧を提供します。

一般的な背景情報を知るには、The Kubernetes API、 Controlling Access to the Kubernetes APIを読んでください。それらはKubernetes APIサーバーがクライアントを認証する方法とリクエストを認可する方法を説明します。

APIバージョニング

JSONとProtobufなどのシリアル化スキーマの変更については同じガイドラインに従います。以下の説明は、両方のフォーマットをカバーしています。

APIのバージョニングとソフトウェアのバージョニングは間接的に関係しています。 API and release versioning proposalは、APIバージョニングとソフトウェアバージョニングの関係を説明しています。

APIのバージョンが異なると、安定性やサポートのレベルも異なります。各レベルの基準については、API Changes documentationで詳しく説明しています。

各レベルの概要は以下の通りです:

Alpha:
- バージョン名にalphaが含まれています(例：v1alpha1)。
- 組み込みのalpha APIバージョンはデフォルトで無効化されており、使用するためにはkube-apiserverの設定で明示的に有効にする必要があります。
- バグが含まれている可能性があります。機能を有効にするとバグが露呈する可能性があります。
- alpha APIのサポートは、予告なしにいつでも中止される可能性があります。
- 後にリリースされるソフトウェアで、互換性のない方法で予告なく変更される可能性があります。
- バグのリスクが高く、長期的なサポートが得られないため、短期間のテストクラスターのみでの使用を推奨します。
Beta:
- バージョン名には beta が含まれています(例：v2beta3)。
- 組み込みのbeta APIバージョンはデフォルトで無効化されており、使用するためにはkube-apiserverの設定で明示的に有効にする必要があります。 (例外としてKubernetes 1.22以前に導入されたAPIのbetaバージョンはデフォルトで有効化されています)
- 組み込みのbeta APIバージョンは、導入から非推奨となるまでが9ヶ月または3マイナーリリース(どちらかの長い期間)、そして非推奨から削除まで9ヶ月または3マイナーリリース(どちらかの長い期間)の最大存続期間を持ちます。
- ソフトウェアは十分にテストされています。機能を有効にすることは安全であると考えられています。
- 機能のサポートが打ち切られることはありませんが、詳細は変更される可能性があります。
- オブジェクトのスキーマやセマンティクスは、その後のベータ版や安定版のAPIバージョンで互換性のない方法で変更される可能性があります。このような場合には、移行手順が提供されます。後続のbetaまたはstable APIバージョンに適応することはAPIオブジェクトの編集や再作成が必要になる場合があり、単純ではないかもしれません。移行に伴い、その機能に依存しているアプリケーションのダウンタイムが必要になる場合があります。
- 本番環境での使用は推奨しません。後続のリリースは、互換性のない変更を導入する可能性があります。 beta APIを使用する場合、そのbeta APIが非推奨となり提供されなくなった際には、後続のbetaまたはstable APIバージョンに移行する必要があります。
備考:
ベータ版の機能をお試しいただき、ご意見をお寄せください。ベータ版の機能が終了した後はこれ以上の変更ができない場合があります。
Stable:
- バージョン名は vX であり、X は整数である。
- stable APIバージョンはKubernetesのメジャーバージョン内の全てのリリースで利用可能であり、stable APIを削除するようなKubernetesのメジャーバージョンの修正は、現在計画されていません。

APIグループ

API groupsで、KubernetesのAPIを簡単に拡張することができます。 APIグループは、RESTパスとシリアル化されたオブジェクトのapiVersionフィールドで指定されます。

KubernetesにはいくつかのAPIグループがあります:

core(legacyとも呼ばれる)グループは、RESTパス /api/v1 にあります。コアグループは apiVersion フィールドの一部としては指定されません。例えば、apiVersion: v1 のように。
名前付きのグループは、RESTパス /apis/$GROUP_NAME/$VERSION にあり、以下のように使用します。 apiVersion: $GROUP_NAME/$VERSIONを使用します(例：apiVersion: batch/v1)。サポートされているAPIグループの完全なリストは以下にあります。 Kubernetes API reference。

APIグループの有効化と無効化

一部のリソースやAPIグループはデフォルトで有効になっています。 APIサーバー上で--runtime-configを設定することで、有効にしたり無効にしたりすることができます。またruntime-configフラグには、APIサーバーのランタイム構成を記述したコンマ区切りの<key>[=<value>]ペアを指定します。もし=<value>の部分が省略された場合には、=trueが指定されたものとして扱われます。

例えば:

batch/v1を無効するには、--runtime-config=batch/v1=falseを設定する
batch/v2alpha1を有効するには、--runtime-config=batch/v2alpha1を設定する

備考:

グループやリソースを有効または無効にした場合、 APIサーバーとコントローラーマネージャーを再起動して、--runtime-configの変更を反映させる必要があります。

永続化

Kubernetesはシリアライズされた状態を、APIリソースとしてetcdに書き込んで保存します。

次の項目

API conventionsをもっと知る
aggregatorの設計ドキュメントを読む

最終更新 June 18, 2023 at 4:58 PM PST: Replace design-proposals links (cdd95be3e7)