Cloud SQL Auth Proxy を使用して接続する

このページでは、Cloud SQL Auth Proxy を使用して Cloud SQL インスタンスに接続する方法について説明します。

Cloud SQL Auth Proxy の動作の詳細については、Cloud SQL Auth Proxy についてをご覧ください。

概要

Cloud SQL インスタンスに接続する場合は、Cloud SQL Auth Proxy を使用することをおすすめします。Cloud SQL Auth Proxy は、次のことを行います。

  • パブリック IP エンドポイントとプライベート IP エンドポイントの両方で動作する。
  • ユーザーまたはサービス アカウントの認証情報を使用して接続を検証する。
  • Cloud SQL インスタンスに対して認可された SSL / TLS レイヤに接続をラップする

一部の Google Cloud サービスとアプリケーションでは、Cloud SQL Auth を使用して暗号化と認可を行い、パブリック IP パスの接続を可能にしています。

Google Kubernetes Engine で実行されるアプリケーションは、Cloud SQL Auth Proxy を使用して接続できます。

基本的な使用方法については、Cloud SQL Auth Proxy を使用するためのクイックスタートをご覧ください。

ローカルマシンまたは Compute Engine から sqlcmd クライアントを使用して、Cloud SQL Auth Proxy の有無を問わず接続することもできます。

始める前に

Cloud SQL インスタンスに接続するには、次の作業が必要です。

  1. ユーザー アカウントに Cloud SQL クライアントのロールがあることを確認します。

    IAM ページに移動

  2. Cloud SQL Admin API を有効にします。

    API を有効にする

  3. Cloud SDK をインストールし、初期化します。
  4. 省略可。Cloud SQL Auth プロキシの Docker クライアントをインストールします。

Cloud SQL Auth Proxy をダウンロードする

Linux 64 ビット

  1. Cloud SQL Auth Proxy をダウンロードします。
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Cloud SQL Auth Proxy を動作可能にします。
    chmod +x cloud_sql_proxy
    

Linux 32 ビット

  1. Cloud SQL Auth Proxy をダウンロードします。
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. wget コマンドが見つからない場合は、sudo apt-get install wget を実行してダウンロード コマンドを繰り返します。
  3. Cloud SQL Auth Proxy を動作可能にします。
    chmod +x cloud_sql_proxy
    

macOS 64 ビット

  1. Cloud SQL Auth Proxy をダウンロードします。
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Cloud SQL Auth Proxy を動作可能にします。
    chmod +x cloud_sql_proxy
    

macOS 32 ビット

  1. Cloud SQL Auth Proxy をダウンロードします。
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Cloud SQL Auth Proxy を動作可能にします。
    chmod +x cloud_sql_proxy
    

Windows 64 ビット

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

Windows 32 ビット

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

Cloud SQL Auth Proxy Docker イメージ

便宜上、Cloud SQL Auth プロキシを含む複数のコンテナ イメージは、GitHub で Cloud SQL Auth プロキシ リポジトリから入手できます。次のコマンドを使用して、最新のイメージをローカルマシンに Docker で pull できます。
docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

その他の OS

ここに記載されていないその他のオペレーティング システムの場合は、ソースから Cloud SQL Auth Proxy をコンパイルできます。

Cloud SQL Auth Proxy の起動

TCP ソケットまたは Cloud SQL Auth Proxy の Docker イメージを使用して、Cloud SQL Auth Proxy を起動できます。Cloud SQL Auth Proxy バイナリは、コマンドラインで指定された 1 つ以上の Cloud SQL インスタンスに接続し、TCP ソケットとしてローカル接続を開きます。アプリケーション コードやデータベース管理クライアント ツールなど、他のアプリケーションやサービスは、これらの TCP ソケットの接続を介して Cloud SQL インスタンスに接続できます。

TCP ソケット

TCP 接続の場合、Cloud SQL Auth Proxy は、デフォルトでは localhost127.0.0.1)でリッスンします。したがって、インスタンスに tcp:PORT_NUMBER を指定すると、ローカル接続は 127.0.0.1:PORT_NUMBER になります。

