Kubernetes

冒頭まとめ kubectl applyやkubectl getが、次のエラーで止まることがあります。 Error from server (NotFound): the server could not find the requested resource まず、接続先のクラスターが、指定した種類とバージョンのAPIを提供しているかを確認します。APIは、PodやDeploymentなどを作成・取得するための窓口です。マニフェストのapiVersionとkindを控え、現在の接続先とAPI一覧を調べてください。 kubectl config current-context kubectl api-versions kubectl api-resources --cached=false カスタムリソースなら、その種類を追加する定義であるCRD（CustomResourceDefinition）が必要です。CRDを先に適用して登録を待ち、その後にカスタムリソースを適用します。組み込みリソースなら、apiVersionの誤りや、クラスターの更新で提供されなくなった旧APIを確認します。 ただし、この文言だけでCRD不足と断定はできません。404は要求先が見つからなかった応答で、接続先や途中のプロキシが誤っている場合も調査対象になります。 3つのエラー文言の違い 似た状況で次の文言も出ますが、発生する処理は異なります。 文言 示していること the server could not find the requested resource 要求先から404相当の応答を受けた。要求したAPIのパスと応答元を確認する no matches for kind "MyApp" in version "myorg.example.com/v1" kubectl側で、指定したkindとAPIバージョンを対応するAPIへ変換できなかった the server doesn't have a resource type "myapps" kubectl側で、指定したリソース名に対応するAPIを見つけられなかった 最初の文言は、KubernetesのNewGenericServerResponse()がHTTP 404に対応して組み立てるメッセージです。要求した操作、リソースの種類、名前が分かる場合は、末尾に(get deployments.apps my-app)などが付きます。 すべての404がこの固定文言になるわけではありません。 client-goの応答処理は、Kubernetesの形式で返されたエラー情報を利用し、読み取れない応答には汎用的なエラーを作ります。そのため、固定文言だけで、リソースの種類がないのか、個別の名前がないのか、別のサーバーが応答しているのかを決めないでください。 残りの2つは、RESTMapperのエラー定義とkubectlの表示処理に由来します。RESTMapperは、種類やリソース名をAPIの宛先へ対応付ける仕組みです。対象オブジェクトの操作へ進む前に失敗しますが、対応付けに使うAPI一覧をサーバーから取得することがあります。接続を一度も試していないという意味ではありません。 接続先とAPI一覧を確認する 同じマニフェストでも、開発用クラスターにはCRDがあり、本番用にはない場合があります。最初に現在のcontext（接続先の設定）を確認します。 kubectl config current-context kubectl config get-contexts 接続先が正しければ、apiVersionとkindを照合します。たとえばapiVersion: apps/v1、kind: Deploymentなら、次を実行します。 ...

冒頭まとめ kubectl get podsなどを実行したとき、次のエラーが出ることがあります。 Unable to connect to the server: dial tcp: lookup api.example.com: no such host The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port? どちらもkubectlからKubernetes APIサーバーへ接続できていません。ただし、直す場所は後半の文言によって異なります。 後半の文言 最初に疑う場所 connection refused APIサーバーの停止、ホスト、ポート no such host DNS、VPN、kubeconfig内のホスト名 i/o timeout、TLS handshake timeout 経路、VPN、ファイアウォール、負荷 x509:、tls: CA証明書、接続先名、証明書の期限 no configuration has been provided kubeconfigの有無と読み込み元 最初に、kubectlが選んでいるcontextとAPIサーバーのURLを確認してください。 kubectl config current-context kubectl config view --minify kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}{"\n"}' 想定外のクラスターが表示された場合は、ネットワークを調べる前にkubeconfigの読み込み元を直します。 ...

