Kubernetes API

全般的なAPIの規則は、API規則ドキュメントに記載されています。

APIエンドポイント、リソースタイプ、そしてサンプルはAPIリファレンスに記載されています。

APIへの外部からのアクセスは、APIアクセス制御ドキュメントに記載されています。

Kubernetes APIは、システムの宣言的設定スキーマの基礎としても機能します。kubectlコマンドラインツールから、APIオブジェクトを作成、更新、削除、取得することができます。

また、Kubernetesは、シリアライズされた状態を(現在はetcdに)APIリソースの単位で保存しています。

Kubernetesそれ自身は複数のコンポーネントから構成されており、APIを介して連携しています。

APIの変更

我々の経験上、成功を収めているどのようなシステムも、新しいユースケースへの対応、既存の変更に合わせ、成長し変わっていく必要があります。したがって、Kubernetesにも継続的に変化、成長することを期待しています。一方で、長期間にわたり、既存のクライアントとの互換性を損なわないようにする予定です。一般的に、新しいAPIリソースとリソースフィールドは頻繁に追加されることが予想されます。リソース、フィールドの削除は、API廃止ポリシーへの準拠を必要とします。

何が互換性のある変更を意味するか、またAPIをどのように変更するかは、API変更ドキュメントに詳解されています。

OpenAPIとSwaggerの定義

完全なAPIの詳細は、OpenAPIに記載されています。

Kubernetes 1.10から、KubernetesAPIサーバーは/openapi/v2のエンドポイントを通じて、OpenAPI仕様を提供しています。 リクエストフォーマットは、HTTPヘッダーを下記のように設定することで指定されます:

ヘッダ設定可能な値
Acceptapplication/json, application/com.github.proto-openapi.spec.v2@v1.0+protobuf (デフォルトのcontent-typeは、*/*に対してapplication/jsonか、もしくはこのヘッダーを送信しません)
Accept-Encodinggzip (このヘッダーを送信しないことも許容されています)

1.14より前のバージョンでは、フォーマット分離エンドポイント(/swagger.json, /swagger-2.0.0.json, /swagger-2.0.0.pb-v1, /swagger-2.0.0.pb-v1.gz)が、OpenAPI仕様を違うフォーマットで提供しています。これらのエンドポイントは非推奨となっており、Kubernetes1.14で削除されました。

OpenAPI仕様の取得サンプル:

1.10より前Kubernetes1.10以降
GET /swagger.jsonGET /openapi/v2 Accept: application/json
GET /swagger-2.0.0.pb-v1GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf
GET /swagger-2.0.0.pb-v1.gzGET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf Accept-Encoding: gzip

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

また、1.14より前のバージョンのKubernetesAPIサーバーでは、Swagger v1.2をベースにしたKubernetes仕様を、/swaggerapiで公開しています。 このエンドポイントは非推奨となっており、Kubernetes1.14で削除されました。

APIバージョニング

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

APIが、システムリソースと動作について明確かつ一貫したビューを提供し、サポート終了、実験的なAPIへのアクセス制御を有効にするために、リソースまたはフィールドレベルではなく、APIレベルでバージョンを付けることを選択しました。JSONとProtocol Buffersのシリアライズスキーマも、スキーマ変更に関して同じガイドラインに従います。ここから以下の説明は、双方のフォーマットをカバーしています。

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

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

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

APIグループ

KubernetesAPIの拡張を簡易に行えるようにするため、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)を使います。サポートされているAPIグループの全リストは、Kubernetes APIリファレンスを参照してください。

カスタムリソースでAPIを拡張するために、2つの方法がサポートされています:

  1. カスタムリソース定義は、とても基本的なCRUDが必要なユーザー向けです。
  2. 独自のAPIサーバーを実装可能な、フルセットのKubernetes APIが必要なユーザーは、アグリゲーターを使い、クライアントにシームレスな形で拡張を行います。

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

いくつかのリソースとAPIグループはデフォルトで有効になっています。それらは、APIサーバーの--runtime-config設定で、有効化、無効化できます。--runtime-configは、カンマ区切りの複数の値を設定可能です。例えば、batch/v1を無効化する場合、--runtime-config=batch/v1=falseをセットし、batch/v2alpha1を有効化する場合、--runtime-config=batch/v2alpha1をセットします。このフラグは、APIサーバーのランタイム設定を表すkey=valueのペアを、カンマ区切りで指定したセットを指定可能です。

備考: APIグループ、リソースの有効化、無効化は、--runtime-configの変更を反映するため、APIサーバーとコントローラーマネージャーの再起動が必要です。

APIグループextensions/v1beta1に含まれる特定のリソースの有効化

APIグループextensions/v1beta1に含まれるDaemonSets、Deployments、StatefulSet、NetworkPolicies、PodSecurityPolicies、ReplicaSetsはデフォルトで無効にされています。 例えば、deploymentとdaemonsetを有効にするには、--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=trueと設定します。

備考: リソースを個別に有効化、無効化することは歴史的な理由によりAPIグループextensions/v1beta1に含まれるリソースに限りサポートされています。
最終更新 July 22, 2020 at 10:05 AM PST: Refine the translation following the suggestion. (5316ff3b5)