API概要
このセクションでは、Kubernetes APIのリファレンス情報を提供します。
REST APIはKubernetesの基本的な構造です。 すべての操作とコンポーネント間のと通信、および外部ユーザーのコマンドは、REST API呼び出しでありAPIサーバーが処理します。
その結果、Kubernetesプラットフォーム内のすべてのものは、APIオブジェクトとして扱われ、APIに対応するエントリーがあります。
Kubernetes APIリファレンスは、Kubernetesバージョンv1.24の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」）。
- バグが含まれている可能性があります。 機能を有効にするとバグが露呈する可能性があります。 機能がデフォルトで無効になっている可能性があります。
- ある機能のサポートは、予告なしにいつでも中止される可能性があります。
- 後にリリースされるソフトウェアで、互換性のない方法で予告なく変更される可能性があります。
- バグのリスクが高く、長期的なサポートが得られないため、短期間のテストクラスターのみでの使用を推奨します。
-
Beta:
-
バージョン名には
betaが含まれています(例：v2beta3)。 -
ソフトウェアは十分にテストされています。 機能を有効にすることは安全であると考えられています。 機能はデフォルトで有効になっています。
-
機能のサポートが打ち切られることはありませんが、詳細は変更される可能性があります。
-
オブジェクトのスキーマやセマンティクスは、その後のベータ版や安定版のリリースで互換性のない方法で変更される可能性があります。 このような場合には、移行手順が提供されます。 スキーマの変更に伴い、APIオブジェクトの削除、編集、再作成が必要になる場合があります。 編集作業は単純ではないかもしれません。 移行に伴い、その機能に依存しているアプリケーションのダウンタイムが必要になる場合があります。
-
本番環境での使用は推奨しません。 後続のリリース は、互換性のない変更を導入する可能性があります。 独立してアップグレード可能な複数のクラスターがある場合、この制限を緩和できる可能性があります。
備考: ベータ版の機能をお試しいただき、ご意見をお寄せください。 ベータ版の機能が終了した後はこれ以上の変更ができない場合があります。 -
-
Stable:
- バージョン名は
vXであり、Xは整数である。 - 安定版の機能は、リリースされたソフトウェアの中で、その後の多くのバージョンに登場します。
- バージョン名は
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を設定する
--runtime-configの変更を反映させる必要があります。
永続化
Kubernetesはシリアライズされた状態を、APIリソースとしてetcdに書き込んで保存します。
次の項目
- API conventionsをもっと知る
- aggregatorの設計ドキュメントを読む