Kubernetes APIとは｜仕組み・リソース・エンドポイント構造とCRD拡張を実例で解説

Kubernetes APIは、クラスタ内のあらゆるリソース（Pod・Service・Deploymentなど）を統一的に操作するためのRESTfulなHTTPインターフェースです。kubectlもダッシュボードもCI/CDツールも、内部ではすべてこのAPIを呼んでクラスタを動かしています。つまりKubernetes APIを理解することは、Kubernetesの内部動作を理解することとほぼ同義です。この記事では、APIサーバーの処理フロー、主要リソースとスコープ、APIグループとバージョン管理、RESTエンドポイント構造、CRDによる拡張までを実例で整理します。Kubernetesそのものの全体像はKubernetes（クーベネティス）とは？読み方・K8sの意味から仕組みまで初心者向けに解説を先に読むと理解が早まります。

まとめ：Kubernetes APIの要点

• 正体：クラスタの全リソースを操作するRESTful HTTP API。処理するのはkube-apiserverで、クラスタ唯一のフロントエンドかつetcdへの唯一の書き込み口。
• 処理順：リクエストは「認証 → 認可(RBAC) → Admission(検証・変更) → etcd保存」の順に通り、各コントローラーへイベント通知される。
• 識別子：各リソースはグループ・バージョン・リソース(GVR)で一意。コアは/api/v1、拡張は/apis/<group>/<version>。
• バージョン：Alpha→Beta→GAの3段階。GA(v1)は非推奨後も12ヶ月または3リリース維持される（一次情報）。
• 操作の入口：日常はkubectlかクライアントライブラリ経由。生のcurl直叩きは学習・デバッグ・制約環境に限る。
• 拡張：CRD(apiextensions.k8s.io/v1)で独自リソースを追加でき、Operatorで振る舞いを与える。

Kubernetes APIとは：クラスタ操作の統一インターフェース

Kubernetes APIは、クラスタ内リソースの作成・取得・更新・削除を単一の窓口で扱うRESTful APIです。リソースの取得はGET、作成はPOST、全面更新はPUT、部分更新はPATCH、削除はDELETEという標準HTTPメソッドに対応します。加えて、リソースの変更をリアルタイムに受け取るwatch（list-watch）があり、コントローラーやOperatorはこの仕組みで状態変化を監視します。

HTTPで統一されているため、言語や環境を問わずプログラムから制御でき、自動化や他システム連携がしやすいのが最大の利点です。管理系ツールやクラウドのマネージドサービス（例：AKS（Azure Kubernetes Service））も、裏側はこのAPI呼び出しで動いています。

APIサーバー(kube-apiserver)の仕組み：リクエスト処理とetcd連携

Kubernetes APIを処理する実体がkube-apiserverです。クラスタ唯一の入口として全リクエストを受理し、クラスタ状態を保存する分散キーバリューストアetcdと連携します。etcdはクラスタの「唯一の真実の情報源（source of truth）」であり、APIサーバーだけがetcdへ書き込みます。他のコンポーネント（スケジューラーや各コントローラー）はetcdへ直接触れず、必ずAPIサーバー経由でやり取りします。

リクエスト処理の4ステップ：3つの関門とetcd保存

たとえばPOST /api/v1/namespaces/default/podsでPodを作る場合、リクエストは次の順で処理されます。

1. 認証(Authentication)：クライアント証明書・Bearerトークン・OIDCなどで「誰か」を確認する。kubectlはkubeconfig内の資格情報を使う。
2. 認可(Authorization)：主にRBACで「その操作を許可されているか」を判定する。RoleやClusterRoleのバインドが根拠になる。
3. Admission制御：認可後もすぐには保存されない。Mutating Admission（デフォルト値補完・サイドカー注入など）とValidating Admission（ResourceQuota超過拒否・ポリシー違反拒否）が最後の関門となる。かつてのPodSecurityPolicyはこの一種で、v1.25で廃止されPod Security Admissionへ置き換わった。
4. etcd保存とイベント通知：全チェックを通ったオブジェクトだけがetcdに書き込まれ、201などで応答。その後watchで各コントローラーへ通知され、スケジューラーがノード割り当てを進める。