また、ローカル接続に別のアドレスを指定することもできます。たとえば、ローカル接続用に Cloud SQL Auth Proxy が 0.0.0.0:1234 でリッスンする方法を次に示します。

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234
  1. INSTANCE_CONNECTION_NAME をコピーします。これは、Google Cloud Console のインスタンスの [概要] ページで確認できます。また、次のコマンドを実行して確認することもできます。

    gcloud sql instances describe INSTANCE_NAME

    例: myproject:myregion:myinstance

  2. インスタンスにパブリック IP とプライベート IP の両方が構成されている場合に、Cloud SQL Auth Proxy によってプライベート IP アドレスが使用されるようにするには、Cloud SQL Auth Proxy の起動時に次のオプションを指定する必要があります。
    -ip_address_types=PRIVATE
  3. サービス アカウントを使用して Cloud SQL Auth Proxy を認証する場合は、サービス アカウントを作成したときに作成された秘密鍵ファイルのクライアント マシン上での場所を記録しておきます。
  4. Cloud SQL Auth Proxy を起動します。

    有効な Cloud SQL Auth Proxy の呼び出し文字列:

    • Cloud SDK 認証を使用する場合
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433
      
      指定されたポートは、ローカル データベース サーバーなどがまだ使用していないものにする必要があります。
    • サービス アカウントを使用して、インスタンス接続の名前を明示的に指定する場合(本番環境用に推奨):
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:1433 \
                        -credential_file=PATH_TO_KEY_FILE &
      

    Cloud SQL Auth Proxy オプションの詳細については、Cloud SQL Auth Proxy を認証するためのオプションインスタンスを指定するためのオプションをご覧ください。

Docker

Docker コンテナで Cloud SQL Auth Proxy を動作させるには、Google Container Registry から入手できる Cloud SQL Auth Proxy Docker イメージを使用します。

次のコマンドで、TCP ソケットまたは Unix ソケットのどちらかを使用して、Cloud SQL Auth Proxy を起動できます。このオプションは、Cloud SQL インスタンスを識別するための接続文字列として INSTANCE_CONNECTION_NAME を使用します。INSTANCE_CONNECTION_NAME は、Google Cloud Console のインスタンスの [概要] ページに表示されます。また、次のコマンドを実行して確認することもできます。

gcloud sql instances describe INSTANCE_NAME
.

例: myproject:myregion:myinstance

言語や環境に応じて、TCP ソケットまたは Unix ソケットのどちらかを使用して Cloud SQL Auth Proxy を起動できます。Unix ソケットは、Java プログラミング言語で作成されたアプリケーションや Windows 環境ではサポートされていません。

TCP ソケットの使用

docker run -d \\
  -v PATH_TO_KEY_FILE:/config \\
  -p 127.0.0.1:1433:1433 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 -credential_file=/config

Compute Engine インスタンスによって提供される認証情報を使用している場合は、credential_file パラメータと -v PATH_TO_KEY_FILE:/config の行を含めないでください。

Cloud SQL Auth Proxy がローカルホストの外部に公開されないように、常に 127.0.0.1 に -p の接頭辞を指定します。インスタンス パラメータに含まれる「0.0.0.0」は、Docker コンテナの外側からポートにアクセスできるようにするために必要です。

Unix ソケットの使用

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

Compute Engine インスタンスによって提供される認証情報を使用している場合は、credential_file パラメータと -v PATH_TO_KEY_FILE:/config の行を含めないでください。

コンテナ最適化イメージを使用している場合は、/cloudsql の代わりに書き込み可能なディレクトリを使用します。たとえば、次のようにします。

-v /mnt/stateful_partition/cloudsql:/cloudsql

複数のインスタンスをカンマで区切って指定できます。また、Compute Engine メタデータを使用して接続対象のインスタンスを動的に決定することもできます。Cloud SQL Auth Proxy パラメータについての詳細をご覧ください。

sqlcmd クライアントに接続する

Debian、Ubuntu

Debian / Ubuntu については、こちらの手順を使用して、該当する SQL Server コマンドライン ツールをインストールします。

