Cloud SQL Proxy について

ここでは、Cloud SQL Proxy の基本的な概要と、プロキシ オプションについて説明します。

Cloud SQL Proxy を使用する詳細な手順については、次のリンクからお使いの環境に該当するものをクリックしてください。

Cloud SQL に App Engine の標準またはフレキシブル環境から接続するために、プロキシを使用したり SSL を構成したりする必要はありません。

プロキシの機能

Cloud SQL Proxy を使用すると、IP アドレスのホワイトリストへの登録や、SSL の構成を行わなくても、Cloud SQL の第 2 世代インスタンスに安全にアクセスできます。

Cloud SQL Proxy を使用して Cloud SQL インスタンスにアクセスする利点は以下のとおりです。

  • 安全な接続: プロキシは、TLS 1.2 と 128 ビット AES 暗号を使用して、データベースとの間で送受信されるトラフィックを自動的に暗号化します。クライアントとサーバーの ID の確認には、SSL 証明書が使用されます。
  • 簡単な接続管理: プロキシが Cloud SQL との認証を処理するので、静的な IP アドレスを提供する必要がなくなります。

プロキシは新しい接続パスを提供せず、既存の IP 接続を使用します。たとえば、プロキシがプライベート サービス アクセス用に構成された VPC ネットワークを使用している場合を除き、プライベート IP を使用してインスタンスに接続するためにプロキシを使用することはできません。

Cloud SQL Proxy の仕組み

Cloud SQL Proxy は、プロキシと呼ばれるローカル クライアントをローカル環境で実行することによって機能します。アプリケーションは、データベースで使用されている標準のデータベース プロトコルを介してプロキシと通信します。プロキシは、セキュアなトンネルを使用して、サーバー上で実行されているコンパニオン プロセスと通信します。

次の図では、プロキシが Cloud SQL に接続する方法を示します。

クライアント ソフトウェアから SQL インスタンスに接続するプロキシの図

Cloud SQL Proxy を使用する際の要件

プロキシを使用するには、次の要件を満たしている必要があります。

  • Cloud SQL Admin API が有効になっている必要があります。
  • プロキシに GCP 認証情報を指定する必要があります。
  • プロキシに有効なデータベース ユーザー アカウントとパスワードを指定する必要があります。
  • インスタンスでパブリック IPv4 アドレスが指定されているか、プライベート IP を使用するように構成されている必要があります。

    パブリック IP アドレスが(ホワイトリストに登録された)すべての外部アドレスからアクセス可能である必要はありません。

Cloud SQL Proxy のインストール

Linux 64 ビット

  1. プロキシをダウンロードします。
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. プロキシを実行できるようにします。
    chmod +x cloud_sql_proxy
    

Linux 32 ビット

  1. プロキシをダウンロードします。
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. プロキシを実行できるようにします。
    chmod +x cloud_sql_proxy
    

macOS 64 ビット

  1. プロキシをダウンロードします。
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. プロキシを実行できるようにします。
    chmod +x cloud_sql_proxy
    

macOS 32 ビット

  1. プロキシをダウンロードします。
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. プロキシを実行できるようにします。
    chmod +x cloud_sql_proxy
    

Windows 64 ビット

https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe を右クリックして [名前を付けてリンク先を保存] を選択し、プロキシをダウンロードします。ファイルの名前を cloud_sql_proxy.exe に変更します。

Windows 32 ビット

https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe を右クリックして [名前を付けてリンク先を保存] を選択し、プロキシをダウンロードします。ファイルの名前を cloud_sql_proxy.exe に変更します。
お使いのオペレーティング システムがここに記載されていない場合は、ソースからプロキシをコンパイルすることもできます。

プロキシの起動オプション

プロキシを起動するときに、次の情報をプロキシに提供します。

  • 接続先の Cloud SQL インスタンス
  • Cloud SQL へ送信するためにアプリケーションから受信するデータを待ち受ける場所
  • Cloud SQL に対するアプリケーションの認証に使用する認証情報を取得できる場所
  • 使用する IP アドレスのタイプ(必要な場合)

