Cloud SQL Auth Proxyの複数プロジェクト切り替え時の接続エラーと解決策

はじめに

今回は、Google Cloudの「Cloud Shell」から「Cloud SQL」へ接続する際、特に複数のプロジェクトを横断して作業する場面で発生した接続トラブルとその解決策についてご紹介します。

日常の業務の中でCloud Shellを利用してCloud SQL（MySQLやPostgreSQLなど）に接続し、データの確認やメンテナンスを行うことは頻繁にあるかと思います。 通常は非常に便利な構成なのですが、最近プロジェクトをまたいで接続作業を行った際に予期せぬ接続エラーに遭遇しました。

本ブログでは、実体験をもとにエラーの原因と、プロセス管理による正しい対処法について詳しく説明します。これにより、皆さんが日々の業務効率を向上させ、無駄なトラブルシューティングの時間を過ごさずに済む手助けとなることを目指しています。

Cloud SQL Auth Proxyとは

Cloud SQL Auth Proxyは、ローカル環境（今回の場合はCloud Shell環境）からCloud SQLインスタンスへの安全な接続を提供するツールです。

これを利用することで、Cloud SQL側のIP許可リストを管理したり、複雑なSSL証明書の設定を行ったりすることなく、IAM権限に基づいて安全にデータベースへ接続することが可能になります。Cloud Shellにはこのツールをあらかじめダウンロードする必要はありますが、公式ドキュメントのコマンド一つですぐにダウンロードして利用できるのが大きなメリットです。

発生した事象：プロジェクトを切り替えると接続エラーになる

今回、私が直面した具体的なシチュエーションは以下の通りです。

1. プロジェクトAでの作業：プロジェクトAにアクセスしてCloud Shellを立ち上げて、Cloud SQL Auth Proxyを起動してデータベースへ接続・作業を行いました。ここまでは通常通り、問題なく動作しました。
   
2. プロジェクトBへの切り替え：プロジェクトAでの作業が終了したため、Cloud Shellをいったん閉じました。そしてプロジェクトBにコンソール上で切り替えてから、またCloud Shellを立ち上げました。
   
3. プロジェクトBでの接続試行（エラー発生）：プロジェクトBのCloud SQLインスタンスに対して、再度接続コマンドを実行しました。しかし、ここで接続エラーが発生し、データベースに繋ぐことができませんでした。
   

「一度Cloud Shellを閉じて開き直した」ため、環境はリセットされていると思い込んでいましたが、③で載せている画像のようになぜか接続が拒否される状況でした。

原因：プロセスの残留

調査の結果、原因は非常にシンプルなものでした。「Cloud Shell上で、前のプロジェクト（プロジェクトA）向けのCloud SQL Auth Proxyプロセスが生き残っていた」ことが原因でした。

Cloud SQL Auth Proxyはバックグラウンドで実行されることが多く、またCloud Shellはウィンドウを閉じても一定時間はセッション（および実行中のプロセス）がバックグラウンドで維持されます。 そのため、見た目上は新しくCloud Shellを開き直したつもりでも、裏で動いているProxyのプロセスは「プロジェクトA」の接続情報を保持したまま、ローカルポート（例: 3306や5432）を占有し続けていました。

その結果、新しい接続コマンドを打っても、実際には古いプロセスがリクエストを処理しようとしてしまい、認証情報やインスタンスの不一致によりエラーとなっていたようです。

解決策：プロセスの停止（Kill）

解決策は、プロジェクトをまたいで接続を行う際に、必ず既存のプロセスを停止することです。具体的な手順は以下の通りです。

①プロセスの確認

以下のコマンドをCloud Shellで実行して、実行中のProxyプロセスを確認します。コマンドの実行結果にPIDがあると思いますので、そのPIDは次のコマンドで利用するためコピーしておきます。

MySQLの場合：

sudo ss -tulnp | grep :3306

PostgreSQL

sudo ss -tulnp | grep :5432

以下の画像はプロジェクトAのCloud SQLへのアクセスで利用していたプロセスがプロジェクトBで残っていることを示す画像になります。

②プロセスの停止

該当するプロセスのPIDを確認し、kill コマンドで停止します。今回の検証ではPIDが1810だったので、以下のコマンドのところを置き換えます。

sudo kill [PIDに置き換える]

これでプロセスが停止できたので、プロセスがクリアになった状態で、再度プロジェクトB向けの接続コマンドを実行します。

最後に

この挙動について公式ドキュメントを確認してみたところ、「一つのプロセスで複数のインスタンスに接続する方法」については記載がありました。しかし、「順次プロジェクトを切り替えて作業する場合、前のプロセスを明示的にKillする必要がある」という運用上の注意点までは具体的に記載されていませんでした。

一つのターミナルで連続して作業を行う場合はもちろん、今回のように「一度閉じてから開き直す」場合でも、セッション維持の仕様によりプロセスが残留することは盲点になりがちです。「プロジェクトを切り替えたら、プロキシもリセットする」をセットで覚えておく必要があります。あとは、基本的なところでエラーの文章をよく読むべきだったと考えています。

エラー自体は単純な原因でしたが、Cloud Shellのセッション維持仕様とプロセスがバックグラウンドで動いていることを忘れていると、意外と解決に時間がかかってしまうポイントです。今回の記事が、皆さんの業務やプロジェクトがさらに効率的で効果的になることを期待しています！

お忙しい中、お読みいただきありがとうございました。