kubectl基本操作とObservability｜CKAD第6回

新卒インフラエンジニア向け「Kubernetes 実践教科書① CKAD アプリケーション開発編」の第6回です。第5回で kind による軽量クラスタを立ち上げ、kubectl get nodes で初めて接続しました。今回は kubectl の基本操作を体系的に押さえ、ログ確認・コンテナ内デバッグ・リソース使用量の確認といった Observability（可観測性）と、API デプリケーション（非推奨化）の検知までを実機で習得します。ここは CKAD のドメイン D3（Application Observability and Maintenance）に対応する重要回です。

今ここマップ（全 19 回中の現在地）

現在地は第 2 部「Kubernetes 基礎」の第 6 回（第 2 部の最終回）です。次回からは模擬アプリ fanclub-api を Kubernetes に載せていきます。

• 第 1 部 コンテナと Docker（第 1〜4 回）
• 第 2 部 Kubernetes 基礎（第 5〜6 回）← 今ここ
• 第 3 部 アプリリソース（第 7〜11 回）
• 第 4 部 ワークロード戦略（第 12〜14 回）
• 第 5 部 セキュリティ基礎（第 15〜16 回）
• 第 6 部 パッケージ管理と HTTPS 公開（第 17〜19 回）

この回のゴール

• kubectl の基本コマンド（get / describe / logs / exec / apply / delete / diff）と出力形式を使いこなせる。
• ログ確認・コンテナ内デバッグ・イベント確認・リソース使用量（kubectl top）で状態を観測できる。
• API の非推奨化を検知する手段（api-versions / api-resources / convert）を説明できる。

kubectl の仕組み

kubectl は、操作内容を kube-apiserver への API リクエストに変換して送るクライアントです。接続先・認証情報は kubeconfig（既定で ~/.kube/config）に書かれており、第5回で kind が kind-kind というコンテキストを自動設定しました。リクエストを受けた API Server は、クラスタの状態を etcd に読み書きします。つまり kubectl → API Server → etcd という一方向の流れで、すべての操作は API Server を必ず経由します。

まず接続できているかをバージョン表示で確認します。クライアント（kubectl）とサーバー（クラスタ）の双方が出れば接続成功です。

実行コマンド：

$ kubectl version

実行結果（例）：

Client Version: v1.35.6
Kustomize Version: v5.7.1
Server Version: v1.35.0

基本コマンドの型を身につける

kubectl の操作は「kubectl 動詞 リソース種別 名前 オプション」という型で覚えると整理しやすくなります。代表的な動詞は次のとおりです。

• get：リソースの一覧・概要を表示する。
• describe：1 つのリソースの詳細（イベント含む）を表示する。
• logs：コンテナの標準出力ログを表示する。
• exec：稼働中コンテナ内でコマンドを実行する。
• apply：マニフェスト（YAML）を適用して宣言した状態にする。
• delete：リソースを削除する。
• diff：マニフェストを適用したら何が変わるかを事前に差分表示する。

以降の操作のため、学習用のサンプル Pod を 1 つ起動します。kubectl run は単一の Pod を手早く起動するコマンドです。--labels で後の絞り込み用にラベルを付けておきます。

実行コマンド：

$ kubectl run web --image=nginx:1.27-alpine --labels=app=web

起動を確認します。get は既定の表形式に加え、-o wide で Pod の IP やノードまで表示できます。

実行コマンド：

$ kubectl get pod web -o wide

実行結果（例）：

NAME   READY   STATUS    RESTARTS   AGE   IP            NODE                 NOMINATED NODE   READINESS GATES
web    1/1     Running   0          9s    10.244.82.7   kind-control-plane   <none>           <none>

Pod の IP（10.244.82.7）が第5回で設定した podSubnet（10.244.0.0/16）の範囲から払い出されていることが分かります。

出力形式（-o yaml / json / wide / jsonpath）

-o yaml / -o json はリソースの全定義を出力し、調査やマニフェストの雛形取りに使います。-o jsonpath は特定のフィールドだけを抜き出すのに便利です。たとえば Pod の IP やイメージ名だけを取り出せます。

