エラーの概要
新しいデプロイメントをプッシュした直後に、Podが停止してしまうことがあります。5分経っても ContainerCreating 状態のままで、アプリケーションのログも全く出力されません。kubectl describe pod コマンドで詳細を確認すると、出力の最後に以下のような一連の Warning イベントが表示されているはずです。
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning FailedMount 12s (x5 over 44s) kubelet MountVolume.SetUp failed for volume "config-vol" : configmap "app-config" not found
要するに、ワーカーノード上の Kubelet が ConfigMap または Secret をコンテナのファイルシステムにマウントしようとしていますが、そのリソースが見つからない状態です。Kubernetes は、必要な依存関係が揃わない限りコンテナを起動させません。リソースが表示されるのを期待して、バックグラウンドで再試行を繰り返します。
主な原因
通常、以下の3つのいずれかが原因です。
- 名前空間（Namespace）の不一致: ConfigMap を
defaultに作成したが、Pod はproductionで実行されている。 - YAMLのタイポ: Deployment マニフェスト内での大文字・小文字の区別ミスや、名前のスペルミス。
- リソースの欠落: ConfigMap が作成されていない、またはチームメンバーがクリーンアップのために削除してしまった。
ステップ別のトラブルシューティング
1. リソースと名前空間を確認する
ConfigMap や Secret などの Kubernetes リソースは名前空間に属しています。これらは境界を越えてマウントすることはできません。Pod が web-stack 名前空間にある場合、ConfigMap も同じ場所に存在する必要があります。以下のコマンドを実行して確認してください。
# 'web-stack' を実際の名前空間に置き換えてください
kubectl get configmap app-config -n web-stack
もし Error from server (NotFound) と表示された場合は、リソースが不足しています。正しい場所にリソースを再作成する必要があります。
2. 大文字・小文字の区別とタイポをチェックする
Kubernetes は命名に対して厳密です。App-Config と app-config は別物として扱われます。デプロイメントマニフェストを開き、volumes セクションとクラスター内の実際のリソース名を比較してください。
# デプロイメントマニフェストを確認
spec:
volumes:
- name: config-vol
configMap:
name: app-config # <-- これは 'kubectl get configmap' の結果と完全に一致する必要があります
3. 欠落しているConfigMapを作成する
リソースが本当に存在しない場合は、その場で作成してデプロイを再開できます。例えば、アプリが config.yaml ファイルを必要としている場合は、以下を実行します。
kubectl create configmap app-config --from-literal=API_URL="https://api.example.com" -n web-stack
作成後、Pod を再起動する必要はありません。Kubelet は通常10〜20秒ごとにマウントを再試行します。ConfigMap が見つかると、Pod は自動的に Running 状態に移行します。
4. オプションのマウントを使用する
アプリの起動に設定ファイルが必ずしも必須ではない場合もあります。その場合は、ボリュームをオプション（optional）としてマークできます。これにより、ConfigMap が削除されても Pod 全体がハングするのを防ぐことができます。
volumes:
- name: config-vol
configMap:
name: app-config
optional: true # <-- ConfigMapがなくてもPodは起動します
Secretの場合は？
Secret の場合もロジックは同じです。secret "db-password" not found というエラーが表示された場合は、同様の手順でコマンドを Secret 用に置き換えて実行してください。
kubectl get secret db-password -n web-stack
確認作業
すべてが正常に戻ったか確認するには、Pod のステータスを監視します。イベントログに Started container というメッセージが表示されているか確認してください。
kubectl get pods -n web-stack
# ステータスが 'Running' になっているはずです
kubectl describe pod <pod-name> -n web-stack
# "Successfully mounted volumes for pod..." というメッセージを探します
再発防止のアドバイス
その場しのぎの手動修正も役立ちますが、自動化によってこれらの問題を本番環境に持ち込まないようにすることが重要です。ConfigMap と Deployment を同じ Helm チャートや Kustomize フォルダにまとめましょう。これにより、常に一つのユニットとして適用されるようになります。また、ArgoCD のような GitOps ツールを使用すると、CLI を確認する前に視覚的なダッシュボードで依存関係の欠落を把握できます。