CentOS / RHEL

CentOS / RHEL については、こちらの手順を使用して、該当する SQL Server コマンドライン ツールをインストールします。

openSUSE

openSUSE については、こちらの手順を使用して、該当する SQL Server コマンドライン ツールをインストールします。

他のプラットフォーム

SQL サーバーをインストールするためのランディング ページと、SQL Server のダウンロード ページをご覧ください。

使用する接続文字列は、Cloud SQL Auth Proxy の起動時に TCP ソケットを使用したか、Docker を使用したかによって異なります。

TCP ソケット

  1. sqlcmd クライアントを起動します。
    sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD
    

    TCP ソケットを使用して接続する場合、Cloud SQL Auth Proxy には 127.0.0.1 経由でアクセスします。

  2. プロンプトが表示されたら、パスワードを入力します。
  3. sqlcmd プロンプトが表示されます。

お困りの場合、プロキシのトラブルシューティングについては、Cloud SQL Auth Proxy 接続のトラブルシューティングまたは Cloud SQL のサポートページをご覧ください。

アプリケーションに接続する

TCP ソケットに接続できる任意の言語を使用して、Cloud SQL Auth Proxy に接続できます。アプリケーションでどのように連携するのかを把握できるように、GitHub の詳細な例からコード スニペットをいくつか紹介します。

TCP で接続

Cloud SQL Auth Proxy 呼び出しステートメント:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from environment variable DB_HOST
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

# SQL Server drivers don't account for this
if db_hostname == "localhost":
    db_hostname = "127.0.0.1"

# The SQLAlchemy engine will help manage interactions, including automatically
# managing a pool of connections to your database
pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mssql+pytds://<db_user>:<db_pass>@/<host>:<port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
    sqlalchemy.engine.url.URL.create(
        "mssql+pytds",
        username=db_user,
        password=db_pass,
        database=db_name,
        host=db_hostname,
        port=db_port,
    ),
    **db_config
)

Java

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

注:

  • CLOUD_SQL_CONNECTION_NAME は <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME> のように指定する必要があります。
  • 引数 ipTypes=PRIVATE を使用すると、SocketFactory はインスタンスに関連付けられたプライベート IP を使用して接続するようになります。
  • pom.xml ファイルの JDBC ソケット ファクトリ バージョン要件については、こちらをご覧ください。

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following is equivalent to setting the config options below:
// jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
// socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
// socketFactoryConstructorArg=<INSTANCE_CONNECTION_NAME>

// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config
    .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
config.setUsername(DB_USER); // e.g. "root", "sqlserver"
config.setPassword(DB_PASS); // e.g. "my-password"
config.addDataSourceProperty("databaseName", DB_NAME);

config.addDataSourceProperty("socketFactoryClass",
    "com.google.cloud.sql.sqlserver.SocketFactory");
config.addDataSourceProperty("socketFactoryConstructorArg", INSTANCE_CONNECTION_NAME);

// ... Specify additional connection properties here.

// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

const createPool = async () => {
  const config = {pool: {}, options: {}};
  config.user = process.env.DB_USER; // e.g. 'my-db-user'
  config.password = process.env.DB_PASS; // e.g. 'my-db-password'
  config.database = process.env.DB_NAME; // e.g. 'my-database'
  // set the server to '172.17.0.1' when connecting from App Engine Flex
  config.server = process.env.DEPLOYED ? '172.17.0.1' : '127.0.0.1';
  config.port = 1433;

  // ...
  config.options.trustServerCertificate = true;
  return await mssql.connect(config);
};

Go

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	dbPort    = mustGetenv("DB_PORT") // e.g. '1433'
	dbName    = mustGetenv("DB_NAME") // e.g. 'my-database'
)

dbURI := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;", dbTCPHost, dbUser, dbPwd, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("mssql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                DataSource = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // ...
            return connectionString;

Ruby

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

development:
  adapter: sqlserver
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

このスニペットをウェブ アプリケーションのコンテキストで表示するには、GitHub の README をご覧ください。

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('sqlsrv:server=%s;Database=%s', $dbHost, $dbName);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