APIサーバーは単なる保存係ではなく、書き込みを起点にクラスタ全体の動作を駆動するトリガーとして働きます。Podの正常性判定に使うLiveness Probeのような設定も、この宣言的な仕組みの上で機能します（Liveness ProbeはPod spec内のフィールドで、独立したAPIリソースではありません）。

主要リソースとスコープ：Namespacedとクラスタースコープ

Kubernetes APIが扱うオブジェクトは多数ありますが、性質でカテゴリ分けすると把握しやすくなります。

Namespacedリソースは特定のNamespace内で名前が一意であればよく、別Namespaceに同名オブジェクトを共存させられます（例：team-aとteam-bにそれぞれnginx Pod）。操作時は-n <namespace>で対象を指定します。クラスタースコープリソースはNamespaceに属さずクラスタ全体で一意で、Namespace指定は不要（指定しても無視）です。

あるリソースがどちらかはkubectl api-resourcesのNAMESPACED列（true/false）で確認できます。同じ出力のAPIVERSION列で、そのリソースが属するグループとバージョンも一目で分かります。

APIグループとバージョン管理：core・apis・GVRと非推奨ポリシー

リソースはグループ・バージョン・リソース名(GVR)で一意に識別されます。Podはグループ空・バージョンv1・リソースpods、Deploymentはグループapps・v1・deploymentsです。グループ名を持たないコアグループ（Pod・Service・Node・Secretなど基本リソース）はURLで/api/v1、名前付きの拡張グループ（apps／batch／networking.k8s.io／rbac.authorization.k8s.ioなど）は/apis/<group>/<version>で表されます。機能領域ごとにグループを分けることで、独立した開発サイクルと名前衝突の回避を両立しています。

Alpha・Beta・GAと非推奨のルール

APIは安定度に応じて段階が進みます。Alphaは機能ゲートで明示的に有効化しないと使えず、予告なく仕様変更・削除される可能性があるため本番非推奨です。Betaはある程度安定していますが、既存のBeta APIは有効のまま、v1.24以降に新規追加されるBeta APIは既定で無効化される方針に変わっています。GA（v1など正式版）は後方互換が重視され、安心して本番利用できます。

非推奨(Deprecated)後の維持期間は公式ポリシーで定められています。GA APIは非推奨後も最低12ヶ月または3リリース（長い方）、Beta APIは9ヶ月または3リリース提供が保証され、Alphaは無保証です。実際にextensions/v1beta1のDeployment・Ingress・DaemonSetはv1.16で削除されapps/v1やnetworking.k8s.io/v1へ移行、前述のPodSecurityPolicyはv1.25で削除されました。

アップグレード前には、マニフェストのapiVersionが削除対象でないかリリースノートで確認するのが実務の鉄則です。サポート対象は原則直近3マイナー（執筆時点で1.34〜1.36、最新パッチは公式リリースページで確認）で、各版の新機能や削除APIの詳細はKubernetes 1.35主要新機能と変更点やKubernetes 1.34の新機能・変更点とEOLで追えます。

RESTエンドポイント構造：URLパスの読み方

エンドポイントはグループとスコープでパターンが決まります。規則を覚えれば、apiVersionとkindからURLをほぼ推測できます。

Namespacedリソースには必ず/namespaces/{ns}が挟まり、クラスタースコープには入りません。この規則性のおかげで、エラーメッセージ中のパスを見るだけで問題のリソース箇所を特定できます。

kubectlとKubernetes APIの関係：CLIからRESTへの変換

kubectlは公式CLIですが、実体はKubernetes APIクライアントです。kubectl get podsはGET /api/v1/namespaces/{ns}/podsを、kubectl create -f deployment.yamlはPOST /apis/apps/v1/namespaces/{ns}/deploymentsを送っているだけで、対象クラスタ・Namespace・認証情報は~/.kube/configのコンテキストから解決されます。通信はTLSで暗号化されたHTTPSです。実際にどのAPIを叩いているかはkubectl get pods -v=8のように詳細ログを出すと確認できます。

プログラムから使う場合は、生のHTTPを組み立てず公式クライアントライブラリ（Go用client-go、Python用kubernetes-client、Java・JavaScript用など）を使うのが定石です。認証やバージョン折衝を肩代わりしてくれるため、list_namespaced_pod(namespace)のような関数呼び出しで済みます。

