Kubernetesアーキテクチャ
YAMLがコンテナになるまでを追う

3日目です。昨日の第1章では、Podを直接作ると誰も見張らず、Deploymentという見張り役を付けると消しても戻ってくることを確かめました。今日は、その「見張り役」と「裏側の部品たち」を分解します。kubectl apply と打ってからコンテナが動き出すまでに、誰が何をしているのか。それが見えると、症状を見た瞬間に「止まっているのはどの層か」を言えるようになります。

昨日の演習の続きになっているので、第1章を読んでいない方は、先に「最初のPodを動かす」と「kubectlで状態を読む」だけ目を通しておいてください。

この章の結論

この章では部品の名前を暗記してもらうつもりはありません。代わりに、1本のDeploymentを作って、イベントの1行1行が「誰の仕事か」を読めるようにします。読めるようになると、Pending と ImagePullBackOff が別の層の話だと、見た瞬間にわかります。

5つの部品と、それぞれの仕事

特集トップの図1で「司令塔」とまとめたControl Planeの中身と、Node側の部品を、仕事で分けると次の表になります。

ほかにも、Serviceの通信を各Nodeで振り分けるkube-proxyや、クラウドと連携するCloud Controller Managerがいますが、第2章ではこの5つに絞ります。kube-proxyは第4章で扱います。

YAMLがコンテナになるまでの6ステップ

第1章でDeploymentを作ったとき、裏では次の順番で仕事が回っていました。図2-1の番号を追ってください。

図2-1: kubectl applyからコンテナ起動まで。1〜4はControl Plane、5はNode、6は報告。

1. kubectlがAPI Serverに送る。 YAMLはHTTPのリクエストになってAPI Serverへ届きます。あなたが話す相手は、いつもAPI Serverだけです。
2. API Serverがetcdに保存する。 認証・認可・検証を通ったDeploymentが、望ましい状態として台帳に書かれます。apply が「成功」と返すのはこの時点で、まだコンテナは1つも動いていません。
3. Controllerが子を作る。 Deploymentの見張り役が「このDeploymentにはReplicaSetが要る」と気づいてReplicaSetを作り、ReplicaSetの見張り役が「Podが2個要る」と気づいてPodを2個作ります。この時点のPodには、まだNodeが書かれていません。
4. SchedulerがNodeを決める。 Nodeが未定のPodを見つけ、条件に合うNodeを1つ選んで、Podの nodeName に書き込みます。運ぶのではなく、台帳に「置き場所」を書くだけです。
5. kubeletがランタイムに頼む。 各Nodeのkubeletは、自分の名前が書かれたPodを見つけると、containerdなどのコンテナランタイムに、イメージの取得とコンテナの起動を頼みます。
6. kubeletが報告する。 起動できたか、Readyか、何回再起動したかを、kubeletがAPI Serverへ書き戻します。あなたが kubectl get pod で見ている STATUS は、この報告です。

イベントで6ステップを追う

ここから手を動かします。昨日と同じく、まずContextを確かめて lab を作ってください。

kubectl config current-context      # kind-xxx / minikube / docker-desktop などが出ればOK
kubectl create namespace lab

次のDeploymentを deploy.yaml として保存します。第1章の create deployment と同じ内容を、今回はYAMLで書きます。

# deploy.yaml ― 「nginxのPodを2個、いつもあるように」という望ましい状態
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  labels:
    app.kubernetes.io/name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: api      # このラベルのPodを「自分の子」とみなす
  template:
    metadata:
      labels:
        app.kubernetes.io/name: api    # selectorと一致していないと適用できない
    spec:
      containers:
        - name: api
          image: nginx:stable
          ports:
            - containerPort: 80
          resources:
            requests:                  # Schedulerが置き場所を選ぶときの「必要量」
              cpu: 100m
              memory: 64Mi

kubectl -n lab apply -f deploy.yaml

# 親子3世代を一度に見る
kubectl -n lab get deploy,rs,pod -o wide

# 出来事を古い順に並べる（新しいものが下に来る）
kubectl -n lab get events --sort-by=.lastTimestamp

イベントは、次のような順番で並ぶはずです（名前やNodeは環境によって違います）。