その他のトピック

Cloud SQL Auth Proxy のコマンドライン引数

これまでの例は最も一般的なユースケースを対象としていますが、Cloud SQL Auth Proxy にはコマンドライン引数で設定できる構成オプションが他にもあります。コマンドライン引数のヘルプについては、-help フラグを使用して最新のドキュメントをご覧ください。

./cloud_sql_proxy -help

Cloud SQL Auth Proxy コマンドライン オプションの使用方法のその他の例については、Cloud SQL Auth Proxy GitHub リポジトリの README をご覧ください。

Cloud SQL Auth Proxy の認証オプション

これらのオプションではすべて、Cloud SQL インスタンスを識別するための接続文字列として INSTANCE_CONNECTION_NAME を使用します。INSTANCE_CONNECTION_NAME は、Google Cloud Console のインスタンスの [概要] ページに表示されます。また、次のコマンドを実行して確認することもできます。

gcloud sql instances describe INSTANCE_NAME --project PROJECT_ID

例: gcloud sql instances describe myinstance --project myproject

これらのオプションの中には、アカウントの RSA 秘密鍵を含む JSON 認証情報ファイルを使用するものもあります。サービス アカウントの JSON 認証情報ファイルを作成する手順については、サービス アカウントの作成をご覧ください。

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

  1. credential_file フラグによって指定された認証情報。

    サービス アカウントを使用して、関連付けられた JSON ファイルを作成してダウンロードし、Cloud SQL Auth Proxy を起動するとき、そのファイルのパスに -credential_file フラグを設定します。サービス アカウントには、Cloud SQL インスタンスに対する必要な権限が付与されていることが必要です。

    コマンドラインでこのオプションを使用するには、-credential_file フラグを JSON 認証情報ファイルのパスとファイル名に設定して、cloud_sql_proxy コマンドを呼び出します。パスは現在の作業ディレクトリへの絶対パス、または相対パスとして設定できます。例:

    ./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME
      

    サービス アカウントに IAM ロールを追加する方法の詳細については、サービス アカウントへのロールの付与をご覧ください。

    Cloud SQL でサポートされるロールの詳細については、Cloud SQL のプロジェクトのアクセス制御をご覧ください。

  2. アクセス トークンによって指定された認証情報。

    アクセス トークンを作成し、OAuth 2.0 アクセス トークンに -token フラグを設定して cloud_sql_proxy コマンドを呼び出します。例:
    ./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME
      
  3. 環境変数によって指定された認証情報。

    このオプションは、-credential_file コマンドライン引数を使用する代わりに、GOOGLE_APPLICATION_CREDENTIALS 環境変数で設定する JSON 認証情報ファイルを指定する点を除けば、-credential_file フラグを使用する場合と類似しています。
  4. 認証済みの Cloud SDK クライアントの認証情報。

    Cloud コマンドライン ツールをインストールし、個人アカウントで認証した場合は、Cloud SQL Auth Proxy で同じアカウント認証情報を使用できます。この方法は、開発環境の運用を開始する際に特に便利です。

    gcloud auth login 用のアカウントが選択されていない場合は、Cloud SQL Auth Proxy によって gcloud auth application-default login 用に選択されているアカウントがチェックされます。

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

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

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

  6. 環境のデフォルトのサービス アカウント

    前述のいずれの場所でも認証情報を見つけることができない場合、Cloud SQL Auth Proxy はサーバー間での本番環境アプリケーションの認証の設定に記載されたロジックに従います。一部の環境(Compute Engine、App Engine など)では、アプリケーションがデフォルトで認証に使用できるデフォルトのサービス アカウントが用意されています。デフォルトのサービス アカウントを使用する場合は、アカウントにロールと権限で概説している権限が付与されている必要があります。Google Cloud の認証のアプローチについて詳しくは、認証の概要をご覧ください。

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

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

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

  2. Cloud SQL インスタンスを含むプロジェクトを選択します。
  3. [サービス アカウントを作成] をクリックします。
  4. [サービス アカウントの作成] ダイアログで、わかりやすいサービス アカウント名を指定します。
  5. [サービス アカウント ID] を一意のわかりやすい値に変更してから、[作成] をクリックします。
  6. [ロール] には、次のいずれかのロールを選択してから、[続行] をクリックし、[完了] をクリックします。
    • [Cloud SQL] > [Cloud SQL クライアント]
    • [Cloud SQL] > [Cloud SQL 編集者]
    • [Cloud SQL] > [Cloud SQL 管理者]
  7. 新しいサービス アカウントの操作メニューをクリックし、[鍵を管理] を選択します。
  8. [鍵を追加] プルダウン メニューをクリックして、[新しい鍵を作成] をクリックします。
  9. 鍵のタイプが JSON であることを確認し、[作成] をクリックします。

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