実行コマンド：

$ kubectl get pod web -o jsonpath='{.status.podIP}'
$ kubectl get pod web -o jsonpath='{.spec.containers[0].image}'

実行結果（例）：

10.244.82.7
nginx:1.27-alpine

alias k=kubectl を設定する

kubectl は何度も打つため、k という別名を付けておくと操作が速くなります。CKAD 試験でも定番のテクニックです。現在のシェルと、次回以降のログインの両方で有効にするため、~/.bashrc にも追記します。

実行コマンド：

$ echo 'alias k=kubectl' >> ~/.bashrc
$ source ~/.bashrc
$ k get pod web

以降は kubectl と k のどちらでも同じ操作ができます（本記事では分かりやすさのため kubectl と表記します）。

kubectl explain でリソース定義を調べる

マニフェストを書くとき、どのフィールドが使えるかは kubectl explain で調べられます。試験中もオンラインのドキュメントを引かずに確認できるため重宝します。. でフィールドを掘り下げ、--recursive で配下を一覧できます。

実行コマンド：

$ kubectl explain pod.spec.containers

実行結果（例・抜粋）：

KIND:       Pod
VERSION:    v1

FIELD: containers <[]Container>

DESCRIPTION:
    List of containers belonging to the pod. Containers cannot currently be
    ...

Observability 実践

アプリの状態を観測する基本動作を押さえます。これらは第1部の Docker（logs / exec）と発想が同じで、対象が Pod になっただけです。

ログとイベントを確認する

コンテナのログは kubectl logs で確認します。コンテナが再起動した場合、1 つ前の起動時のログは --previous（-p）で取得でき、CrashLoopBackOff の原因調査で重要になります。なお --previous は再起動が起きていない Pod（RESTARTS が 0）では「previous terminated container … not found」とエラーになるため、再起動が発生してから使うコマンドだと押さえてください（次の web はまだ再起動していません）。

実行コマンド：

$ kubectl logs web
$ kubectl logs web --previous

リソースの詳細とイベントは kubectl describe で確認します。スケジュール・イメージ取得・起動の経過や失敗理由は、出力末尾の Events 欄に出ます。クラスタ全体のイベントは kubectl get events でも一覧できます。

実行コマンド：

$ kubectl describe pod web
$ kubectl get events --sort-by=.lastTimestamp

実行結果（get events の例・抜粋）：

Normal   Scheduled   pod/web   Successfully assigned default/web to kind-control-plane
Normal   Pulling     pod/web   Pulling image "nginx:1.27-alpine"
Normal   Pulled      pod/web   Successfully pulled image "nginx:1.27-alpine"
Normal   Created     pod/web   Container created
Normal   Started     pod/web   Container started

コンテナ内に入って調べる

コンテナ内でコマンドを実行するには kubectl exec を使います。1 回だけコマンドを流すなら -- の後ろにコマンドを書き、対話的に操作するなら -it でシェルを起動します（Alpine 系は sh）。

実行コマンド：

$ kubectl exec web -- nginx -v
$ kubectl exec -it web -- sh

実行結果（例）：

nginx version: nginx/1.27.5

リソース使用量を見る（metrics-server と kubectl top）

ノードや Pod の CPU・メモリ使用量は kubectl top で確認します。ただしこの値を提供する metrics-server は kind に同梱されていないため、未導入のままだと kubectl top nodes は error: Metrics API not available になります。まず metrics-server を導入します。kind ではノードの証明書検証を省くため --kubelet-insecure-tls を付与する必要があります。データの流れと metrics-server の役割を次の図に示します。

実行コマンド：

$ kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.8.1/components.yaml
$ kubectl patch -n kube-system deployment metrics-server --type=json \
    -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'
$ kubectl rollout status -n kube-system deployment/metrics-server

metrics-server が起動し、メトリクスを収集し始める（数十秒）と kubectl top が値を返します。

実行コマンド：

$ kubectl top nodes
$ kubectl top pods -n kube-system

実行結果（top nodes の例。top pods -n kube-system も同様に Pod ごとの CPU・メモリが表示されます）：