# 出力の例（列を一部省略）
REASON              OBJECT                      MESSAGE
ScalingReplicaSet   deployment/api              Scaled up replica set api-7d9c6b5f4 to 2
SuccessfulCreate    replicaset/api-7d9c6b5f4    Created pod: api-7d9c6b5f4-x8k2q
SuccessfulCreate    replicaset/api-7d9c6b5f4    Created pod: api-7d9c6b5f4-m4n7z
Scheduled           pod/api-7d9c6b5f4-x8k2q     Successfully assigned lab/api-7d9c6b5f4-x8k2q to kind-worker
Pulling             pod/api-7d9c6b5f4-x8k2q     Pulling image "nginx:stable"
Pulled              pod/api-7d9c6b5f4-x8k2q     Successfully pulled image "nginx:stable"
Created             pod/api-7d9c6b5f4-x8k2q     Created container api
Started             pod/api-7d9c6b5f4-x8k2q     Started container api

この1行1行に、担当者の名前を付けてみます。

障害のときは、この表のどこで行が途切れているかを見ます。Scheduled が出ていなければSchedulerの手前、Scheduled はあるのに Pulled がなければkubeletかレジストリ、という読み方です。第1章の演習1で「どこまでは成功したか」と書いたのは、このことでした。

API Serverは唯一の窓口

kubectlも、Controllerも、kubeletも、etcdに直接書きには行きません。全員がAPI Serverを通ります。そのおかげで、認証、権限、検証、監査ログを1か所でそろえられます。API Serverの中では、1つのリクエストが次の関所を順番に通ります。

図2-2: API Serverの関所。どこで止まったかは、kubectlのエラー文でほぼ特定できる。

関所の順番を知っていると、エラー文を見ただけで切り分けが進みます。Unauthorized ならkubeconfigや証明書の期限、Forbidden なら権限、error validating ならYAMLの項目名です。Admissionは、クラスター管理者が「このラベルがないPodは拒否する」「このレジストリ以外のイメージは拒否する」といったルールを差し込む場所で、ここで止まると、YAMLは正しいのに適用できない、という症状になります。

# 自分がその操作をしてよいか、適用する前に聞ける（②認可の確認）
kubectl auth can-i create deployments -n lab
kubectl auth can-i delete nodes

# YAMLの項目名が正しいか、クラスターに何も作らずに確かめる（④検証の確認）
kubectl -n lab apply --dry-run=server -f deploy.yaml

--dry-run=server は、昨日使った --dry-run=client と違って、API Serverまでリクエストを送り、関所をすべて通してから「保存だけしない」で返してくれます。Admissionで拒否されるかどうかも、これで事前にわかります。

etcdは台帳

etcdは、Kubernetesのすべての状態を保存する分散キーバリューストアです。DeploymentやServiceの定義だけでなく、Secretの値、Podにどのnodeが割り当てられたか、Controllerが管理している途中経過まで、全部ここにあります。

第1章で「Kubernetesは状態を頼む仕組み」と書きましたが、その状態が置かれている場所がetcdです。Nodeの上でコンテナが動いていても、etcdが失われると、「何個あるべきだったか」「どのServiceがどのPodを指していたか」を誰も思い出せなくなり、クラスターとして組み直せなくなります。

SchedulerはNodeを選ぶだけ

Podが作られた直後は、まだどのNodeにも置かれていません。Schedulerは、この「Node未定」のPodを見つけると、全Nodeを2段階でふるいにかけます。

図2-3: Schedulerはまず「置けないNode」を除外し、残りを採点して1つ選ぶ。

フィルタで見るのは、requests に対するCPUとメモリの空き、NodeのTaint（「特別な許可がないPodは乗せない」という印）とPodのToleration（その許可）、Nodeを指名するAffinity、ホストのポート競合、ボリュームの制約などです。ここで注意してほしいのは、Schedulerが見るのは「実際の使用量」ではなく「requestsの合計」だということです。Nodeのメモリが実際には空いていても、すでに置かれたPodのrequestsの合計で埋まっていれば、置けません。

だから Pending のときに「Nodeを増やす」の前に、まず requests の値が妥当かを見ます。開発者が「念のため」と大きめに書いたrequestsが、クラスター全体の空きを食いつぶしていることはよくあります。

# 各NodeのCPU・メモリの「requestsの合計」と「上限」を見る（Allocated resources の欄）
kubectl describe node <Node名>

# NodeにTaintが付いているか
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Controllerは差を埋め続ける

第1章で「見張り役」と呼んでいたのがControllerです。Deployment、ReplicaSet、Node、Jobなど、リソースの種類ごとに専用の見張り役がいて、Controller Managerという1つのプロセスの中でまとめて動いています。それぞれの仕事は同じ形です。台帳の「望ましい状態」と「観測した状態」を比べて、差があれば1つ埋める。これをずっと繰り返す。

図2-4: 親子関係と制御ループ。Podが1個消えると、差の1個だけを作り直す。

