Posts

冒頭まとめ GCP の 401 Unauthorized は、「あなたが誰なのか分からない」という意味です。「あなたにその操作をする資格がない」ではありません。この2つは似て見えますが、GCP では明確に区別されています。 Google が公開しているエラー区分の定義ファイルを読むと、その区別が仕様として書かれています。401 に対応する区分の説明は「その操作に対する有効な認証情報を持っていない」という一文だけです。一方、403 に対応する区分の説明には、呼び出し元を特定できない場合にこれを使ってはならず、代わりに 401 の区分を使うこと、と明記されています。 つまり、認証情報が届いていない、あるいは読めない段階が 401 です。誰であるかは分かったが、その人にはその操作が許されていない段階が 403 です。この境界は、対処の方向を決めます。401 に対して権限の役割を追加しても、何も変わりません。 もう1つ、実務で誤解されやすい点があります。サービスアカウントの鍵は、既定では期限切れになりません。公式文書に、利用者が作成した鍵は既定では期限が無い、と明記されています。組織の方針で期限を設定した場合にのみ期限が発生します。したがって「鍵の期限切れ」を最初に疑うのは、多くの環境で見当違いです。 期限があるのは、短命の認証情報のほうです。こちらは既定で1時間、組織の設定を変えれば最大12時間まで延ばせます。長時間動く処理で 401 に当たるなら、疑うべきはこちらです。 エラーの概要 応答の形は他のエラーと共通で、status に区分名が入ります。 { "error": { "code": 401, "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.", "status": "UNAUTHENTICATED" } } status が UNAUTHENTICATED であることが、このエラーの性質を示しています。認証されていない、という区分です。 details 配列には、機械が読める識別子が入ります。設計の指針では、すべてのエラー応答が識別子を含むべきとされているため、reason の値で原因を分岐できます。 コマンド行の道具からは、認証情報が見つからない旨の文言が出ます。この場合、要求は送られてすらいないことがあります。手元で認証情報を探す段階で失敗しているためです。応答としての 401 なのか、手元での失敗なのかは、文言で区別できます。 まず最初に：誰として認証されているかを確認する 第一に、いま自分がどの身元で操作しているかを確認します。 gcloud auth list 第二に、実際に使われる認証情報が何かを確認します。ここが意図と違っていることが、このエラーの大半です。 gcloud auth application-default print-access-token > /dev/null && echo "既定の認証情報あり" || echo "既定の認証情報なし" 第三に、status が UNAUTHENTICATED か PERMISSION_DENIED かを見ます。後者であれば、認証は通っており、問題は権限の側です。調べる先が変わります（GCP の 403 の記事）。 ...

冒頭まとめ GCP の 403 Forbidden は、身元は届いているが、その操作が許されていない状態を示します。認証が通っていない 401 とは段階が違います（GCP の 401 の記事）。 このエラーの扱いやすさは、応答に含まれる情報の多さにあります。公式文書によれば、コマンド行の道具や窓口が返す文言には、必要な権限の名前、操作しようとした対象、認証に使われた身元、エラーごとの識別子、そして原因を調べるための専用の URL が含まれます。つまり、どの権限が足りないかは推測する必要がありません。応答に書かれています。 原因についても、公式文書が4つに整理しています。必要な権限を持っていない場合、拒否の方針が権限の使用を妨げている場合、主体に対する境界の方針が対象を含んでいない場合、そして対象が存在しない場合です。 4つ目が重要です。対象が存在しない場合も、このエラーになります。実際、文言も「対象に対して権限が拒否されました（あるいは対象が存在しない可能性があります）」という形になっており、両方の可能性を含んだ書き方です。したがって、403 を受け取ったからといって、権限の問題とは限りません。名前の綴りを間違えているだけ、ということがあります。 区分の定義にも、このエラーが要求の妥当性や対象の存在を意味しない、と明記されています。 エラーの概要 窓口からの応答は、次の形になります。 { "error": { "code": 403, "message": "Permission 'storage.buckets.list' denied on resource (or it may not exist). Remediate access with this Troubleshooter URL or share it with your administrator - https://console.cloud.google.com/iam-admin/troubleshooter;errorId=<識別子> .", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "forbidden", "domain": "global", "metadata": { "error_info_id": "<識別子>", "permission": "storage.buckets.list" } } ] } } 読むべきは metadata の中の permission です。ここに、不足している権限の名前がそのまま入ります。上の例なら、ファイル置き場の一覧を取得する権限です。 ...

エラーの概要 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（修正後）： ...

冒頭まとめ Nginx の 502 Bad Gateway は、リバースプロキシとしての Nginx が上流（proxy_pass や fastcgi_pass の接続先）への接続に失敗したか、接続はできたものの応答として解釈できないデータを受け取ったことを示します。原因はほぼ確実にエラーログの文言で特定できます。connect() failed (111: Connection refused) なら上流が起動していないか接続先の指定違い、unix ソケットへの (2: No such file or directory) や (13: Permission denied) ならソケットのパスか権限、no live upstreams なら全上流サーバーの一時除外、upstream prematurely closed connection なら上流の応答途中の切断、upstream sent too big header なら応答ヘッダーのバッファ超過、SSL_do_handshake() failed なら上流との TLS ハンドシェイク失敗です。 502と誤解されやすい隣のコードも押さえておくと迷いません。上流の応答待ちの時間切れは502ではなく504です（エラーログに upstream timed out と残ります）。limit_req などの制限超過は503、応答前にクライアント側が切断した場合はアクセスログに499が残ります。「遅いから502」という説明を見かけますが、Nginx のソースコード上、時間切れは504に明示的に割り当てられており、502になるのはそれ以外の接続失敗と不正応答です。 エラーの概要 Nginx は上流への中継に失敗したとき、失敗の種類ごとに返すステータスコードを割り当てます。この割り当てはソースコード（ngx_http_upstream.c の ngx_http_upstream_next）で確認でき、時間切れ（NGX_HTTP_UPSTREAM_FT_TIMEOUT）は504、接続失敗・不正な応答ヘッダー・全サーバー除外などそれ以外の失敗は既定の分岐として502になります。つまり502は「時間内に、しかし正常には、上流とやり取りできなかった」ことの総称です。 ブラウザに表示されるデフォルトのエラーページ： 502 Bad Gateway nginx アクセスログの出力例： 192.0.2.10 - - [15/Jul/2026:10:23:45 +0900] "GET /api/users HTTP/1.1" 502 157 "-" "Mozilla/5.0" エラーログ（/var/log/nginx/error.log）の出力例。この upstream: に続く接続先と、括弧内の失敗理由が切り分けの起点です： ...