curlで直接叩くべき場面・避けるべき場面

curlでの直接呼び出しも可能です。

curl -X GET https://<APIサーバー>/api/v1/pods \
  -H "Authorization: Bearer <トークン>" --cacert <CA証明書>

ただし本番運用でkubectlの代わりに常用するのは避けるべきです。トークン更新・証明書管理・非推奨APIへの追従を自前で背負うことになり、事故のもとになります。直叩きが向くのは、APIの挙動を学ぶとき、kubectlが入らない制約環境での緊急対応、細かなHTTP制御が要るデバッグに限られます。手元で気軽に試すならkubectl proxyで認証を肩代わりさせ、curl localhost:8001/api/v1/...と叩く方法が安全です。

CRDによるAPI拡張とOperator

Kubernetes APIはCustomResourceDefinition(CRD)で拡張できます。CRDはapiextensions.k8s.io/v1（v1.16でGA）のリソースで、これを適用すると独自のリソース種別がAPIに追加され、標準リソースと同じくetcd保存・RBAC・kubectl操作の対象になります。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: applications.example.com
spec:
  group: example.com
  scope: Namespaced
  names:
    plural: applications
    singular: application
    kind: Application
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                image: { type: string }
              required: ["image"]

適用後はkubectl get applicationsのように扱えます。ただしCRDを定義しただけでは何も起きません。作成を検知して実際の処理（DB構築・外部連携など）を行うカスタムコントローラー＝Operatorを実装して初めて、宣言的な自動運用が成立します。導入時はopenAPIV3Schemaで必須フィールドや型をきちんと定義しておくこと、将来のスキーマ変更に備えて複数versionsで移行経路を用意することが要点です。スキーマ未定義のCRDは入力ミスを検知できず、後の互換性維持が難しくなります。

よくある質問（FAQ）

Kubernetes APIとkubectlの違いは？

Kubernetes APIはクラスタを操作するHTTPインターフェース（サーバー側の窓口）、kubectlはそれを呼ぶCLIクライアントです。kubectlの各コマンドは内部で対応するREST呼び出しに変換されており、両者は「窓口」と「窓口を叩く道具」の関係にあります。

apiVersionには何を書けばいい？

そのリソースが属する「グループ/バージョン」を書きます。コアリソース（Pod・Service・ConfigMapなど）はv1、Deployment・StatefulSetはapps/v1、Ingress・NetworkPolicyはnetworking.k8s.io/v1、CronJobはbatch/v1です。正確な値はkubectl explain <リソース名>やkubectl api-resourcesのAPIVERSION列で確認できます。

利用可能なAPIリソースの一覧を確認するには？

kubectl api-resourcesで全リソース種別・短縮名・APIグループ・NAMESPACED（名前空間の有無）が表形式で出ます。kubectl api-versionsを併用すると、クラスタで有効なグループ/バージョンの一覧も確認できます。

Alpha版のAPIを本番で使ってよい？

推奨されません。Alpha APIは既定で無効で、予告なく仕様変更・削除される可能性があります。本番で機能を使うなら、原則GA（安定版）まで昇格したものに限り、Beta利用時もリリースノートで変更を追う前提にしてください。

Kubernetes APIとアプリが公開するAPIは同じもの？

別物です。ここでのKubernetes APIはクラスタ基盤を管理するための管理API（コントロールプレーンのAPI）で、コンテナ内アプリが外部へ公開する業務APIとは層が異なります。混同するとRBACやエンドポイント設計を誤るため、対象を明確に区別してください。関連する内容として、ScalarDB Clusterもご覧ください。

関連記事

• Kubernetes（クーベネティス）とは？読み方・K8sの意味から仕組みまで初心者向けに解説
• Kubernetes 1.35主要新機能と変更点を徹底解説: アップグレード前に知っておくべき重要なポイント
• Kubernetes 1.34の新機能・変更点とEOL｜DRA GA・再起動ルール・EKS対応を解説
• コンテナの正常性チェックにおけるLiveness Probeの重要性と実装方法
• AKS（Azure Kubernetes Service）とは｜できること・料金・始め方を解説【2026年版】