親子関係は、台帳の上で確かめられます。子のリソースには metadata.ownerReferences に親の名前が書かれていて、ReplicaSetはこれと selector を使って「自分の子」を数えます。

# ReplicaSetの親はDeployment、Podの親はReplicaSet
kubectl -n lab get rs,pod -o custom-columns=KIND:.kind,NAME:.metadata.name,OWNER:.metadata.ownerReferences[0].kind,OWNER_NAME:.metadata.ownerReferences[0].name

# 出力の例
KIND         NAME                    OWNER        OWNER_NAME
ReplicaSet   api-7d9c6b5f4           Deployment   api
Pod          api-7d9c6b5f4-x8k2q     ReplicaSet   api-7d9c6b5f4
Pod          api-7d9c6b5f4-m4n7z     ReplicaSet   api-7d9c6b5f4

Deploymentを更新すると、Deployment Controllerは既存のReplicaSetを書き換えるのではなく、新しいReplicaSetをもう1つ作り、古い方の数を減らしながら新しい方の数を増やします。これが「ローリングアップデート」で、古いReplicaSetは数が0になっても残るので、戻せます。使い方は明日の第3章で扱います。

kubeletとコンテナランタイム

kubeletは各Nodeで動くエージェントです。API Serverの台帳を見て、自分のNode名が書かれたPodを見つけると、CRI（Container Runtime Interface）という共通の取り決めを通して、containerdなどのコンテナランタイムに頼みます。イメージを取得して、コンテナを作って、起動して、止めて、ログを管理するのはランタイムの仕事です。

切り分けの観点では、ここが大事です。Podに Scheduled のイベントがあるのに起動しないなら、API ServerやSchedulerの話はもう終わっていて、Node側の話に入っています。 見る場所は、kubelet、コンテナランタイム、レジストリへの通信、Nodeのディスク容量、CNI（ネットワーク）、CSI（ストレージ）です。

最後の行は、Kubernetesの問題に見えて実際はコンテナの中身の問題、という典型です。kubeletはコンテナを止めるときにまずSIGTERMを送り、既定で30秒待ってから強制終了します。アプリがシェル経由で起動されていてシグナルを受け取れないと、毎回30秒待たされ、ローリングアップデートがやたら遅くなります。Dockerfileの書き方を直せば解決する話で、Kubernetesの設定をいじっても直りません。

Manifestを「構造」として読む

ここまでの部品がやり取りしているのは、全部APIオブジェクトです。YAMLを「設定ファイル」ではなく、台帳の1ページとして読み直してみます。どのリソースも、次の4〜5つの区画でできています。

spec はあなたの注文、status は現場からの報告です。status をYAMLに手で書いて apply しても、Controllerが報告で上書きするので意味がありません。逆に、kubectl get -o yaml で取り出したものには status も、Kubernetesが補った既定値も入っているので、それをそのままGitに戻すとファイルが膨らみ、差分が読めなくなります。

# 台帳の実体を読む（statusと既定値が足されている。手元のYAMLとは別物）
kubectl -n lab get deployment api -o yaml

# 手元のYAMLと台帳の差だけを見る（Gitのdiffと同じ感覚）
kubectl -n lab diff -f deploy.yaml

# どの項目を誰が書いたかを見る（通常は省略されている）
kubectl -n lab get deployment api -o yaml --show-managed-fields | less

status の中でも conditions は読む価値があります。Deploymentなら Available（必要数がReadyか）と Progressing（更新が進んでいるか）の2つがあり、「applyは成功したのに使えない」ときの最初の手がかりになります。

kubectl -n lab get deployment api -o jsonpath='{range .status.conditions[*]}{.type}={.status} ({.reason}){"\n"}{end}'

Namespace・Label・Annotationの使い分け

わざと壊す演習

ここからは、さっきの deploy.yaml を使って、層ごとに1つずつ壊します。壊すたびに「どの部品の仕事で止まったか」を言ってから直してください。

# requests を cpu 64コア に変える（学習環境にそんなNodeはない）
kubectl -n lab set resources deployment/api --requests=cpu=64
kubectl -n lab get pods -w     # 新しいPodが Pending のまま止まる（Ctrl+Cで終了）

kubectl -n lab describe pod <Pending の Pod名>    # 一番下の Events

# Events の例
Warning  FailedScheduling  default-scheduler  0/1 nodes are available: 1 Insufficient cpu.
                                              preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.

kubectl -n lab rollout undo deployment/api
kubectl -n lab get pods            # Pending だったPodが消え、2個に戻る