指定したプロキシ スタートアップ オプションによって、TCP ポートと Unix ソケットのどちらでリッスンするのかが決まります。Unix ソケットでリッスンする場合は、選択した場所(通常は /cloudsql/ ディレクトリ)にソケットが作成されます。TCP の場合、プロキシはデフォルトで localhost でリッスンします。

プロキシは、ローカル環境の任意の場所にインストールできます。プロキシ バイナリの場所が、アプリケーションから受信するデータをリッスンする場所に影響することはありません。

Cloud SQL Proxy を認証するためのオプション

Cloud SQL Proxy では、環境に応じて、認証のための代替手段が複数用意されています。プロキシは、次の項目をこの順序でチェックし、最初に見つかったものを使用して認証を試みます。

  1. プロキシ呼び出しコマンドで提供された認証情報
  2. ローカル環境によって提供された認証情報
  3. Compute Engine インスタンスに関連付けられている認証情報
  4. 認証済みの Cloud SDK クライアントからの認証情報

呼び出しと接続文字列の例をご覧ください

プロキシ呼び出しコマンドで提供された認証情報

Google Cloud Platform Console を使用して認証情報ファイルを作成し、Cloud SQL Proxy を起動するときにコマンドラインの -credential_file パラメータでそのファイルを指定できます。サービス アカウントには、Cloud SQL インスタンスに対する必要な権限が付与されていることが必要です。

この認証方法には、プロキシ固有の認証情報ファイルを作成しておけば、プロキシが実行されている限り、そのファイルがプロキシに明示的かつ永続的にリンクされるという利点があります。このため、Compute Engine インスタンスで実行していない本番インスタンスにはこの方法が推奨されます。

Cloud SQL Proxy を複数のマシンから呼び出す必要がある場合は、認証情報ファイルをシステム イメージで複製できます。

この方法を使用するには、認証情報ファイルを作成して管理する必要があります。resourcemanager.projects.setIamPolicy 権限を持つユーザー(プロジェクト オーナーなど)だけが、サービス アカウントを作成できます。GCP ユーザーにこの権限がない場合は、他のユーザーにサービス アカウントを作成してもらうか、別の方法でプロキシを認証する必要があります。

認証情報ファイルの作成に関するヘルプについては、サービス アカウントを作成するをご覧ください。

ローカル環境によって提供された認証情報

この方法はコマンドラインで認証情報ファイルを提供するのとほぼ同じですが、認証情報ファイルの場所を GOOGLE_APPLICATION_CREDENTIALS 環境変数で提供する点が異なります。

Compute Engine インスタンスに関連付けられている認証情報

Cloud SQL に Compute Engine インスタンスから接続している場合、プロキシは Compute Engine インスタンスに関連付けられているサービス アカウントを使用できます。Cloud SQL インスタンスに対する必要な権限がサービス アカウントに付与されていれば、プロキシの認証は成功します。

Compute Engine インスタンスが Cloud SQL インスタンスと同じプロジェクトに属している場合、Compute Engine インスタンスのデフォルトのサービス アカウントには、プロキシの認証に必要な権限が付与されています。この 2 つのインスタンスが別々のプロジェクトに属している場合は、Cloud SQL インスタンスが属するプロジェクトに Compute Engine インスタンスのサービス アカウントを追加する必要があります。

認証済みの Cloud SDK クライアントからの認証情報

Cloud SDK をインストールし、それを使用して GCP に対する認証を行っている場合、Cloud SQL Proxy は同じ認証情報を使用できます。この方法は、開発環境を短時間で使用できるようにする場合に特に便利です。本番環境の場合は、他のいずれかの認証方法を使用する必要があります。

Cloud SDK の現在の認証情報は、gcloud auth list コマンドを使用して確認できます。

サービス アカウントに付与される必要な権限

サービス アカウントを使用してプロキシの認証情報を提示する場合は、十分な権限が付与されたサービス アカウントを作成する必要があります。よりきめ細かい Identity Access and Management(IAM)の役割を使用して Cloud SQL 権限を管理する場合は、サービス アカウントに cloudsql.instances.connect 権限を含む役割を付与する必要があります。この役割を含む事前定義された Cloud SQL の役割は次のとおりです。

  • Cloud SQL クライアント
  • Cloud SQL 編集者
  • Cloud SQL 管理者

