CTS-KB
インフラ📚 シリーズ 4/15

kubectl applyと宣言的管理：Kubernetesマニフェストの読み方

⏱ 約 3 分で読めます
#Kubernetes#GKE#kubectl#YAML#宣言的管理
Kubernetesクラスタの仕組み：Control plane・data plane・etcdPod・ReplicaSet・Deployment：Webアプリを継続稼働させる仕組み

Kubernetes運用の中心は、「このコマンドでコンテナを1個起動する」という命令ではなく、こうなっていてほしい状態をマニフェストとして宣言することです。

kubectl applyから調整ループまで

マニフェストの共通構造

ほとんどのKubernetesオブジェクトは、次の4項目を持ちます。

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-config
  namespace: YOUR_NAMESPACE
data:
  APP_MODE: production
フィールド意味
apiVersion使用するKubernetes APIの版
kindオブジェクトの種類
metadata名前、Namespace、ラベル、注釈
spec または種類固有フィールド望ましい状態

status は通常、コントローラーが現在状態を書き込む領域です。人がマニフェストへ固定するものではありません。

desired stateとcurrent state

たとえば replicas: 3 は「Podを3個作る命令を一度だけ実行する」という意味ではありません。

  • desired state：3個で動いてほしい
  • current state：現在は2個しか動いていない
  • controller：不足する1個を作る

その後1個が故障しても、差が再び検出され、代わりが作られます。この継続的な調整がKubernetesの自己修復の基礎です。

学習用マニフェスト

example.yaml にConfigMapとDeploymentを記述します。

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-config
  namespace: YOUR_NAMESPACE
data:
  MESSAGE: hello-kubernetes
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-web
  namespace: YOUR_NAMESPACE
spec:
  replicas: 2
  selector:
    matchLabels:
      app: example-web
  template:
    metadata:
      labels:
        app: example-web
    spec:
      containers:
        - name: web
          image: nginx:alpine
          env:
            - name: MESSAGE
              valueFrom:
                configMapKeyRef:
                  name: example-config
                  key: MESSAGE
          ports:
            - containerPort: 80

metadata.namespace を明示すると、誤ったNamespaceへの適用を減らせます。selector.matchLabels とPodテンプレートの labels は一致させます。

変更前に差分を見る

kubectl apply --dry-run=server -f example.yaml
kubectl diff -f example.yaml
kubectl apply -f example.yaml
  • --dry-run=server：API server側の検証を行うが保存しない
  • diff：現在状態とファイルの差を見る
  • apply：宣言をAPIへ反映する

kubectl diff は差分があると終了コード1を返す仕様なので、シェル上でエラーに見えても内容を確認します。

反映後の確認

kubectl get configmap,deployment,pods -n YOUR_NAMESPACE
kubectl describe deployment example-web -n YOUR_NAMESPACE
kubectl rollout status deployment/example-web -n YOUR_NAMESPACE
kubectl get deployment example-web -n YOUR_NAMESPACE -o yaml

適用成功の表示だけで完了とせず、利用可能レプリカ数、Pod状態、イベントまで確認します。

変更と削除もファイルを基準にする

replicas やイメージタグをファイルで変更し、再び diff と apply を実行します。一時的な調査以外では、クラスタ上だけを kubectl edit で変更し、元ファイルへ反映し忘れる運用を避けます。

学習リソースを削除する場合は、対象ファイルを明示します。

kubectl delete -f example.yaml

本番で kubectl delete namespace のような広範囲の削除を安易に実行しません。削除前に対象、Namespace、依存する永続ボリュームを確認します。

命令的コマンドは不要なのか

不要ではありません。kubectl create namespace、kubectl scale、kubectl rollout restart などは、学習、緊急対応、使い捨てリソースに便利です。ただし長期運用する構成はマニフェストへ戻し、再現できる状態にします。

本シリーズはCI/CDを使わず手で適用しますが、手作業でも宣言ファイルを正本にすることはできます。実行の自動化と、構成の宣言性は別の話です。

よくある失敗

  • contextまたはNamespaceを確認せず適用する
  • selector と labels が一致していない
  • latest タグを使い、どのイメージが動くか追跡できない
  • 実際のパスワードをSecretマニフェストへ書いてコミットする
  • apply の成功だけを見てPodやイベントを確認しない

次回

Deploymentの内部でどのようにPodとReplicaSetが連携するかを、Pod・ReplicaSet・Deploymentで掘り下げます。

参考資料