kubectl -n lab set image deployment/api api=nginx:this-tag-does-not-exist
kubectl -n lab rollout status deployment/api --timeout=60s

kubectl -n lab get rs                                   # ReplicaSetが2つになっている
kubectl -n lab get events --sort-by=.lastTimestamp | tail -8

kubectl -n lab rollout history deployment/api          # 戻る前に、履歴を見ておく
kubectl -n lab rollout undo deployment/api
kubectl -n lab rollout status deployment/api            # successfully rolled out

POD=$(kubectl -n lab get pod -l app.kubernetes.io/name=api -o jsonpath='{.items[0].metadata.name}')
kubectl -n lab label pod "$POD" app.kubernetes.io/name=rogue --overwrite
kubectl -n lab get pods --show-labels

kubectl -n lab get pod -o custom-columns=NAME:.metadata.name,OWNER:.metadata.ownerReferences[0].kind,LABEL:.metadata.labels.app\.kubernetes\.io/name

kubectl -n lab delete pod "$POD"   # 親のいないPodは、消しても誰も作り直さない
kubectl -n lab get pods            # 2個に戻る

壊したら、メモを残す

第1章と同じ6項目です。今日は「原因」の欄に、止まった層（部品の名前）を必ず入れてください。

# 演習メモの例
日時/Context : 2026-10-21 21:30 / kind-kind（Namespace: lab）
症状         : set image 後、rollout status が60秒で timed out
最初に見たもの: get events → 新Podに Scheduled あり、その後 Failed（kubelet）
原因         : イメージタグが存在しない。止まった層は kubelet／レジストリ
修正         : rollout undo で前の ReplicaSet に戻した
再発防止     : タグは --dry-run=server では検出できない。CIでイメージの存在を確認する

どの層で止まっているか、の早見表

今日の内容を、障害のときにすぐ引ける形にまとめます。上から順に見ていけば、層を飛ばして「とりあえず再起動」をせずに済みます。

Control Planeが止まると、何が止まるか

「API Serverが落ちたらサービスが全部止まる」と思っている人が多いのですが、正確ではありません。図2-1で、kubeletはAPI Serverの台帳を読んで動いていました。台帳が読めなくなっても、kubeletは最後に読んだPodを維持し続けます。

だから「画面が見えているから正常」とは判断できません。逆に、Control Planeの障害中でも、慌ててNodeを再起動するとPodが戻ってこなくなります。マネージドKubernetesでは、Control PlaneのログやetcdにはあなたからはOSごと触れないので、クラウドのヘルスイベント、監査ログ、サポート窓口を使う前提で、障害対応の手順書を作ります。

# Control Planeの各部品の健康状態（権限がないと Forbidden になる環境もある）
kubectl get --raw='/readyz?verbose'

# Nodeの条件（Ready / MemoryPressure / DiskPressure など）
kubectl get nodes
kubectl describe node <Node名> | sed -n '/Conditions:/,/Addresses:/p'

片付け

kubectl delete namespace lab
kubectl get namespaces          # lab が消えたことを確認

今日もロードバランサーやディスクは作っていないので、これで終わりです。演習2のイメージタグ違いは、CIでイメージの存在を確認すれば防げる類のものです。明日の第3章では、更新とロールバックをDeploymentの機能として、もう少し丁寧に扱います。

まとめ

• 部品どうしは直接話さない。全員がAPI Serverの台帳を読み、自分の担当の差を埋めて、書き戻す
• applyの成功は「台帳に書けた」だけ。コンテナが動くのは、Controller → Scheduler → kubelet の後
• Eventsの1行ずつに担当者がいる。行が途切れた場所が、止まっている層
• Pending はSchedulerの層、ImagePullBackOff はNodeの層。古いPodが残っていれば利用者への影響はない
• Podを直接いじる前に、所有者（ownerReferences）を見る。台帳の外で変えた現実は、Controllerが差として扱う
• Control Planeが止まっても、動いているPodは動き続ける。止まるのは「変えること」と「読むこと」

公式資料

• Cluster Architecture: https://kubernetes.io/docs/concepts/architecture/
• Controllers: https://kubernetes.io/docs/concepts/architecture/controller/
• Kubernetes Scheduler: https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/
• Controlling Access to the Kubernetes API: https://kubernetes.io/docs/concepts/security/controlling-access/
• Operating etcd clusters: https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/

※本章の記述は2026年10月時点の公式ドキュメントに基づきます。イベントの文言、Schedulerのメッセージ、kubectl の出力形式は、Kubernetesのバージョンや学習環境によって少し異なることがあります。