kakudooo docs

Kubernetes APIについて

概要

Control PlaneにあるAPIサーバーに対してHTTPリクエストすることで、Kubernetes内のオブジェクト(例: Pod,Namespace,ConfigMap,Event,…)の状態を操作できるようにする機能。 kubectlコマンドなどREST APIをラップしたツールから操作することが一般的。(例: kubectl apply)

操作対象となるAPIリソースの表現の仕方として、API Groupsというものが用意されている。 同じリソースを複数のバージョンで操作することが可能となっている

例えば、同じリソースでv1とv1beta1の2つのバージョンが有ることを考えてみます。 v1beta1バージョンのAPIを利用しオブジェクトを最初に作成したとして、v1beta1バージョンが非推奨となり削除されるまで、v1beta1もしくはv1どちらのAPIバージョンを利用してもオブジェクトのread、update、deleteができます。 その時点では、v1 APIを使用してオブジェクトの修正やアクセスを継続することが可能です。

API Groups

REST形式のパス、manifestファイルのapiVersionフィールドとして指定される。

• Core(Legacy)グループ
  • REST APIのパス/api/v1に存在する
  • manifestファイルではapiVersion: v1のようにグループ名なしでバージョンのみ指定する
• 名前付きグループ
  • REST APIのパス/apis/$GROUP_NAME/$VERSIONの形式
  • manifestファイルのapiVersion apiVersion: $GROUP_NAME/$VERSIONの形式で指定する
    • 例: apiVersion: batch/v1
  • 用意されている標準の名前付きリソースは以下を参照
    • https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.33/#strong-api-groups-strong-

APIのVersioning

以下の3レベルのバージョンが定義されている。

• Alpha
  • 例: v1alpha1
• Beta
  • 例: v2beta3
• Stable
  • 例: v1

基準について詳細は、以下を参照

https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions

APIの変更にあたって

上記のVersioningの設計により既存クライアントとの互換性を一定期間維持することが可能であり、また、Kubernetesプロジェクトとしてもこれを推奨している。

→ APIの非推奨化ポリシーが存在する。

例えば、Beta版のAPIからStable版のAPIへ移行することになったとする。その場合、Beta版のAPIに対して非推奨期間を設け、非推奨期間中は両方のversionをアクセス可能にする必要がある。

• 非推奨期間を過ぎた後でバージョンを上げようとする場合
• CRDなどサードパーティ製のリソースで非推奨期間が設けられなかった場合

については、新旧のversionで互換性を保つ必要のある処理が存在(helm applyなど)すると問題を引き起こすことがあるので注意する。

→ Plutoを導入しておくと、apiVersionについて現在指定しているversionがDEPRECATEDかREMOVEDかを教えてくれるみたいなので活用するのもあり。

参考

• https://kubernetes.io/ja/docs/concepts/overview/kubernetes-api/
• https://kubernetes.io/ja/docs/reference/using-api/
• https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#api-conventions