冒頭まとめ Nginx の 503 Service Unavailable の原因は、ほぼ次の3系統のいずれかです。第一に、limit_req（リクエスト頻度の制限）や limit_conn（同時接続数の制限）の超過で、Nginx 自身が既定で 503 を返します。第二に、メンテナンス用に設定した return 503 が設定内に残っているケースです。第三に、proxy_pass 先の上流アプリケーション自身が 503 を返し、Nginx がそれをそのまま中継しているケースです。 注意すべき点として、「バックエンドに接続できない」ときに Nginx が返すのは 503 ではなく 502 Bad Gateway、応答待ちで時間切れになったときは 504 Gateway Timeout です。503 の調査だと思っていたものが実は 502 や 504 の問題だった、ということが起こりやすいので、まずアクセスログで実際のステータスコードを確かめ、次にエラーログの文言で原因を絞り込みます。 エラーの概要 503 Service Unavailable は、サーバーが一時的にリクエストを処理できない状態を示します。Nginx をリバースプロキシとして使っている場合、似た状況で返るコードが3つあり、区別が重要です。上流への接続自体に失敗した場合（プロセス停止、ポート違い、接続拒否など）は 502、接続はできたが応答が時間内に返らなかった場合は 504、そして上流が「処理できない」と自ら 503 を応答した場合はその 503 がそのまま中継されます。加えて、上流と無関係に Nginx 自身が制限機能によって 503 を返す場合があります。 Nginx が自身の既定ページで 503 を返す場合、ブラウザには「503 Service Temporarily Unavailable」という見出しだけが表示されます。「The server is temporarily unable to service your request due to maintenance downtime or capacity problems.」のような説明文が表示されているなら、それは Nginx の既定ページの文言ではなく、上流の別のサーバーが生成した 503 を中継している可能性が高いです（原因3）。 ...

冒頭まとめ Nginx の 504 Gateway Time-out は、リバースプロキシとして上流（proxy_pass や fastcgi_pass の先）の応答を待ったが、時間内に届かなかったことを示します。時間切れになるタイマーは2つあり、どちらかはエラーログの文言で判別できます。文言が while connecting to upstream で終わっていれば、接続の確立自体が時間切れです（proxy_connect_timeout。原因は経路の問題が典型）。while reading response header from upstream で終わっていれば、接続はできたが応答が返らない時間切れです（proxy_read_timeout。原因は上流の処理の遅さが典型）。 対処の本筋は、時間を延ばすことではなく、どのタイマーがなぜ切れたかを特定することです。応答待ちの時間切れなら遅い処理の改善が本筋で、正当に時間のかかる処理に限ってタイムアウトを延ばします。その際、設定したのに効かないという定番の落とし穴（別の location が処理している、リロード漏れ）があるため、実効設定の確認までを対処に含めます。 エラーの概要 Nginx が自身の既定ページで504を返す場合、ブラウザには「504 Gateway Time-out」（Time-out はハイフン入り）という見出しだけが表示されます。エラーログには次のように記録されます。 2026/07/14 14:32:10 [error] 1234#1234: *567 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.100, server: example.com, request: "GET /api/report HTTP/1.1", upstream: "http://127.0.0.1:8080/api/report" 関係するタイマーの正確な仕様を押さえておくと、対処を誤りません。公式ドキュメントによると、proxy_connect_timeout（既定60秒）は上流との接続確立に対する制限で、通常75秒を超える値には設定できません。proxy_read_timeout（既定60秒）は応答の読み取りに対する制限ですが、応答全体の転送時間の上限ではなく、連続する2つの読み取り操作の間隔に適用されます。つまり上流が少しずつでもデータを送り続けていれば、全体が60秒を超えても切れません。切れるのは「この時間、何も送られてこなかった」ときです。proxy_send_timeout（既定60秒）は同様に、上流への書き込み操作の間隔に適用されます。PHP-FPM などの FastCGI 構成では、対応する fastcgi_read_timeout などが同じ意味を持ちます。 なお、似た状況で別のコードになる場合があります。上流への接続が即座に拒否された場合（プロセス停止・ポート違い）は504ではなく502です。また、Nginx が待っている間にクライアント側が先に諦めて切断した場合は、誰にも何も返らず、アクセスログに499が記録されます。 まず最初に：エラーログの文言でタイマーを特定する sudo grep "upstream timed out" /var/log/nginx/error.log | tail -10 該当行の末尾近くの文言を読みます。while connecting to upstream なら接続確立の時間切れで、調べるのは経路です（原因2）。while reading response header from upstream なら応答待ちの時間切れで、調べるのは上流の処理時間です（原因1）。 ...

エラーの概要 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（修正後）： ...