Kubernetes API
Kubernetesの中核である control planeはAPI server です。 APIサーバーは、エンドユーザー、クラスターのさまざまな部分、および外部コンポーネントが相互に通信できるようにするHTTP APIを公開します。
Kubernetes APIを使用すると、Kubernetes API内のオブジェクトの状態をクエリで操作できます（例：Pod、Namespace、ConfigMap、Events）。
ほとんどの操作は、APIを使用しているkubectlコマンドラインインターフェースもしくはkubeadmのような別のコマンドラインツールを通して実行できます。 RESTコールを利用して直接APIにアクセスすることも可能です。
Kubernetes APIを利用してアプリケーションを書いているのであれば、client librariesの利用を考えてみてください。
OpenAPI 仕様
完全なAPIの詳細は、OpenAPIを使用して文書化されています。
Kubernetes APIサーバーは、/openapi/v2エンドポイントを介してOpenAPI仕様を提供します。
次のように要求ヘッダーを使用して、応答フォーマットを要求できます。
| Header | Possible values | Notes |
|---|---|---|
Accept-Encoding |
gzip |
このヘッダーを使わないことも可能 |
Accept |
application/com.github.proto-openapi.spec.v2@v1.0+protobuf |
主にクラスター内での使用 |
application/json |
デフォルト | |
* |
application/jsonを提供 |
Kubernetesは、他の手段として主にクラスター間の連携用途向けのAPIに、Protocol buffersをベースにしたシリアライズフォーマットを実装しています。このフォーマットに関しては、[Kubernetes Protobuf serialization](https://github.com/kubernetes/community/blob/master/contributors/des ign-proposals/api-machinery/protobuf.md)デザイン提案を参照してください。また、各スキーマのInterface Definition Language（IDL）ファイルは、APIオブジェクトを定義しているGoパッケージ内に配置されています。
永続性
KubernetesはAPIリソースの観点からシリアル化された状態をetcdに書き込むことで保存します。
APIグループとバージョニング
フィールドの削除やリソース表現の再構成を簡単に行えるようにするため、Kubernetesは複数のAPIバージョンをサポートしており、/api/v1や/apis/rbac.authorization.k8s.io/v1alpha1のように、それぞれ異なるAPIのパスが割り当てられています。
APIが、システムリソースと動作について明確かつ一貫したビューを提供し、サポート終了、実験的なAPIへのアクセス制御を有効にするために、リソースまたはフィールドレベルではなく、APIレベルでバージョンが行われます。
APIの発展や拡張を簡易に行えるようにするため、Kubernetesは有効もしくは無効を行えるAPIグループを実装しました。
APIリソースは、APIグループ、リソースタイプ、ネームスペース（namespacedリソースのための）、名前によって区別されます。APIサーバーは、APIバージョン間の変換を透過的に処理します。すべてのバージョンの違いは、実際のところ同じ永続データとして表現されます。APIサーバーは、同じ基本的なデータを複数のAPIバージョンで提供することができます。
例えば、同じリソースでv1とv1beta1の2つのバージョンが有ることを考えてみます。v1beta1バージョンのAPIを利用しオブジェクトを最初に作成したとして、v1beta1もしくはv1どちらのAPIバージョンを利用してもオブジェクトのread、update、deleteができます。
APIの変更
成功を収めているシステムはすべて、新しいユースケースの出現や既存の変化に応じて成長し、変化する必要があります。 したがって、Kubernetesには、Kubernetes APIを継続的に変更および拡張できる設計機能があります。 Kubernetesプロジェクトは、既存のクライアントとの互換性を破壊 しないこと 、およびその互換性を一定期間維持して、他のプロジェクトが適応する機会を提供することを目的としています。
基本的に、新しいAPIリソースと新しいリソースフィールドは追加することができます。 リソースまたはフィールドを削除するには、API非推奨ポリシーに従ってください。
Kubernetesは、公式のKubernetes APIが一度一般提供（GA）に達した場合、通常はv1APIバージョンです、互換性を維持することを強い責任があります。さらに、Kubernetesは beta についても可能な限り互換性を維持し続けます。ベータAPIを採用した場合、その機能が安定版になったあとでも、APIを利用してクラスタを操作し続けることができます。
備考: Kubernetesは、 alpha APIバージョンについても互換性の維持に注力しますが、いくつかの事情により不可である場合もあります。アルファAPIバージョンを使っている場合、クラスタのアップグレードやAPIが変更された場合に備えて、Kubernetesのリリースノートを確認してください。
APIバージョンレベルの定義に関する詳細はAPIバージョンのリファレンスを参照してください。
APIの拡張
Kubernetes APIは2つの方法で拡張できます。
- カスタムリソースは、APIサーバーが選択したリソースAPIをどのように提供するかを宣言的に定義します。
- アグリゲーションレイヤーを実装することでKubernetes APIを拡張することもできます。
次の項目
- 自分自身でカスタムリソース定義を追加してKubernetes APIを拡張する方法について学んでください。
- Kubernetes APIのアクセス制御では、クラスターがAPIアクセスの認証と承認を管理する方法を説明しています。
- APIリファレンスを読んで、APIエンドポイント、リソースタイプやサンプルについて学んでください。
- APIの変更から、互換性のある変更とは何か, どのようにAPIを変更するかについて学んでください。