TL; DR

• いわゆるKubernetesのリリースバージョンはコンポーネントバイナリのバージョンを指す。
• マニフェストに記載するAPIバージョンはAPIグループとバージョンから構成され、APIグループごとに成熟度を表すバージョンが設定されている。
• feature gateは実験的機能の成熟度を表し、APIグループのバージョンとは別に管理される。

背景

Kubernetesのバージョンというと何を思い浮かべるでしょうか？

私が真っ先に思い浮かべるのは、いわゆるKubernetesのリリースバージョンで、この記事を書いている時点ではv1.34.2が最新であり、次回リリースは2025年12月にv1.35が予定されています。

しかしそれ以外にもバージョンに関する概念がいくつか存在します。

例えばマニフェストファイルに記載するAPIバージョンです。 Deploymentリソースを作成する際には、マニフェストのapiVersionフィールドにはapp/v1と記載するようになっています。

また、バージョンと似た話として、feature gateがbetaからGAになったなどという話もよく聞きます。

今まで私はこれらの概念についてちゃんと深くまで理解していなかったため、本記事では以下の3つの概念について整理してみます。

• いわゆるKubernetesのリリースバージョン
• マニフェストに記載するAPIバージョン
• feature gateのリリースチャネル

いわゆるKubernetesのリリースバージョン

バージョニングに関するドキュメントに端的な説明があります。

X.Y.Z refers to the version (git tag) of Kubernetes that is released. This versions all components: apiserver, kubelet, kubectl, etc. (X is the major version, Y is the minor version, and Z is the patch version.)

また、公式ドキュメントの記載も参考とすると、いわゆるKubernetesのリリースバージョンは以下のように説明できます。

• リリースバージョンはコンポーネントバイナリのバージョンを指す
• major.minior.patchの形式のsemantic versioningで表現される

つまり、kube-apiserverやkubeletに対してのバージョンであり、通常のアプリケーションのバージョニングと同様に機能追加やバグフィックスに応じて上がっていく形です。

なお、Kubernetesは複数のコンポーネントから構成されており、当然バージョンがあまりにも違いすぎるコンポーネントが混在すると不具合が起きる可能性があります。 これを防ぐために「kube-apiserverのバージョンがv1.34系の場合、kubeletのバージョンはv1.31~v1.34である必要がある」といったVersion Skew Policyも定義されています。

ちなみに、minorリリースは3,4ヶ月に1回のペースでリリースされることとなっていますが、majorリリースに関しては現時点ではv2系のリリースの予定はないようです。

マニフェストに記載するAPIバージョン

以下はDeploymentを作成する際のマニフェストですが、apiVersionにapps/v1と記載されています。 これは果たして何をさしているのでしょうか？

apiVersion: apps/v1 # APIバージョンの記載
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:latest

そもそも、Kubernetesにおけるマニフェストは、最終的にはkube-apiserverが提供するKubernetes APIを通じてリソースを操作するためためのものです。 例えば、上のマニフェストによってDeploymentを作成する場合、下記のようなREST APIリクエストがkube-apiserverに送信されます。

POST /apis/apps/v1/namespaces/{namespace}/deployments
# cf. https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/#create-create-a-deployment

このAPIパスにはマニフェストのapiVersionフィールドに指定したapps/v1も含まれていますが、正確にはこれらはAPIグループ（apps）とバージョン（v1）から構成されています¹。

実はKubernetes APIは単一のAPIではなく、用途や役割によって複数のまとまりに分かれており、APIグループはそのまとまりを指しています。 例えばDeploymentであればappsグループに属しており、JobやCronJobはbatchグループに属しています。

そしてバージョンは、これらAPIグループそれぞれに対して設定されており、semantic versioningではなく以下のようにAPIの成熟度を表しています（参考1・参考2・参考3）。

• alpha：開発途上でありスキーマ・仕様は不安定。開発者向けであり一般ユーザーは使うべきではない。
  • ex. PodCertificateRequestが属するcertificates.k8s.io/v1alpha1
• beta：開発途上でありスキーマ・仕様は不安定であるが、テストなどは完備されている。アーリーアダプター向け。
  • ex. MutatingAdmissionPolicyが属するadmissionregistration.k8s.io/v1beta1
• GA：安定版。
  • ex. Podが属するcore/v1

alphaとbetaのAPIバージョンはデフォルトで無効となっており、kube-apiserverのruntime-onfigで明示的に有効にしないと使うことはできません。

なお、注意する点としてこれらのバージョンはあくまでもAPIグループに対して設定されているものであり、個別のKindに対して設定されているわけではないという点があります。

