Kubernetes

冒頭まとめ Pending は、コンテナの状態を表す名前ではありません。対象全体がどの段階にあるかを表す名前です。公式の定義には、対象は受け付けられたがコンテナの1つ以上がまだ起動していない状態であり、これには機器に割り当てられる前の時間と、イメージを取得している時間の両方が含まれる、と書かれています。 この一文が示すとおり、Pending は性質の違う2つの状況を1語でまとめています。置き場所がまだ決まっていない状況と、置き場所は決まったが起動の準備が終わっていない状況です。前者は配置を担う仕組みの問題で、後者は機器の上の仕組みの問題です。原因も対処もまったく違います。 分岐は1点で決まります。配置先が決まっているかどうかです。決まっていなければ配置の問題、決まっていれば起動準備の問題です。この確認を最初に行えば、調べる範囲が半分になります。 配置の問題であれば、記録に理由が残ります。文言は「0/N nodes are available」で始まり、そのあとに理由が続きます。この形式はソースに定義されていて、理由ごとに何台の機器が該当したかという数が付きます。 読み方に注意点が1つあります。この数は理由ごとの機器の台数で、1台の機器が複数の理由に数えられることがあります。したがって、並んでいる数字を足しても総数に一致するとは限りません。合計が合わないのは異常ではありません。 エラーの概要 一覧では、準備できているコンテナの数が0のまま止まります。 NAME READY STATUS RESTARTS AGE my-app-5f8c7d9b4-nq3vt 0/1 Pending 0 6m41s 配置が済んでいない場合、記録に理由が残ります。 Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning FailedScheduling 6m (x5 over 6m) default-scheduler 0/5 nodes are available: 3 Insufficient memory, 2 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }. この例では、5台のうち3台がメモリの空き不足、2台が許容していない印によって除外されています。理由が2つ並んでいるので、対処も2通り考えられます。空きを増やすか、印を許容する設定を加えるかです。 配置が済んでいる場合は、この記録が出ません。代わりに、コンテナごとの待機の理由が入ります。この場合、Pending という表示のままイメージの取得や保管領域の準備が進んでいます。 まず最初に：配置先が決まっているかを見る 第一に、配置先が入っているかを確認します。 kubectl get pod <ポッド名> -o jsonpath='{.spec.nodeName}{"\n"}' 何も出なければ、まだ置き場所が決まっていません。配置の問題として調べます。機器の名前が出れば、置き場所は決まっています。起動準備の問題として調べます。 ...

冒頭まとめ Kubernetes で 504 Gateway Timeout に出会う場面は、大きく2つに分かれます。API サーバーが自分の締め切りに達して要求を打ち切った場合と、Ingress などの中継役が背後の応答を待ちきれずに返した場合です。前者はクラスタの操作そのものが止まり、後者は利用者向けの通信が止まります。原因も対処もまったく別です。 API サーバーが打ち切った場合、文言は一意に定まっています。ソースを読むと、時間切れの応答は Timeout: request did not complete within the allotted timeout という文言で、区分は Timeout、状態コードは 504 として組み立てられます。kubectl からは Error from server (Timeout): の形で表示されます。この文言が出ていれば、打ち切ったのは API サーバー自身です。 締め切りの既定値は60秒です。API サーバーの起動時の指定として定義されており、変更にはクラスタ側の設定変更が要ります。 ここで重要なのが、クライアント側の指定との関係です。要求に待ち時間を付けて送ることはできますが、ソースの処理を読むと、指定された値が0より大きく、かつサーバー側の上限より小さい場合にだけ採用される、と書かれています。つまり、クライアント側で長い値を指定しても、サーバー側の締め切りは伸びません。短くすることはできても、伸ばすことはできない、という一方通行です。「待ち時間を伸ばす」という定番の対処が効かない理由がここにあります。 なお、監視や実行、ログの追従といった長時間動き続ける種類の要求は、この打ち切りの対象から外れます。ソースでも、該当する要求はそのまま通す分岐になっています。 エラーの概要 kubectl からは次の形で見えます。 Error from server (Timeout): error when creating "example.yaml": Timeout: request did not complete within the allotted timeout 応答そのものは次の構造です。区分と状態コードが対応しています。 { "kind": "Status", "status": "Failure", "message": "Timeout: request did not complete within the allotted timeout", "reason": "Timeout", "code": 504 } API サーバー側の記録には、要求ごとの処理時間と結果が残ります。時間切れになった要求は、要した時間とともに記録されます。 "HTTP" verb="GET" URI="/api/v1/namespaces/example/endpoints/sample?timeout=10s" latency="15.79s" resp=504 この例では、要求に10秒の指定が付いているにもかかわらず、15.79秒かかっています。指定した値と実際の処理時間は一致しません。 ...