以前のプロジェクトの役割(閲覧者、編集者、オーナー)を使用する場合、サービス アカウントには少なくとも編集者の役割が付与されている必要があります。

Cloud SQL インスタンスを指定するためのオプション

プロキシに接続先のインスタンスを示すには複数の方法があります。明示的な方法と暗黙的な方法があります。一部の構成では、プロキシは接続リクエストに基づいて接続するため、事前に接続先インスタンスをプロキシに伝える必要はありません。

インスタンス指定のオプションは、オペレーティング システムと環境によって異なります。

オプション 利点 注意点と要件 Linux / macOS
(Unix ソケット)
Java Windows 備考
自動インスタンス検出 インスタンスを指定する必要はありません。デフォルト プロジェクト内のすべてのインスタンスに対してソケットが作成されます。 Proxy API の使用が増加します。Cloud SDK をインストールし、デフォルトのプロジェクト セットで認証する必要があります。新しいインスタンスを追加するには、プロキシの再起動が必要です。 対応 × × 本番インスタンスには推奨されません。
プロジェクト検出 インスタンスを指定する必要はありません。指定したプロジェクト内のすべてのインスタンスに対してソケットが作成されます。 Proxy API の使用が増加します。Cloud SDK をインストールして認証する必要があります。新しいインスタンスを追加するには、プロキシの再起動が必要です。 対応 × × -projects パラメータを使用します。本番環境インスタンスには推奨されません。
プロキシ呼び出しでのインスタンス指定 インスタンスのリストは既知で静的です。 新しいインスタンスを追加するには、プロキシの再起動が必要です。 対応 TCP ソケットで対応 TCP ソケットで対応 -instances パラメータを使用します。複数のインスタンスを指定する場合、スペースなしのカンマ区切りリストを使用します。 詳細についてはこちらをご覧ください。
Compute Engine メタデータでのインスタンス指定 メタデータの値を変更することでインスタンス リストを更新でき、プロキシの再起動は必要ありません。 Compute Engine でのみ使用できます。 対応 TCP ソケットで対応 TCP ソケットで対応 -instances_metadata フラグを使用します。 詳細についてはこちらをご覧ください。

呼び出しと接続文字列の例をご覧ください

プライベート IP でプロキシを使用する

プロキシは、IP を使用して Cloud SQL インスタンスとの接続を確立します。デフォルトでは、プロキシはパブリック IPv4 アドレスを使用して接続を試行します。プロキシが Cloud SQL インスタンスと同じ VPC ネットワークを使用していて、そのインスタンスにプライベート IP アドレスがある場合、プロキシはプライベート IP を使用して接続できます。

Cloud SQL インスタンスにプライベート IP しかない場合、プロキシはプライベート IP アドレスを使用して接続します。インスタンスにパブリック IP とプライベート IP の両方が構成されていて、プロキシがプライベート IP アドレスを使用するように設定するには、プロキシの開始時に次のオプションを指定する必要があります。

--ip_address_types=PRIVATE

Cloud SQL Proxy の使用に関するヒント

Cloud SQL Proxy の呼び出し

プロキシ呼び出しの例はすべてバックグラウンドでプロキシを起動するので、プロンプトが返されます。プロキシからの出力が他のプログラムからの出力と混ざらないように、そのターミナルをプロキシ専用にすることをおすすめします。また、プロキシからの出力は接続の問題を診断する際に役立つため、ログファイルに取り込んでおくことをおすすめします。

プロキシ ソケットのディレクトリとして /cloudsql を使用する必要はありません(このディレクトリ名は、App Engine の接続文字列との相違を最小限に抑えるために選択されたものです)。ただし、ディレクトリ名を変更する場合は、全体の長さを最小限に保ってください。ディレクトリ名は、さらに長い文字列に組み込まれ、オペレーティング システムの長さ制限が適用されます。

プロキシを使用して複数のインスタンスに接続する

