🍎

【入門】KubernetesのAPIについて理解する

に公開
AWS
Kubernetes
API
EKS
kubectl
tech

はじめに

Kubernetesは「コンテナオーケストレーションツール」だが、その仕組みの中心にはKubernetes APIがある。
クラスタの内部では、PodやDeployment、ServiceといったすべてのリソースがAPIを通じて作成・管理されている。
言い換えると、Kubernetesは「APIを中心に動くシステム」

  • kubectlコマンドを打つ時
  • Web UI(Dashboard)で操作するとき
  • CI/CDツールから自動デプロイする時
    これらはすべて裏側でAPIサーバーにリクエストを送っている。

Kubernetes APIとは？

APIサーバーの位置付け

Kubernetesクラスタの「司令塔」となるのがAPIサーバー。すべての操作はAPIサーバーを経由して行われる。

  • ユーザーがkubectlコマンドを実行すると、そのリクエストはAPIサーバーに送られる
  • コントローラーやスケジューラーといったKubernetesの内部コンポーネントも、APIサーバーを介して情報を取得・更新する。
  • APIサーバーはクラスタの状態をetcdに保存し、正確な状態管理を担う

つまりAPIサーバーは「クラスタの入り口」「状態管理のハブ」として機能している。

APIを通じてやり取りされるリソース

Kubernetesでは、クラスタを構成するあらゆる要素をリソースとしてAPI経由で操作する。
代表的なリソースは以下がある。

  • Pod：コンテナの実行単位。最小のデプロイ単位
  • Deployment：複数のPodを管理・更新するための仕組み
  • Service：Podへのアクセス方法を定義
  • Namespace：リソースを論理的に区切る仕組み
  • ConfigMap/Secret：設定情報や機密情報を管理するリソース

これらはすべてAPIサーバーに対してCRUD操作することで扱う。例えば、kubectl get podsは「Podリソースの一覧を取得する」APIリクエスト、kubectl apply -f deployment.yamlは「Deploymentリソースを作成または更新する」APIリクエストである。

APIの構造

Kubernetes APIはRESTful APIとして設計されている。
つまり、HTTPリクエストを使ってリソースの作成・取得・更新・削除を行う

基本のエンドポイント構造

KubernetesはAPIエンドポイントは、以下のような形式になっている。

/apis/<APIグループ>/<バージョン>/<リソース>

または一部の基本リソースでは：

/api/v1/<リソース>

例：

  • Pod一覧の取得：
GET /api/v1/pods
  • ある名前空間のDeployment一覧：
GET /apis/apps/v1/namespaces/default/deployments

3つの要素で構成

1. API Group(APIグループ)

  • リソースを分類するためのグループ
  • 例：
    • coreグループ(Pod、Service、ConfigMapなど基本リソース→/api/v1)
    • appsグループ(Deployment、DaemonSet、StatefulSet→/apis/apps/v1)
    • batchグループ(Job、CronJob→/apis/batch/v1)

2. Version(バージョン)

  • APIの安定度を示すもの
  • よく使うのはv1(安定版)、開発中や試験的なものはv1beta1、v1alphaなど

3. Resource(リソース)

  • 実際に操作する対象
  • 例：pods、deployments、services、jobsなど

kubectlとAPIの関係

kubectlコマンドがAPIを呼び出している仕組み

kubectlはKubernetesを操作するためのCLIツールだが、実際にはAPIサーバーにHTTPリクエストを送るクライアント。

  • 例えばkubectl get podsを実行すると、内部的には以下のようなAPI呼び出しを行なっている
GET /api/v1/pods
  • そのレスポンス(JSONデータ)を受け取り、見やすい表形式に整えて表示しているのがkubectl

kubextl proxyで直接APIに触れる

kubectl proxyを実行すると、ローカルにHTTPプロキシを立ち上げ、認証や証明書の処理をkubectlが肩代わりしてくれる。

kubectl proxy

これでhttp:127.0.0.1：8001/にアクセスすると、Kubernetes APIサーバーに安全に接続できる。
例：

curl http://127.0.0.1:8001/api/v1/namespaces/default/pods

→ defaultネームスペースのPod一覧がJSONで返る

kubectl get --rawで直接APIを叩く

もう１つの方法として、kubectl get --rawを使うとAPIの生レスポンスを取得可能
例：クラスタの全APIリソースを確認する方法

kubectl get --raw /api/v1

例：API Groupsの一覧を取得

kubectl get --raw /apis

これにより、普段kubectl getで整形されている情報がそのままJSONで見られ、Kubernetesがどのようにデータを返しているかを理解できる。

認証と認可

認証方式(Authentication)

認証とは「アクセスしてきたのは誰か？」を確認する仕組み。KUbernetes APIサーバーは以下の方法で認証を行う。

  • 証明書認証(X.509証明書)
    • 管理者やkubeletなどクラスタの内部コンポーネントはクライアント証明書を利用
    • ~/.kube/config内に埋め込まれている証明書を kubectl が使用
  • ベアラートークン
    • ServiceAccountに関連づけられたトークンを利用し、PodやアプリケーションからAPIにアクセス
  • OIDC(OpenID Connect)
    • Google、Azure AD、Keycloakなど外部IdPと連携し、シングルサインオンを実現

これらを組み合わせて「クラスタ外の人間」「クラスタ内のPod」「外部サービス」など、様々なクライアントを認証する。

RBACによる権限制御(Authorization)

認証で「誰か」が分かったら、次は「その人が何をできるか？」を制御。これが認可
Kubernetesでは主にRBAC(Role-Based Access Control)を使う。

  • Role/ClusterRole
    • Roleは特定のネームスペース内の権限を定義
    • ClusterRoleはクラスタ全体で有効な権限を定義
  • RoleBinding/ClusterRoleBinding
    • ユーザーやServiceAccountをRoleに紐付ける

例：defaultネームスペース内のPodを閲覧できるRole

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: default
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

ネームスペースとスコープ

Kubernetesでは、リソースを Namespace ごとに分離できる。これにより、同じクラスタでも「開発環境」「本番環境」などを論理的に分割可能。

  • Role は ネームスペース単位 で権限を管理
  • ClusterRole は 全ネームスペース横断 で権限を付与

つまり、ユーザーやアプリがAPIにアクセスする際には、
「どのNamespaceの、どのリソースに、どんな操作をしていいのか？」が細かく制御される。

まとめ

  • Kubernetesは API駆動 で動作しており、すべての操作はAPIサーバー（kube-apiserver）を通じて行われる
  • APIは REST構造（Group/Version/Resource） を持ち、PodやDeploymentなどのリソースをCRUD操作可能
  • kubectl はAPIクライアントであり、認証・認可やRBACを通じて安全にリソースを管理

Discussion