テクノロジー · 実用ガイド

kubectl port-forward の「connection refused」—再試行前に4区間を監査

ローカル listener、API tunnel、選択された Pod、Pod 内 process を分け、最初に失敗した区間だけを直します。

執筆 Watch at Ease News · 3 分で読めます公開 2026/10/17 8:43 UTC

接続拒否は一種類ではありません。local socket の bind、API stream、再起動中の Pod、または Pod 内の remote port listener が失敗点になり得ます。

完全な command と最初の error を保存し、4区間を順に確認します。--address 0.0.0.0 は local 公開範囲を変えるだけで、Pod 内 listener は作りません。

command と最初の failure を保存

context、namespace、target、mapping、version、最初の refusal 前の全出力を記録します。

local bind failure は空き port で確認し、forbidden や stream error は RBAC を先に確認します。

name、UID、node、start time、readiness、restart、deletion timestamp を保存します。

rollout 中は Forwarding 後に終了し得るため、診断では Running、Ready の Pod を直接指定します。

Service port と targetPort、Pod の runtime config を照合します。Service 80 が Pod 8080 に対応する場合があります。

selector と EndpointSlice は選択理由を示しますが listener の存在証明ではありません。

承認された read-only 方法で共有 namespace の TCP listener、process、protocol を確認します。

listener がなければ app config や startup を直します。local --address は remote refusal を修復しません。

明示した Pod へ新しく forward し、正しい protocol の request と同じ UID を確認します。

完了条件は local listener、API stream、Pod identity、remote process の全一致です。