1 つのローカル プロキシ クライアントを使用して、複数の Cloud SQL インスタンスに接続できます。これを行う方法は、Unix ソケットまたは TCP のどちらを使用しているかによって異なります。

Unix ソケット

プロキシを複数のインスタンスに接続するには、インスタンス接続名をカンマ区切りリスト(スペースなし)で、-instances パラメータ付きで指定します。プロキシは、起動時に各インスタンスに接続します。

指定されたディレクトリ内のソケットを使用して各インスタンスに接続します。

例:

./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2

TCP

TCP を使用して接続する場合は、インスタンスへの接続に使用するマシンでポートを指定します。すべてのインスタンスに専用のポートが必要です。psql ツールではデフォルトで 5432 を使用しますが、別のポートを使用するように指定することもできます。

例:

./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432,myProject:us-central1:myInstance2=tcp:5433 &
psql -U myUser -h 127.0.0.1  --port 5433

Cloud SQL Proxy を最新状態に保つ

Google から新しいバージョンのプロキシがリリースされることがあります。最新バージョンは Cloud SQL Proxy Github リリースページで確認できます。また、プロキシの今後のリリースについては、Google Groups Cloud SQL のお知らせフォーラムで通知されます。

API の使用

Cloud SQL Proxy は、Cloud SQL API に対してリクエストを発行します。これらのリクエストは、プロジェクトの API 割り当て量にカウントされます。

API 使用率は、プロキシの起動時に最高値となります。これは特に、インスタンスの自動検出または -projects パラメータを使用している場合に顕著です。プロキシは実行中に、接続されているインスタンスごとに 1 時間あたり 2 つの API 呼び出しを発行します。

Cloud SQL Proxy のパラメータとフラグ

Cloud SQL Proxy は、起動時に複数のフラグとパラメータを受け取ります。これらのオプションにより、Cloud SQL Proxy が Cloud SQL との通信に使用するソケットを作成する場所と方法、および認証の方法が決まります。

プロキシのオプションについては、次の情報をご覧ください。

プロキシの呼び出しと PSQL クライアントの接続文字列の例

次の例は、myProject プロジェクトの us-central1 にある myInstance インスタンスの PostgreSQL ユーザー myUser に対するプロキシ呼び出しと接続文字列を示しています。

自動インスタンス検出と gcloud 認証情報を使用する場合:

./cloud_sql_proxy -dir=/cloudsql &
 psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
プロジェクト検出と gcloud 認証情報を使用する場合:

./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Compute Engine インスタンスでインスタンスを明示的に指定する場合:

./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Unix で TCP を使用する場合:

./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432 &
psql -U myUser -h 127.0.0.1
Windows の場合(コマンドライン プロンプト):

cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:5432
psql -U myUser -h 127.0.0.1

Cloud SQL Proxy のオプションと接続文字列の詳細については、Cloud SQL Proxy に関する GitHub ページをご覧ください。

サービス アカウントを作成する

サービス アカウントを作成するには:

  1. Google Cloud Platform Console の [サービス アカウント] ページに移動します。

    [サービス アカウント] ページに移動

  2. 必要に応じて、Cloud SQL インスタンスを含むプロジェクトを選択します。
  3. [サービス アカウントを作成] をクリックします。
  4. [サービス アカウントの作成] ダイアログで、わかりやすいサービス アカウント名を指定します。
  5. [役割] で、次のいずれかの役割を選択します。
    • [Cloud SQL] > [Cloud SQL クライアント]
    • [Cloud SQL] > [Cloud SQL 編集者]
    • [Cloud SQL] > [Cloud SQL 管理者]

    [Project] > [編集者] の順に選択して、基本の役割である編集者を使用することもできますが、編集者の役割には Google Cloud Platform 全体に対する権限が含まれます。

    これらの役割が表示されない場合、Google Cloud Platform ユーザーに resourcemanager.projects.setIamPolicy 権限がない可能性があります。権限を確認するには、Google Cloud Platform Console の [IAM] ページにアクセスし、自分のユーザー ID を検索します。

  6. 必要に応じて [サービス アカウント ID] を一意のわかりやすい値に変更して、後でこのサービス アカウントを簡単に見つけられるようにします。
  7. [新しい秘密鍵の提供] をクリックします。
  8. デフォルトのキータイプは JSON であり、この値を使用するのが適切です。
  9. [作成] をクリックします。

    秘密鍵ファイルがマシンにダウンロードされます。秘密鍵ファイルは、別の場所に移動できます。安全な場所に鍵ファイルを保管してください。

