Kubernetes API

Kubernetesの中核である control planeはAPI server です。 APIサーバーは、エンドユーザー、クラスターのさまざまな部分、および外部コンポーネントが相互に通信できるようにするHTTP APIを公開します。

Kubernetes APIを使用すると、Kubernetes API内のオブジェクトの状態をクエリで操作できます（例：Pod、Namespace、ConfigMap、Events）。

APIエンドポイント、リソースタイプ、サンプルについてはAPIリファレンスで説明しています。

APIの変更

成功を収めているシステムはすべて、新しいユースケースの出現や既存の変化に応じて成長し、変化する必要があります。 したがって、Kubernetesには、Kubernetes APIを継続的に変更および拡張できる設計機能があります。 Kubernetesプロジェクトは、既存のクライアントとの互換性を破壊しないこと、およびその互換性を一定期間維持して、他のプロジェクトが適応する機会を提供することを目的としています。

基本的に、新しいAPIリソースと新しいリソースフィールドは追加することができます。 リソースまたはフィールドを削除するには、API非推奨ポリシーに従ってください。

互換性のある変更の構成要素とAPIの変更方法については、APIの変更で詳しく説明しています。

OpenAPI 仕様

完全なAPIの詳細は、OpenAPIを使用して文書化されています。

Kubernetes APIサーバーは、/openapi/v2エンドポイントを介してOpenAPI仕様を提供します。 次のように要求ヘッダーを使用して、応答フォーマットを要求できます。

Kubernetesは、他の手段として主にクラスター間の連携用途向けのAPIに、Protocol buffersをベースにしたシリアライズフォーマットを実装しており、そのフォーマットの概要はデザイン提案に記載されています。また各スキーマのIDFファイルは、APIオブジェクトを定義しているGoパッケージ内に配置されています。

APIバージョニング

フィールドの削除やリソース表現の再構成を簡単に行えるようにするため、Kubernetesは複数のAPIバージョンをサポートしており、/api/v1や/apis/rbac.authorization.k8s.io/v1alpha1のように、それぞれ異なるAPIのパスが割り当てられています。

APIが、システムリソースと動作について明確かつ一貫したビューを提供し、サポート終了、実験的なAPIへのアクセス制御を有効にするために、リソースまたはフィールドレベルではなく、APIレベルでバージョンが行われます。

JSONとProtocol Buffersのシリアライズスキーマも、スキーマ変更に関して同じガイドラインに従います。ここから以下の説明は、双方のフォーマットをカバーしています。

APIとソフトウエアのバージョニングは、間接的にしか関連していないことに注意してください。APIとリリースバージョニング提案で、APIとソフトウェアのバージョニングの関連について記載しています。

異なるバージョンのAPIでは、安定性やサポートのレベルも変わります。各レベルの詳細な条件は、APIの変更に記載されています。下記に簡潔にまとめます:

• アルファレベル(版):
  • バージョン名にalphaを含みます(例、v1alpha1)。
  • バグが多いかもしれません。アルファ機能の有効化がバグを顕在化させるかもしれません。デフォルトでは無効となっています。
  • アルファ機能のサポートは、いつでも通知無しに取りやめられる可能性があります。
  • ソフトウェアリリース後、APIが通知無しに互換性が無い形で変更される可能性があります。
  • バグが増えるリスク、また長期サポートが無いことから、短期間のテスト用クラスターでの利用を推奨します。
• ベータレベル(版):
  • バージョン名にbetaを含みます(例、v2beta3)。
  • コードは十分にテストされています。ベータ機能の有効化は安全だと考えられます。デフォルトで有効化されています。
  • 全体的な機能のサポートは取りやめられませんが、詳細は変更される可能性があります。
  • オブジェクトのスキーマ、意味はその後のベータ、安定版リリースで互換性が無い形で変更される可能性があります。その場合、次のバージョンへアップデートするための手順を提供します。その手順ではAPIオブジェクトの削除、修正、再作成が必要になるかもしれません。修正のプロセスは多少の検討が必要になるかもしれません。これは、この機能を利用しているアプリケーションでダウンタイムが必要になる可能性があるためです。
  • 今後のリリースで、互換性の無い変更が行われる可能性があるため、ビジネスクリティカルな場面以外での利用を推奨します。もし複数のクラスターを持っており、それぞれ個別にアップグレードが可能な場合、この制限の影響を緩和できるかもしれません。
  • 是非ベータ機能を試して、フィードバックをください！ベータから安定版になってしまうと、より多くの変更を加えることが難しくなってしまいます。
• 安定版:
  • バージョン名はvXのようになっており、Xは整数です。
  • 安定版の機能は、今後のリリースバージョンにも適用されます。

APIグループ

APIの拡張を簡易に行えるようにするため、KubernetesはAPIグループを実装しました。 APIグループは、RESTのパスとシリアライズされたオブジェクトのapiVersionフィールドで指定されます。

クラスターにはいくつかのAPIグループがあります:

1. core グループ(legacy group とも呼ばれます)は、/api/v1というRESTのパスで、apiVersion: v1を使います。

2. 名前付きのグループは、/apis/$GROUP_NAME/$VERSIONというRESTのパスで、apiVersion: $GROUP_NAME/$VERSION(例、apiVersion: batch/v1)を使います。KubernetesのAPIリファレンスにすべての使用可能なAPIグループのリストがあります。

カスタムリソースでAPIを拡張するために、2つの方法があります:

1. カスタムリソース定義は、APIサーバーが選択したリソースAPIを提供する方法を宣言的に定義できます。
2. 独自の拡張APIサーバーを実装し、アグリゲーターを使用してクライアントに対してシームレスにすることもできます。

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

いくつかのリソースとAPIグループはデフォルトで有効になっています。それらは、kube-apiserverのコマンドラインオプションとしてAPIサーバーの--runtime-config設定で、有効化、無効化できます。

--runtime-configは、カンマ区切りの複数の値を設定可能です。例えば、batch/v1を無効化する場合、--runtime-config=batch/v1=falseをセットし、batch/v2alpha1を有効化する場合、--runtime-config=batch/v2alpha1をセットします。このフラグは、APIサーバーのランタイム設定を表すkey=valueのペアを、カンマ区切りで指定したセットを指定可能です。

備考: APIグループ、リソースの有効化、無効化は、--runtime-configの変更を反映するため、kube-apiserverとkube-controller-managerの再起動が必要です。

永続性

KubernetesはAPIリソースの観点からシリアル化された状態をetcdに書き込むことで保存します。

次の項目

APIアクセスの制御は、クラスターがAPIアクセスの認証と承認を管理する方法を説明しています。

全体的なAPI規則は、API規則の資料で説明されています。

APIエンドポイント、リソースタイプ、サンプルについては、APIリファレンスをご覧ください。