プライベート IP での Cloud SQL Auth Proxy の使用

プライベート IP を使用して Cloud SQL インスタンスに接続するには、Cloud SQL Auth Proxy が、そのインスタンスと同じ VPC ネットワークにアクセスできるリソース上に存在する必要があります。

Cloud SQL Auth Proxy は、IP を使用して Cloud SQL インスタンスとの接続を確立します。デフォルトでは、Cloud SQL Auth Proxy は、パブリック IPv4 アドレスを使用して接続を試行します。Cloud SQL インスタンスにプライベート IP しかない場合、Cloud SQL Auth Proxy は、プライベート IP アドレスを使用して接続します。

インスタンスにパブリック IP とプライベート IP の両方が構成されている場合に、Cloud SQL Auth Proxy によってプライベート IP アドレスが使用されるようにするには、Cloud SQL Auth Proxy の起動時に次のオプションを指定する必要があります。

-ip_address_types=PRIVATE

別のプロセスでの Cloud SQL Auth Proxy の実行

Cloud SQL Auth Proxy を別のターミナル プロセスで実行することはコンソール出力と他のプログラムからの出力が混在するのを回避するうえで有用な可能性があります。以下の構文を使用して、別のプロセスで Cloud SQL Auth Proxy を呼び出します。

Linux

Linux または macOS の場合、コマンドラインで末尾の & を使用して Cloud SQL Auth Proxy を別のプロセスで起動します。

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

Windows PowerShell で、Start-Process コマンドを使用して、別のプロセスで Cloud SQL Auth Proxy を起動します。

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Docker コンテナでの Cloud SQL Auth Proxy の実行

Docker コンテナで Cloud SQL Auth Proxy を動作させるには、Google Container Registry から入手できる Cloud SQL Auth Proxy Docker イメージを使用します。Cloud SQL Auth Proxy Docker イメージは、次の gcloud コマンドを使用してインストールできます。

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

次のコマンドで、TCP ソケットまたは Unix ソケットのどちらかを使用して、Cloud SQL Auth Proxy を起動できます。

TCP ソケット

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:1433:1433 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 \
      -credential_file=/config

Unix ソケット

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

コンテナ最適化イメージを使用している場合は、/cloudsql の代わりに書き込み可能なディレクトリを使用します。たとえば、次のようにします。

-v /mnt/stateful_partition/cloudsql:/cloudsql

Compute Engine インスタンスによって提供される認証情報を使用している場合は、credential_file パラメータと -v PATH_TO_KEY_FILE:/config の行を含めないでください。

Cloud SQL Auth Proxy をサービスとして動作させる

Cloud SQL Auth Proxy をバックグラウンド サービスとして実行すると、ローカルでの開発とテストに役立ちます。Cloud SQL インスタンスにアクセスする必要がある場合は、バックグラウンドでサービスを開始し、終了したらサービスを停止できます。

  • Cloud SQL Auth Proxy には現在、Windows サービスとして動作する組み込みのサポートはありませんが、サードパーティのサービス マネージャーを使用することで、サービスとしての動作が可能です。たとえば、NSSM を使用して Cloud SQL Auth Proxy を Windows のサービスとして構成できます。NSSM が Cloud SQL Auth Proxy をモニタリングし、応答しなくなった場合は自動的に再起動します。詳細については、NSSM のドキュメントをご覧ください。