冒頭まとめ KubernetesでPodがPendingのままになり、kubectl describe podのEventsに次のような警告が出ることがあります。 Warning FailedScheduling default-scheduler 0/3 nodes are available: 1 Insufficient cpu, 2 node(s) had taints that the pod didn't tolerate. FailedSchedulingは、kube-schedulerがPodを配置できるノードを見つけられなかったことを示すイベントです。エラー名だけでは原因を判断できません。0/3 nodes are available:の後ろにある理由を、最後まで確認する必要があります。 最初に次のコマンドを実行してください。 kubectl describe pod <pod-name> -n <namespace> kubectl get events -n <namespace> \ --field-selector reason=FailedScheduling \ --sort-by=.metadata.creationTimestamp 理由がInsufficient cpuならCPUの要求量、didn't match Pod's node affinity/selectorならラベルと配置条件、had taints that the pod didn't tolerateならTaintとTolerationを調べます。複数の理由が並んでいる場合は、1つ直しただけでは配置できないことがあります。 FailedSchedulingとは FailedSchedulingはPodの状態ではなく、スケジューラーが記録するイベントのReasonです。Podの状態はPendingのままで、PodScheduled条件はFalseになります。 kube-schedulerは、まだ配置先が決まっていないPodを監視し、次のような条件で候補ノードを絞り込みます。 Podが要求するCPUやメモリを確保できるか nodeSelectorやNode Affinityに一致するか ノードのTaintをPodが許容しているか 使用するボリュームの配置条件を満たすか すべてのノードがいずれかの条件で候補から外れると、配置に失敗してFailedSchedulingが記録されます。この仕組みはKubernetes Schedulerの公式ドキュメントで確認できます。 同じPendingでも、すでに配置先ノードが決まり、イメージ取得やコンテナ作成を待っている場合はスケジューラーの問題ではありません。FailedSchedulingが出ている場合は、Podを起動する処理より前の「配置先を決める段階」で止まっています。 0/N nodes are availableの読み方 イベントは、次の形式で表示されます。 ...

この記事にはアフィリエイト広告が含まれています。 冒頭まとめ Kubernetesのエラーを検索して1件ずつ直しているのに、翌日は別のエラーで止まる。この繰り返しから抜けるには、覚える順序を変える必要があります。 Kubernetesのエラーの多くは、4つの境界のどこかで起きています。宣言した状態と実際の状態の境界、コントロールプレーンとノードの境界、Podの内と外の境界、そしてPodの寿命とデータの寿命の境界です。エラー文やイベントはこの境界のどれで止まったかを示していますが、境界の存在を知らないと文言が読めません。 Dockerとの最大の違いはここにあります。Dockerでは実行した命令がそのまま結果になりますが、Kubernetesでは「こうあってほしい」という宣言を出し、それを実現しようとする過程が延々と続きます。したがってエラーは、失敗した瞬間ではなく、実現できないまま繰り返している状態として現れます。 学ぶ順序は、Podとコンテナ、Deploymentと宣言、Serviceとネットワーク、設定とデータ、スケジューリングとリソース、ログとトラブルシューティングの6段階です。各段階には「次へ進む目安」を置きました。飛ばした段階は、後の段階のエラーとして別の顔で現れます。 個別に直すだけでは理解しにくい理由 検索で見つかる対処は、多くの場合その環境で有効だった手順です。なぜ有効だったかは書かれていないことがあります。 たとえば、Podが起動しないときに kubectl delete pod を実行したら直った、という手順があります。Deploymentの管理下にあるPodは削除すると作り直されるので、一時的な不具合であれば確かに解消します。しかし原因がマニフェストの側にあれば、作り直されたPodも同じ理由で止まります。Podが誰に管理されているかを知らないと、この区別ができません。 同じことがネットワークでも起きます。Serviceの port と targetPort を同じ値に揃えたら繋がった、という手順は、どちらがService側でどちらがコンテナ側かを知らなければ再現できません。 エラー文とイベントも同じです。Kubernetesの表示は、どの部品が判断したのかを示しています。スケジューラが置き場所を決められないのか、kubeletがイメージを取得できないのか、コンテナの中のプロセスが落ちているのかで、直す場所が変わります。この区別は、次に説明する全体像を知っていれば読み取れます。 最初に理解するべきKubernetesの全体像 先に部品の関係を押さえます。ここを飛ばすと、後のすべての段階で判断がぶれます。 公式ドキュメントによれば、Kubernetesクラスターはコントロールプレーンと1つ以上のワーカーノードで構成されます。コントロールプレーン側には、KubernetesのHTTP APIを公開する中核サーバーである kube-apiserver、APIサーバーの全データを保持するキーバリューストアの etcd、まだノードに割り当てられていないPodを探して適切なノードへ割り当てる kube-scheduler、APIの振る舞いを実装するコントローラーを動かす kube-controller-manager があります。ノード側には、Podとそのコンテナが動いていることを保証する kubelet、Serviceを実装するネットワーク規則を維持する kube-proxy、コンテナの実行を担うコンテナランタイムがあります（Cluster Architecture）。 この構造から、エラーの読み分けが決まります。kubectl はAPIサーバーへ要求を送るだけの道具です。マニフェストを適用した時点で成功と表示されても、それは「宣言が受け付けられた」という意味であり、動き出したという意味ではありません。実際に動くかどうかは、その後にスケジューラとkubeletが決めます。 したがってKubernetesの調査は、常に2段構えになります。宣言は正しく登録されたか。そしてその宣言を実現しようとした過程のどこで止まったか。前者は kubectl get で、後者は kubectl describe のイベント欄で確認します。 まずは手元の環境が動いているかを確認してください。 kubectl cluster-info kubectl get nodes ノードが Ready でなければ、この先のPodはどれも起動しません。この時点で次へ進んでも、以降のコマンドはすべて同じ理由で止まります。 学習ステップ1：Podとコンテナ 何を理解する段階か：Podが何の単位なのか、そしてコンテナとどう違うのかです。 なぜエラー解決に必要か：Kubernetesのエラーの大半はPod単位で現れます。Podの状態欄とコンテナの状態欄が別々にあることを知らないと、どちらの情報を読んでいるのか分からなくなります。 最低限覚える概念：公式ドキュメントによれば、PodはKubernetesで作成・管理できる最小のデプロイ単位で、1つ以上のコンテナのグループです。ストレージとネットワークの資源を共有し、コンテナをどう動かすかの仕様を持ちます。Podの中身は常に同じ場所に配置され、同時にスケジュールされ、共有された文脈で動きます（Pods）。 つまりPodは、複数のコンテナをまとめて1台の論理的なホストのように扱う入れ物です。同じPodの中のコンテナは同じネットワーク名前空間を共有するため、互いに localhost で通信できます。別のPodには届きません。 実際に試すコマンド： # Pod を一覧する kubectl get pods # 状態とノードと再起動回数まで表示する kubectl get pods -o wide # Pod の詳細とイベントを確認する（最も重要） kubectl describe pod <Pod名> # Pod 内のコンテナでコマンドを実行する kubectl exec -it <Pod名> -- sh # 複数コンテナがある場合はコンテナを指定する kubectl exec -it <Pod名> -c <コンテナ名> -- sh kubectl describe の出力は上半分が宣言された内容、下半分の Events が実現しようとした過程です。エラーの理由はほぼ常に下半分にあります。 ...