エラーの概要 Kubernetes環境で500エラーが発生した場合、APIサーバーまたはコントロールプレーンコンポーネントで予期しない内部エラーが生じています。このエラーはクラスタ全体の管理機能に影響を与える可能性があり、迅速な対応が必要です。500エラーが返される場合、リソースの作成・更新・削除やクラスタ情報の取得が失敗することになります。 実際のエラーメッセージ例 $ kubectl apply -f deployment.yaml Error from server (InternalError): error when creating "deployment.yaml": Internal error occurred: <unknown> { "apiVersion": "v1", "kind": "Status", "metadata": {}, "status": "Failure", "message": "Internal error occurred: etcd server failed", "reason": "InternalError", "code": 500 } よくある原因と解決手順 1. etcdデータベースの障害 なぜ発生するか：etcdはKubernetesクラスタの状態を保持する分散キー・バリューストアです。etcdが応答しない、ディスク満杯、または不整合が発生するとAPIサーバーは500エラーを返します。 Before（エラーが起きる状態）： $ kubectl get nodes Error from server (InternalError): Internal error occurred: etcd server failed After（解決手順）： # 1. etcdのヘルスチェック実行 kubectl exec -it etcd-<master-node-name> -n kube-system -- etcdctl endpoint health # 2. etcdメンバーの状態確認 kubectl exec -it etcd-<master-node-name> -n kube-system -- etcdctl member list # 3. etcdポッドを再起動（自動復旧を待つ） kubectl delete pod etcd-<master-node-name> -n kube-system # 4. APIサーバーのログを確認 kubectl logs -n kube-system -l component=kube-apiserver --tail=100 2. APIサーバーのメモリ不足またはクラッシュ なぜ発生するか：APIサーバーはクラスタのすべてのリソース定義をメモリに保持しています。大規模クラスタやメモリ制限が厳しい環境では、メモリ不足（OOM）によりプロセスがクラッシュし500エラーが多発します。 ...

エラーの概要 Kubernetes環境で503エラーが発生するのは、クライアントからのリクエストに対応できるPodが存在しない、または全てのPodが利用不可状態にあることを示しています。Service経由でアクセスした際、バックエンドのPodがすべてダウンしていたり、起動途中だったり、リソース不足で応答できない状態で表示されるHTTPステータスコードです。本エラーは一時的な問題である場合が多く、Podの自動復旧により解決することもありますが、根本原因の特定と対処が必要です。 実際のエラーメッセージ例 HTTP/1.1 503 Service Unavailable Content-Type: text/html; charset=utf-8 Connection: close <html> <body><h1>503 Service Unavailable</h1> No servers are available to handle this request. </body></html> { "kind": "Status", "apiVersion": "v1", "metadata": {}, "status": "Failure", "message": "no endpoints available for service", "code": 503 } よくある原因と解決手順 原因1: Podがすべてダウン状態である DeploymentやStatefulSetで定義したPodが何らかの理由でクラッシュしており、バックエンドサーバーが完全に停止している状態です。CrashLoopBackOff状態やExit Code 1などの異常終了が続いている場合に発生します（Kubernetes の CrashLoopBackOff の記事）。 Before（エラーが起きるコード）： apiVersion: apps/v1 kind: Deployment metadata: name: web-app spec: replicas: 3 selector: matchLabels: app: web template: metadata: labels: app: web spec: containers: - name: app image: myapp:latest env: - name: DATABASE_URL value: "invalid-connection-string" After（修正後）： ...

エラーの概要 Kubernetesの404エラーは、APIサーバーが指定したリソース（Pod・Service・Deploymentなど）やアクセスしようとしたエンドポイントが存在しないことを示します。kubectlコマンド実行時やKubernetes APIへのHTTPリクエスト時に発生し、リソースの削除後のアクセスや存在しないNamespaceへのクエリで特に見られます。このエラーはデータ消失を意味しませんが、リソースが実際に動作していない状態を示しているため、早期の対応が必要です。 実際のエラーメッセージ例 $ kubectl get pod my-app -n production Error from server (NotFound): pods "my-app" not found { "kind": "Status", "apiVersion": "v1", "metadata": {}, "status": "Failure", "message": "pods \"web-server\" not found", "reason": "NotFound", "details": { "name": "web-server", "kind": "pods" }, "code": 404 } よくある原因と解決手順 原因1：リソースが削除されている なぜ発生するか： Podやサービスが意図せず削除されたり、別のプロセスによって削除された後もアクセスしようとした場合に発生します。Deployment経由でPodを管理している場合、Podは自動的に再作成されることもあります。 Before（エラーが起きるコード）： kubectl delete pod my-app kubectl get pod my-app # Error: pods "my-app" not found After（修正後）： # リソースが本来管理されるべきDeploymentから再作成させる kubectl get deployment kubectl describe deployment my-app-deployment # または新しいPodを作成 kubectl run my-app --image=my-image:latest 原因2：Namespaceの指定ミス なぜ発生するか： リソースがあるNamespaceと異なるNamespaceを指定した場合、APIサーバーはそのNamespace内のリソースを探すため404となります。デフォルトのdefault Namespaceではなく、productionやstagingなどのNamespaceにリソースが存在することを見落とすことが多くあります。 ...