NAME                 CPU(cores)   CPU(%)   MEMORY(bytes)   MEMORY(%)
kind-control-plane   233m         11%      1000Mi          17%

API デプリケーション（非推奨化）の検知

Kubernetes は版が上がるたびに API を進化させ、古い API バージョンは非推奨（deprecated）になり、やがて削除されます。削除された API を使ったマニフェストはある日突然 apply できなくなります。これを事前に検知・対処する手段が D3 で問われます。

クラスタが現在提供している API バージョンとリソース種別は、kubectl api-versions と kubectl api-resources で確認できます。

実行コマンド：

$ kubectl api-versions
$ kubectl api-resources

実行結果（api-resources の例・抜粋）：

NAME                SHORTNAMES   APIVERSION   NAMESPACED   KIND
configmaps          cm           v1           true         ConfigMap
endpoints           ep           v1           true         Endpoints
events              ev           v1           true         Event
...

手元のマニフェストを新しい API バージョンへ変換するには kubectl convert を使います。これは kubectl 本体には含まれない別バイナリで、公式配布元から追加で導入します。第5回の kubectl と同じく、ダウンロードは一般ユーザーで /tmp へ、配置は sudo install -m 0755 で /usr/local/bin に行います（root 所有・755・PATH 上）。末尾の kubectl convert は古い API バージョンのマニフェスト（old-deployment.yaml）がある場合の使用例です。

実行コマンド：

$ curl -fsSL -o /tmp/kubectl-convert https://dl.k8s.io/release/v1.35.6/bin/linux/amd64/kubectl-convert
$ sudo install -m 0755 /tmp/kubectl-convert /usr/local/bin/kubectl-convert
$ kubectl convert -f old-deployment.yaml --output-version apps/v1

このほか、クラスタ内で使われている非推奨 API を洗い出す kubectl deprecations というプラグイン（krew で導入）もあります。アップグレード前のチェックに有用ですが、本シリーズでは名前の紹介にとどめます。

ラベルセレクタで絞り込む

リソースにはラベルを付けられ、-l（--selector）で絞り込めます。Service が Pod を選ぶ仕組み（第8回）や、デプロイ戦略（第13回）でも使う基本概念です。先ほど app=web を付けた Pod を絞り込んでみます。

実行コマンド：

$ kubectl get pods -l app=web

CKAD 高速操作：YAML 雛形を生成する

CKAD は時間との勝負です。マニフェストを一から書くのではなく、--dry-run=client -o yaml で雛形を生成し、必要箇所だけ編集すると速く正確に書けます。--dry-run=client は「クラスタには送らず手元で組み立てる」指定です。次のコマンドはリダイレクト（>）でカレントディレクトリ（developer のホーム）に demo.yaml を作成します（一般ユーザー所有・root 不要）。

実行コマンド：

$ kubectl run demo --image=nginx:1.27-alpine --dry-run=client -o yaml > demo.yaml

生成される YAML（例）：

apiVersion: v1
kind: Pod
metadata:
  labels:
    run: demo
  name: demo
spec:
  containers:
  - image: nginx:1.27-alpine
    name: demo
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always
status: {}

この雛形を編集して kubectl apply -f demo.yaml で適用すれば、宣言的な管理に乗せられます。適用前に kubectl diff -f demo.yaml で変更点を確認するのも安全です。

後片付け（delete）

学習用に作ったリソースは kubectl delete で削除します。基本動詞の最後として、サンプル Pod を片付けておきます（次回はクリーンな状態から自社アプリを載せます）。

実行コマンド：

$ kubectl delete pod web

実行結果（例）：

pod "web" deleted from default namespace

やってみよう

1. kubectl run web --image=nginx:1.27-alpine --labels=app=web でサンプル Pod を起動し、kubectl get pod web -o wide で IP とノードを確認する。
2. kubectl logs web でログ、kubectl describe pod web で Events を確認し、kubectl exec web -- nginx -v でコンテナ内のバージョンを調べる。
3. metrics-server を導入（--kubelet-insecure-tls を付与）し、kubectl top nodes / kubectl top pods -n kube-system で使用量を確認する。
4. kubectl api-resources でリソース種別と API バージョンを確認する。
5. kubectl run demo --image=nginx:1.27-alpine --dry-run=client -o yaml で YAML 雛形を生成する。