冒頭まとめ 同じ Pod を見ているのに、表示が ErrImagePull になったり ImagePullBackOff になったりする。この入れ替わりを原因の変化だと受け取ると、調べる方向を誤ります。 2つは原因の違いではありません。同じ失敗を、時間軸の別の地点から呼んだ名前です。kubelet は取得を求められると、まず待機の途中かどうかを確かめます。待機中なら取得を行わず ImagePullBackOff を返します。待機が明けていれば実際に取得を試み、失敗したときに ErrImagePull を返します。つまり前者は次の試行を待っている時間帯、後者は試して失敗した瞬間です。 したがって、どちらが表示されているかは原因を何も語りません。実際、この入れ替わりは利用者にとって分かりにくいと開発側も認めており、待機中の表示に前回の失敗理由を残す変更が v1.32 で入りました。 もう1つ、名前そのものの意味も押さえてください。ErrImagePull は取得失敗の総称ではありません。実装はレジストリに届かない場合と署名の検証に失敗した場合を先に切り分け、そのどちらでもない残り全部を ErrImagePull にしています。分類できなかった、という意味の名前です。 だから原因は名前ではなくメッセージ本文にあります。実際に取得を試みた瞬間に出る警告のイベントだけが、コンテナの実行基盤が返した文言をそのまま載せています。ここを取り逃がすと、手がかりが無くなります。 エラーの概要 kubectl describe pod のイベントは、失敗が続くと次の並びになります。 Normal Pulling 2m kubelet Pulling image "example.com/app:v1" Warning Failed 2m kubelet Failed to pull image "example.com/app:v1": rpc error: code = NotFound desc = ... Warning Failed 2m kubelet Error: ErrImagePull Normal BackOff 95s kubelet Back-off pulling image "example.com/app:v1" Warning Failed 95s kubelet Error: ImagePullBackOff Failed という理由が2行出ますが、意味が違います。1行目は実際に取得を試みて返ってきた文言で、原因はここにしかありません。2行目は状態の名前を告げているだけです。この違いは実装の作りから来ています。取得の失敗は Failed to pull image %q: %v の形で記録され、状態の名前は別の箇所から Error: %v の形で記録されます。 ...