サービス アカウントについて詳しくは、認証のドキュメントをご覧ください。

本番環境での Cloud SQL Proxy の使用

本番環境で Cloud SQL Proxy を使用している場合は、プロキシがアプリケーションに必要な可用性を確実に提供するように、以下の手順を実行してください。

Cloud SQL Proxy が永続サービスとして実行されていることを確認する

プロキシ プロセスが終了すると、そのプロキシを介した既存の接続がすべて切断され、アプリケーションはそのプロキシを使用して Cloud SQL インスタンスへの接続を確立できなくなります。このようなシナリオを回避するには、プロキシがなんらかの理由で終了した場合に自動的に再起動されるように、プロキシを永続サービスとして実行します。このためには、systemdupstartsupervisor などのサービスを使用します。Windows オペレーティング システムの場合は、プロキシを Windows サービスとして実行します。通常、プロキシはアプリケーション プロセスと同じ稼働時間要件を持っています。

アプリケーションに必要な Cloud SQL Proxy のコピー数

アプリケーション プロセスごとにプロキシ プロセスを作成する必要はありません。多くのアプリケーション プロセスで単一のプロキシ プロセスを共有できます。通常は、ワークステーションまたは仮想マシンごとに 1 つのプロキシ クライアント プロセスを実行します。

仮想マシンの自動スケーリングを使用している場合は、プロキシが仮想マシン構成に含まれており、新しい仮想マシンを起動するたびに独自のプロキシ プロセスが作成されることを確認してください。

接続を制限するかプールするかにかかわらず、アプリケーションに必要な接続数の管理はユーザーが行います。プロキシによって、新しい接続の作成頻度や永続的な接続の数が制限されることはありません。

Cloud SQL Proxy 出力の削減

プロキシログのサイズを小さくする必要がある場合は、プロキシの起動時に -verbose=false を設定します。ただし、ログのサイズを小さくすると、接続の問題を診断する際のプロキシ出力の有効性が低下するので注意してください。

Cloud SQL Proxy 接続のトラブルシューティング

Cloud SQL Proxy を使用して Cloud SQL インスタンスに接続する際に問題が発生した場合は、原因を特定するため、以下の点を確認してください。

  • プロキシ出力を確認します。

    プロキシの出力は多くの場合、問題の原因と解決方法を判断するのに役立ちます。出力をファイルに保存するか、プロキシを起動したターミナルを確認してください。

  • 403 notAuthorized エラーが発生し、サービス アカウントを使用してプロキシを認証している場合は、サービス アカウントに正しい権限があることを確認してください。

    サービス アカウントを確認するには、IAM ページでその ID を検索します。サービス アカウントには、cloudsql.instances.connect 権限が付与されている必要があります。すべての Cloud SQL の事前に定義された役割にはこの権限が付与されています(Cloud SQL Viewer を除く)。また、以前のプロジェクトの役割である EditorOwner にも必要な権限が付与されています。

  • Cloud SQL API が有効になっていることを確認します。

    有効になっていない場合は、プロキシログに「Error 403: Access Not Configured」のような出力が含まれています。

  • インスタンス リストに複数のインスタンスを含めている場合は、区切り記号としてカンマを使用していることを確認します。TCP を使用している場合は、インスタンスごとに異なるポートを指定していることを確認してください。

  • アプリケーションから接続しようとしている場合は、アプリケーションによる影響を排除するため、最初に管理クライアントを使用して接続します。

  • UNIX ソケットを使用して接続している場合は、プロキシの起動時に指定したディレクトリを一覧表示して、ソケットが作成されていることを確認します。

  • 送信ファイアウォール ポリシーがある場合は、ターゲット マシン上のポート 3307 への接続が許可されていることを確認してください。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...