エラーの概要 Kubernetes APIサーバーへのリクエストが不正な形式や内容であることを示すHTTP 400エラーです。マニフェストファイルの構文エラー、API仕様に違反するフィールド値、または不完全なリクエストボディが原因となります。このエラーはクラスタとの通信に成功した後、サーバー側でリクエストの妥当性検証に失敗したときに発生する重要な診断シグナルです。 実際のエラーメッセージ例 { "kind": "Status", "apiVersion": "v1", "metadata": {}, "status": "Failure", "message": "error validating data: ValidationError(Pod.spec.containers[0].resources.limits): invalid type for io.k8s.api.core.v1.ResourceList: got \"string\", expected \"object\"", "reason": "BadRequest", "code": 400 } error: error validating "deployment.yaml": error validating data: [ValidationError(Deployment.spec.template.spec.containers[0].ports[0].containerPort): invalid type for io.k8s.api.core.v1.ContainerPort: got "string", expected "integer", ValidationError(Deployment.spec.template.spec.containers[0].image): string length must be non-empty] よくある原因と解決手順 原因1: YAML構文エラーまたはフィールド型の不一致 なぜ発生するか： Kubernetesマニフェストファイルで、数値型フィールドを文字列で指定したり、オブジェクト型フィールドにスカラー値を渡したりするときに発生します。特にポート番号やリソース制限でこの問題が頻発します。 Before（エラーが起きるコード）： apiVersion: v1 kind: Pod metadata: name: nginx-pod spec: containers: - name: nginx image: nginx:latest ports: - containerPort: "8080" # 文字列型で指定 resources: limits: memory: 512Mi # オブジェクト型だが不正 cpu: "1" # 数値型だが文字列 After（修正後）： apiVersion: v1 kind: Pod metadata: name: nginx-pod spec: containers: - name: nginx image: nginx:latest ports: - containerPort: 8080 # 整数型で指定 resources: limits: memory: 512Mi cpu: "1" # CPU値は文字列でも有効 requests: memory: 256Mi cpu: "500m" 原因2: 必須フィールドの欠落 なぜ発生するか： Kubernetesリソースの必須フィールド（例：metadata.name、コンテナのimage）が定義されていない場合に発生します。APIサーバーは最小限のリソース定義すら受け付けません。 ...

エラーの概要 Kubernetesで401エラーが発生するのは、APIサーバーへのリクエストに対して認証に失敗した状態を示します。認証トークンの有効期限切れ、認証情報の不足、または権限がないServiceAccountの使用が典型的な原因です。このエラーが出ると、kubectlコマンドの実行やPodからAPIサーバーへのアクセスが拒否されます。 実際のエラーメッセージ例 error: You must be logged in to the server (Unauthorized) { "kind": "Status", "apiVersion": "v1", "metadata": {}, "status": "Failure", "message": "Unauthorized", "reason": "Unauthorized", "code": 401 } kubectl logs pod-name -n default Error from server (Unauthorized): pods "pod-name" is forbidden: User "system:serviceaccount:default:default" cannot get resource "pods" in API group "" in the namespace "default" よくある原因と解決手順 原因1：kubeconfig設定の無効化または存在しない認証情報 kubeconfig内の証明書やトークンが無効になっている、または参照しているファイルが削除されている場合に401エラーが発生します。クラスタをセットアップした時点での認証情報が失われたり、パスが誤っていたりすることが多いです。 Before（エラーが起きるコード）： # ~/.kube/config apiVersion: v1 clusters: - cluster: certificate-authority: /etc/kubernetes/pki/ca.crt # ファイルが削除済み server: https://10.0.0.1:6443 name: my-cluster contexts: - context: cluster: my-cluster user: admin-user name: my-context current-context: my-context users: - name: admin-user user: client-certificate: /home/user/.certs/client.crt # パスが誤っている client-key: /home/user/.certs/client.key After（修正後）： ...

エラーの概要 Kubernetes の 403 エラーは「Forbidden」を意味し、リクエストの認証は成功しているものの、そのリソースに対する操作権限（RBAC: Role-Based Access Control）がないことを示します。Pod の実行、リソースの取得・更新・削除など、特定の操作がセキュリティポリシーにより拒否された状態です。API サーバーやマニフェスト適用時、kubectl コマンド実行時に頻繁に発生します。 実際のエラーメッセージ例 Error from server (Forbidden): pods "my-pod" is forbidden: User "system:serviceaccount:default:app" cannot get resource "pods" in API group "" in the namespace "default" { "kind": "Status", "apiVersion": "v1", "metadata": {}, "status": "Failure", "message": "deployments.apps \"nginx\" is forbidden: User \"system:serviceaccount:kube-system:default\" cannot create resource \"deployments\" in API group \"apps\" in the namespace \"kube-system\"", "reason": "Forbidden", "details": { "name": "nginx", "group": "apps", "kind": "deployments" }, "code": 403 } よくある原因と解決手順 原因1: ServiceAccount に適切な Role が割り当てられていない ServiceAccount は Kubernetes 内のアカウントであり、Pod がリソースにアクセスする際に使用されます。このアカウントに必要な権限を持つ Role が紐付けられていない場合、403 エラーが発生します。 ...