冒頭まとめ PVC（PersistentVolumeClaim、ストレージの割り当てを求めるオブジェクト）が Pending のままになったとき、まず容量や設定ファイルを読み返す人が多くいます。順序としては後回しでかまいません。先に読むべきなのは kubectl describe pvc の Events に出る Reason の1語です。 理由は実装にあります。Kubernetes の制御側は、未結合の要求を1か所で3つの経路に振り分けています。結合を遅らせる設定で誰も使っていない場合、クラス名が指定されていて動的な作成に進む場合、そのどちらでもない場合です。この3分岐がそのまま Reason になるため、Reason を見れば自分がどの経路にいるかが確定します。 分かれ方は5通りです。WaitForFirstConsumer と WaitForPodScheduled は待機、ExternalProvisioning と ProvisioningFailed は動的な作成、FailedBinding は既存の領域との突き合わせで、それぞれ直す場所が違います。 最も見落とされるのが2番目です。WaitForPodScheduled が出ているなら、待たせているのは PVC ではありません。それを使う Pod が配置できずに止まっています。PVC の定義を読み直しても原因は出てきません。 WaitForFirstConsumer も異常ではありません。公式ドキュメントは、この設定が Pod ができるまで結合と作成を意図的に遅らせるものだと説明しています。Pending の表示だけを見て設定を書き換えると、かえって配置できない Pod を作ることになります。 エラーの概要 一覧では、状態が Pending のまま止まり、割り当て先の欄が空になります。 NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE data-pvc Pending standard 6m41s この Pending は、実装では要求の段階を表す3つの値のうちの1つです。Pending（まだ結合されていない）、Bound（結合済み）、Lost（結合していた領域が失われた）の3つが定義されています。つまり Pending 自体は失敗ではなく、結合がまだ済んでいないという事実だけを示します。 理由は Events に出ます。表示例は次のようになります。 Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal WaitForFirstConsumer 20s (x6 over 87s) persistentvolume-controller waiting for first consumer to be created before binding 出所は persistentvolume-controller です。このコードは未結合の要求を3つに振り分けます。第一に、結合を遅らせる設定で、まだ配置の判断が渡ってきていない場合。第二に、クラス名が空でない場合。第三に、そのどちらでもない場合です。1番目からは WaitForFirstConsumer または WaitForPodScheduled、2番目からは ExternalProvisioning・ProvisioningFailed・ProvisioningSucceeded、3番目からは FailedBinding が出ます。 ...

冒頭まとめ FailedCreatePodSandbox は、kubelet が Pod の sandbox（ネットワーク名前空間や pause コンテナといった、コンテナ起動前の土台）を作成できなかったときに記録される警告イベントです。Pod は ContainerCreating のまま止まり、kubelet はリトライを繰り返します。 原因はほぼ次の3方向に分かれます。 CNI プラグインまたは CNI 設定の不整合で、Pod のネットワーク設定（IP 割り当てを含む）に失敗している container runtime が sandbox image（pause image）を取得・起動できず、sandbox コンテナを作れない ノード側の状態（ディスク、iptables/sysctl、カーネルモジュール、runtime プロセス）が壊れている 調査の出発点は「イベント本文の desc = 以降に書かれた、container runtime から返った実メッセージ」です。ここに cni / network / image / no space left on device のどの語が出ているかで、上の1〜3のどれを追うべきかがほぼ決まります。次に「1ノードだけの問題か、クラスタ全体か」を確認すると、ノード修復かクラスタ設定修正かの判断が付きます。 エラーの概要 これは HTTP ステータスではなく kubelet のイベント理由です FailedCreatePodSandbox はエラーコードではなく、kubelet が Pod に対して発行する Event の reason です。kubectl describe pod の Events 欄や kubectl get events に現れます。 実際にクラスタ上で出力される文字列は FailedCreatePodSandBox（Box の B が大文字） です。ログやイベントを検索するときは大文字小文字を区別しない検索（grep -i）を使うと取りこぼしが減ります。 ...