SSL が必要なときの接続

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

Cloud SQL Auth Proxy を使用した複数のインスタンスへの接続

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

TCP ソケット

TCP を使用して接続する場合は、Cloud SQL Auth プロキシが Cloud SQL インスタンスごとにリッスンするマシン上のポートを指定します。複数の Cloud SQL インスタンスに接続する場合は、指定された各ポートが一意であり、マシンで使用できる必要があります。

例:

    # Start the Cloud SQL Auth proxy to connect to two different Cloud SQL instances.
    # Give the Cloud SQL Auth proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:1433,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 1433 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1433"

    # Connect to "myInstance2" using port 1234 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1234"
  

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

Cloud SQL Auth Proxy Docker イメージは、Cloud SQL Auth Proxy の特定のバージョンに基づいています。Cloud SQL Auth Proxy の新しいバージョンが利用可能になったら、Cloud SQL Auth Proxy Docker イメージの新しいバージョンを pull して、環境を最新の状態に保ってください。Cloud SQL Auth Proxy の最新バージョンは Cloud SQL Auth Proxy GitHub リリースページで確認できます。

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

  • Cloud SQL Auth Proxy の出力を確認します。

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

  • 403 notAuthorized エラーが発生し、サービス アカウントを使用して Cloud SQL Auth Proxy を認証する場合は、サービス アカウントに正しい権限が付与されていることを確認します。

    サービス アカウントを確認するには、IAM ページでその ID を検索します。cloudsql.instances.connect 権限が必要です。この権限は、事前定義ロールの Cloud SQL AdminClientEditor に含まれています。

  • App Engine から接続する際に 403 notAuthorized エラーが発生した場合は、app.yaml の値 cloud_sql_instances にスペルミスや不正なインスタンス接続名がないか確認してください。インスタンス接続名は常に PROJECT:REGION:INSTANCE の形式です。

    また、App Engine サービス アカウント(たとえば、$PROJECT_ID@appspot.gserviceaccount.com)に Cloud SQL クライアント IAM ロールがあることを確認します。

    App Engine サービスが 1 つのプロジェクト(プロジェクト A)に存在し、データベースは別のプロジェクト(プロジェクト B)にある場合、このエラーは、App Engine サービス アカウントには、そのデータベース(プロジェクト B)があるプロジェクトにおいて Cloud SQL クライアント IAM のロールが付与されていないことを意味します。

  • 必ず Cloud SQL Admin API を有効にしてください。

    有効になっていない場合は、Cloud SQL Auth Proxy に Error 403: Access Not Configured のような出力が含まれています。

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

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

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

  • Google Cloud Console の [オペレーション] > [ロギング] > [ログ エクスプローラ] でログを調べることで、Cloud SQL Auth プロキシが正しく開始されていることを確認できます。正常なオペレーションは次のようになります。

    2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/1433 for $PROJECT_ID:$REGION:$INSTANCE_NAME
    2021/06/14 15:47:56 Ready for new connections
    
  • 割り当ての問題: Cloud SQL Admin API の割り当てに違反していると、Cloud SQL Auth プロキシは次のエラー メッセージで起動します。

    There was a problem when parsing a instance configuration but ignoring due
    to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
    metric 'Queries' and limit 'Queries per minute per user' of service
    'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
    rateLimitExceeded
    

    アプリケーションがプロキシに接続すると、プロキシから次のエラーが報告されます。

    failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
    googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
    'Queries per minute per user' of service 'sqladmin.googleapis.com' for
    consumer 'project_number:$PROJECT_ID., rateLimitExceeded
    

    解決策: 割り当ての問題の原因(たとえば、アプリケーションがコネクタを誤って使用していて、不要な新しい接続を作成している場合があります)を特定するか、サポートに連絡して Cloud SQL Admin API 割り当ての増加をリクエストします。起動時に割り当てエラーが発生した場合は、アプリケーションを再デプロイしてプロキシを再起動する必要があります。起動後に割り当てエラーが発生した場合、再デプロイは必要ありません。

次のステップ