この理由については公式ドキュメントにも簡単な言及がありますが、解釈についてはfeature gateの必要性にて後述します。

それでは、KubernetesのリリースバージョンとAPIグループバージョンの関係性について整理していきましょう。 図にすると以下のようになります。

A given release of Kubernetes can support any number of API groups and any number of versions of each.

公式ドキュメントに記載があるようにコントロールプレーンのあるコンポーネントバージョンでは、各APIグループのバージョンのうち、いくつかがサポートされるという形となっています。 この際、同じAPIグループであっても複数のバージョンをサポートすることができます。

上の図の例だと、

• PodやServiceが含まれるcore/v1グループはv1.33・v1.34の両方でサポートされている。
• DeviceClassはresource.k8s.ioのv1beta2とv1の両方があり、後者はv1.34でのみサポートされている。
• Eventはevents.k8s.io/v1とcore/v1の両方に存在しており、複数のAPIグループにまたがって存在することもある。

などといったことが確認できます。

まとめると、マニフェストに記載するAPIバージョンは、機能的なまとまりであるAPIグループに対して設定されており、リリースバージョンはそれらAPIグループバージョンのうちいくつかをサポートする形となっています。

feature gateのリリースチャネル

それでは3つ目の概念であるfeature gateのリリースチャネルについて整理します。

まず、feature gateは細かい実験的機能の成熟レベルを表し、kube-apiserverのfeature-gatesオプションによって無効・有効化されます。 そしてリリースチャネルは以下の3つとなります。

• alpha：仕様は不安定で、バグを含む可能性も捨てきれない。デフォルトでは無効。
• beta：仕様は変更の可能性はあるものの、テストもされており一般利用には安全。デフォルトで有効となっている場合が多い。
• GA：安定版。

例えばkubeletでの分散トレーシングを有効にするKubeletTracing feature gateは

• v1.25でalpha
• v1.27でbeta
• v1.34でGA と遷移しています。

そしてややこしいのが、同一APIグループ・バージョンであっても、feature gateによってマニフェスト上のフィールドが変わることがあるという点です。 例えばDeploymentのstatus.terminatingReplicasはv1.33でalphaとなっており、appsグループがv1だったとしてもこのfeature gateのないリリースバージョンでは存在しません。

feature gateの必要性

APIグループのバージョンとコントロールプレーンコンポーネントのバージョンの関係性は割とわかりやすく、APIのバージョンとそれを実際にどのバイナリでサポートしているかというものでした。

しかし、feature gateは機能を有効にするかというものなので、その点でAPIグループのバージョンと本質的に同じ役割を果たしているのではないか？という疑問が生じます。 つまり、もしAPIグループのバージョンがsemantic versionに従っていれば、そのバージョンアップによって機能の有効化や無効化を表現することができ、feature gateは不要になるのではないか？ということです。

しかし一般的なAPIのバージョニングとkubernetesの機能開発に求められる性質の違いを考えると、feature gateはAPIグループのバージョンとは別に必要であることがわかります。

というのも、feature gateはあくまでも「実験的機能」であり、「導入することが決定した機能」ではないからです。 もし後者であればminorバージョンアップで機能を追加し古い機能をdeprecatedにした上でmajorバージョンアップで古い機能を消す、みたいなことができるためsemantic versioningでよいでしょう。 しかしfeature gateはそのものが消える可能性があり、これをAPIグループのバージョンで取り扱おうとすると、feature gateが消えるたびにmajorバージョンが上がったりとAPIグループのバージョニングが不安定になってしまいます。

ドキュメントでも書かれているように、kubernetesコミュニティの開発サイクルを維持しつつも利用者に混乱させないように、長期間存続しないfeature gateは独自のサイクルを保っているということのようです。

Feature gates are intended to cover the development life cycle of a feature - they are not intended to be long-term APIs. As such, they are expected to be deprecated and removed after a feature becomes GA or is dropped.

また、先述したようなKind単位でのバージョン管理がされていない理由も似たことが言えます。 もしKind単位でバージョン管理がされた場合、関連した機能を持つKindであっても独立にバージョンがあり、実質的に同じタイミングでバージョンアップされるにもかかわらずバージョン管理の手間だけが膨大になってしまいます。

まとめ

この記事では、Kubernetesに登場する複数のバージョンの概念について整理しました。

まとめると、

• いわゆるKubernetesのリリースバージョンはコンポーネントバイナリのバージョンを指す。
• マニフェストに記載するAPIバージョンはAPIグループとバージョンから構成され、APIグループごとに成熟度を表すバージョンが設定されている。
• feature gateは実験的機能の成熟度を表し、APIグループのバージョンとは別に管理される。

となります。