冒頭まとめ Init:CrashLoopBackOff は、Pod の init container が失敗して終了し、kubelet による再起動が繰り返されてバックオフ待ちに入っている状態を示します。Kubernetes 公式ドキュメントでは、init container は必ず完了まで実行され、次の init container が始まる前に成功して終了する必要があり、init container が失敗した場合は kubelet が成功するまでその init container を繰り返し再起動すると説明されています。つまりこのエラーが出ている間、通常（アプリ）コンテナは一度も起動していません。 調査の出発点は次の 2 つです。 kubectl describe pod <pod-name> と status.initContainerStatuses で、どの init container が止まっているかを特定する。 kubectl logs <pod-name> -c <init-container> --previous で、直前に終了したインスタンスの終了理由を確認する。 本体コンテナの CrashLoopBackOff と混同すると調査対象がずれます。Init: の接頭辞が付いている間は、修正対象は init container 側です。 エラーの概要 Init:CrashLoopBackOff は Pod の STATUS 列に表示される文字列で、Pod の初期化フェーズで失敗が繰り返されていることを表します。 公式ドキュメントで確認できる init container の性質は次のとおりです。 init container は通常のコンテナとほぼ同じですが、常に完了まで実行される点が異なります。各 init container は、次の init container が起動する前に成功して完了しなければなりません。 init container が失敗した場合、kubelet はそれが成功するまで繰り返し再起動します。ただし Pod の restartPolicy が Never で、起動中に init container が失敗した場合は、Kubernetes は Pod 全体を失敗として扱います。 Pod の STATUS は初期化の進み方を示します。Debug Init Containers では、たとえば Init:1/2 は 2 つある init container のうち 1 つが成功して完了したことを示すと説明されています。 近い表示との違いを整理します。 ...

冒頭まとめ RunContainerError は、HTTPステータスコードではなく、Pod内のコンテナ状態に出る waiting.reason です。Podはノードに割り当てられ、Pod sandboxも作られた後、kubeletがcontainer runtimeへコンテナ起動を依頼した段階で失敗しています。 State: Waiting Reason: RunContainerError Message: <container runtime が返した実メッセージ> ここで重要なのは、RunContainerError という文字だけでは原因が決まらないことです。原因は隣にある Message、直近のEvents、そして同じノード上の他Podの状態から切り分けます。 まず次の4つを分けてください。 表示されているreasonが本当に RunContainerError なのか。 messageがワークロード設定の問題を示しているのか。 volume、権限、セキュリティ設定など、Pod定義とノード条件の組み合わせで失敗しているのか。 containerd、CRI-O、runc、cgroup、ディスクなど、ノード側runtimeの問題なのか。 kubectl logs が空でも不思議ではありません。プロセスがまだ開始できていないため、アプリケーションログへ到達しないことがあります。最初に読むべきなのは、アプリログではなく kubectl describe pod のState、Message、Eventsです。 エラーの概要 KubernetesのPod起動は、ざっくり次の段階に分けられます。 Scheduling ↓ Image pull ↓ Pod sandbox 作成 ↓ Container 作成 ↓ Container 起動 ↓ Application 実行 RunContainerError は、このうち Container作成または起動 の近辺で止まっている状態です。kubeletの実装では、RunContainerError はコンテナ起動時の失敗を表すエラーとして定義されています（sync_result.go）。 したがって、RunContainerError を見た時点で、少なくとも次の切り分けが必要です。 kubectl get pod <Pod名> -n <名前空間> \ -o jsonpath='{range .status.containerStatuses[*]}{.name}{"\t"}{.state.waiting.reason}{"\t"}{.state.waiting.message}{"\n"}{end}' initコンテナで止まっている場合は、見る場所が変わります。 ...

冒頭まとめ ContainerCreating は、根本原因を示すエラー名ではありません。kubectl get pods が、Kubernetesでコンテナをまだ開始できていない状態を要約して表示したものです。 NAME READY STATUS RESTARTS AGE app-7f6f8d9c75-2kq8m 0/1 ContainerCreating 0 8m API上では、Podの段階は Pending、コンテナの状態は Waiting、その理由が ContainerCreating になっていることがあります。 Status: Pending State: Waiting Reason: ContainerCreating Kubernetes公式のPodライフサイクルは、kubectl の STATUS 欄をPodの phase と混同しないよう明記しています。ContainerCreating を見ただけでは、ボリューム、イメージ取得、Podの通信環境、コンテナ実行基盤のどこで止まったかは決まりません。 そこで、次に kubectl describe pod の Events を読みます。 Warning FailedMount 2m (x8 over 7m) kubelet MountVolume.SetUp failed for volume "config" : configmap "app-config" not found この場合、ContainerCreating は現在の待機状態、FailedMount はボリュームの準備に失敗した試行の記録です。直す対象を示しているのは、FailedMount より後ろの文です。 configmap "app-config" not found rpc error: code = ... desc = ... driver name ... not found in the list of registered CSI drivers mount failed: exit status 32 volume is already exclusively attached to one node つまり、ContainerCreating を直接直すのではなく、最新イベントの具体的な失敗を直します。FailedMount があるなら、最初に対象ボリューム名をPodの volumes と対応させ、参照先がSecret、ConfigMap、PVC、CSIのどれかを確定します。 ...