理解度チェック

次の各文が正しいか（○）誤りか（×）を判断してください。解答は下にまとめています。

1. kubectl の接続先・認証情報は kubeconfig（既定で ~/.kube/config）に保存される。
2. kubectl logs --previous は、1 つ前の起動時（再起動前）のコンテナログを表示する。
3. kubectl top nodes は metrics-server が無くても常に値を返す。
4. kubectl api-resources はクラスタが提供するリソース種別と API バージョンを一覧する。
5. kubectl convert は kubectl 本体に同梱されており、追加導入は不要である。
6. --dry-run=client -o yaml は、クラスタに送らずにマニフェスト雛形を生成する。
7. -o jsonpath を使うと、リソースの特定フィールドだけを抜き出せる。

解答

• 1. ○：kubeconfig に接続先・認証・コンテキストが記録される。
• 2. ○：CrashLoopBackOff の原因調査では --previous が要点。
• 3. ×：metrics-server が未導入だと Metrics API not available になる。
• 4. ○：api-resources で種別・短縮名・API バージョン・名前空間有無が分かる。
• 5. ×：kubectl convert は別バイナリで、追加導入が必要。
• 6. ○：手元で雛形を生成し、編集して apply する高速化テクニック。
• 7. ○：-o jsonpath で必要なフィールドだけを取り出せる。

まとめ

本記事では、kubectl の仕組み（kubeconfig → API Server → etcd）を起点に、基本コマンドと出力形式、explain によるリソース仕様の確認、ログ・イベント・コンテナ内デバッグ・kubectl top による Observability、そして API 非推奨化の検知（api-versions / api-resources / convert）までを実機で押さえました。--dry-run=client -o yaml による雛形生成は、これ以降すべての回で役立つ高速化の型です。これで Kubernetes を操作・観測する基礎が整いました。

次回予告

次回（第7回）からは第3部「アプリリソース」に入ります。第4回でレジストリに push した自社アプリ fanclub-backend を、いよいよ Pod として Kubernetes に初投入します。Pod 定義 YAML の構造、Init Container・Sidecar などのマルチコンテナパターン、そして JVM ヒープと Pod のメモリ制限の整合（OOMKilled の再現）までを実機で扱います。

シリーズ一覧

第1部：コンテナと Docker

• 第1回 コンテナ技術概念 + Docker 環境準備
• 第2回 Docker 基本操作
• 第3回 Dockerfile + マルチステージ + JDK 25 / Payara Micro イメージビルド
• 第4回 コンテナレジストリ + イメージタグ戦略 + Trivy スキャン

第2部：Kubernetes 基礎

• 第5回 Kubernetes の全体像 + kind で軽量 K8s
• 第6回 kubectl 基本操作 + Observability・Debug ← 今ここ

第3部：アプリリソース

• 第7回 Pod + Multi-container パターン
• 第8回 Service とネットワーキング
• 第9回 ストレージ（PVC + StatefulSet）+ PostgreSQL DB 追加
• 第10回 ConfigMap + Secret + ServiceAccount 基礎
• 第11回 Job + CronJob + DaemonSet

第4部：ワークロード戦略

• 第12回 Deployment + 3 Probe + Rolling Update + Probe デバッグ実践
• 第13回 Deployment 戦略補完（Blue/Green + Canary + Recreate）
• 第14回 ResourceQuota + LimitRange + Multi-tenant Namespace

第5部：セキュリティ基礎

• 第15回 RBAC + SecurityContext + Admission Controller 概念 + CRD 利用
• 第16回 NetworkPolicy 基礎

第6部：パッケージ管理 + HTTPS 公開

• 第17回 Helm v4 + chart 化 + フルサイクル
• 第18回 Gateway API + HTTPRoute + Ingress 対比 + Traefik + cert-manager
• 第19回 fanclub-api 全機構連携の実技総ざらい総合演習 + 第1巻完走宣言 ★