このページでは、AlloyDB Auth Proxy を設定して使用し、AlloyDB インスタンスに対して承認済みの暗号化された接続を確立する方法について説明します。Auth Proxy のコンセプトの概要については、AlloyDB Auth Proxy についてをご覧ください。
AlloyDB Auth Proxy を使用するには、1 回限りの設定をいくつか行った後、Auth Proxy クライアントを起動して、そのクライアントからデータベースに接続します。
- 設定手順は次のとおりです。
- クライアント ホストに Auth Proxy クライアントをダウンロードします。
- 認可に使用する Identity and Access Management(IAM)プリンシパルを選択します。このプリンシパルに必要な権限があることを確認し、クライアント ホストでその認証情報を使用できるようにします。
- 接続する AlloyDB インスタンスの接続 URI を収集します。
- クライアント ホストで Auth Proxy クライアントを起動します。
- Auth Proxy クライアントとのローカル接続を開いて、アプリケーションをデータベースに接続します。
始める前に
-
クライアント ホストは次の要件を満たしている必要があります。
接続先のインスタンスが存在する Virtual Private Cloud(VPC)ネットワークに対してネットワークの可視性が必要です。この Virtual Private Cloud(VPC)ネットワーク内のクライアント ホスト(Compute Engine インスタンスなど)には、本質的にこの可視性があります。AlloyDB インスタンスの VPC ネットワークが Cloud VPN トンネルか、Dedicated Interconnect または Partner Interconnect の VLAN アタッチメントを介して外部ネットワークに接続している場合、外部ネットワーク(オンプレミス ネットワークまたは別の VPC ネットワーク)のクライアント ホストにはこの可視性があります。
クライアント ホストにアウトバウンド ファイアウォール ポリシーがある場合は、AlloyDB インスタンスの IP アドレスからポート
5433
への送信接続が許可されている必要があります。また、ポート443
(標準 HTTPS ポート)を介してすべての IP アドレスへの送信接続も許可されている必要があります。Compute Engine インスタンスをクライアント ホストとして使用している場合は、AlloyDB Admin API を使用できるように
https://www.googleapis.com/auth/cloud-platform
アクセス スコープが必要です。必要に応じて、このスコープを含むようにアクセス スコープを変更します。
Auth Proxy クライアントをダウンロードする
Auth Proxy クライアントをダウンロードするマシンは、VPC ネットワークの内部から AlloyDB インスタンスに接続するか、外部から接続するかによって異なります。
プライベート サービス アクセスを使用してクラスタに接続する場合は、クラスタに対するプライベート サービス アクセス権を持ち、VPC ネットワーク内で実行されている Compute Engine 仮想マシン(VM)インスタンスに Auth Proxy クライアントをダウンロードできます。
VPC の外部からクラスタに接続する場合、クラスタをインストールするマシンは、使用する外部接続によって異なります。たとえば、アプリケーションに近い macOS マシンまたは Windows マシンに Auth Proxy クライアントをインストールし、接続の中継として AlloyDB VPC ネットワーク内で実行されている SOCKS サーバーを使用できます。詳細については、VPC の外部からクラスタに接続するをご覧ください。
Linux
64 ビット(AMD)
Auth Proxy クライアントをダウンロードします。
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
32 ビット(AMD)
Auth Proxy クライアントをダウンロードします。
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
64 ビット(ARM)
Auth Proxy クライアントをダウンロードします。
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
32 ビット(ARM)
Auth Proxy クライアントをダウンロードします。
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
macOS
M1
Auth Proxy クライアントをダウンロードします。
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.darwin.arm64
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
64 ビット
Auth Proxy クライアントをダウンロードします。
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.darwin.amd64
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
32 ビット
Auth Proxy クライアントをダウンロードします。
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy.darwin.386
Auth Proxy クライアントを実行可能にします。
chmod +x alloydb-auth-proxy
Windows
64 ビット
https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy-x64.exe を右クリックして [名前を付けてリンク先を保存] を選択し、Auth Proxy クライアントをダウンロードします。ファイル名を alloydb-auth-proxy.exe
に変更します。
32 ビット
https://storage.googleapis.com/alloydb-auth-proxy/v1.13.1/alloydb-auth-proxy-x86.exe を右クリックして [名前を付けてリンク先を保存] を選択し、Auth Proxy クライアントをダウンロードします。ファイル名を alloydb-auth-proxy.exe
に変更します。
Docker イメージ
Auth Proxy クライアントを含む複数のコンテナ イメージは Container Registry で入手できます。
Docker で次のコマンドを使用して、最新のイメージをローカルマシンに pull できます。
docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest
その他の OS
ここに記載されていないその他のオペレーティング システムの場合は、Auth Proxy クライアントをソースからコンパイルできます。
IAM プリンシパルを選択して認可の準備を行う
AlloyDB Auth Proxy では、次のタイプの IAM プリンシパルを使用して、クライアントと AlloyDB インスタンス間の接続を認可できます。
ユーザー管理のサービス アカウント。アプリケーションに IAM サービス アカウントを作成し、そのアカウントを使用して接続を認可できます。
本番環境での認可には、サービス アカウントを使用することを強くおすすめします。
ユーザー アカウント。独自の IAM ユーザー アカウントを使用して接続を認可できます。
gcloud CLI を使用して AlloyDB リソースを管理し、
psql
などのツールでデータベースの開発を行い、アプリケーション コードをすべて同じホストで開発する開発環境では、独自のユーザー アカウントを使用すると便利です。Compute Engine のデフォルトのサービス アカウント。クライアント ホストが Compute Engine インスタンスの場合は、Compute Engine のデフォルトのサービス アカウントを使用して接続を認可できます。
使用する IAM プリンシパルを選択したら、必要な IAM 権限があることを確認し、クライアント ホストで認証情報を使用できるようにする必要があります。
必要な IAM 権限
接続の認可に使用する IAM プリンシパルには、roles/alloydb.client
(Cloud AlloyDB クライアント)と roles/serviceusage.serviceUsageConsumer
(Service Usage コンシューマー)の事前定義ロールによって提供される権限が必要です。
Cloud AlloyDB クライアントのロールを IAM プリンシパルに割り当てるには:
Google Cloud プロジェクトで Cloud Resource Manager API が有効になっている必要があります。
Google Cloud プロジェクトに
roles/owner
(オーナー)IAM 基本ロールか、次の権限を付与するロールが必要です。resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.setIamPolicy
最小権限の原則に従ってこれらの権限を取得するには、
roles/resourcemanager.projectIamAdmin
(プロジェクト IAM 管理者)ロールを付与するよう管理者に依頼してください。
クライアント ホストで IAM 認証情報を使用できるようにする
クライアント ホストで IAM 認証情報を使用できるようにする方法は、接続の認可に使用している IAM プリンシパルの種類によって異なります。
ユーザー管理のサービス アカウント
ユーザー管理のサービス アカウントの IAM 認証情報を使用するには、JSON 形式のサービス アカウント キーを作成し、クライアント ホストにダウンロードします。Auth Proxy クライアントを起動するときに、
--credentials-file
フラグを使用して鍵ファイルの場所を指定します。ユーザー アカウント
ユーザー アカウントの IAM 認証情報を使用するには、クライアント ホストに Google Cloud CLI をインストールして
gcloud init
コマンドを実行し、ユーザー アカウントを使用して初期化を行います。Auth Proxy クライアントを起動するときに、ユーザー管理のサービス アカウントの認証情報を指定しない場合、ユーザー アカウントの認証情報が自動的に検出され、使用されます。Compute Engine のデフォルトのサービス アカウント
クライアント ホストとして Compute Engine インスタンスを使用している場合、ホストには Compute Engine のデフォルトのサービス アカウントの認証情報がすでに設定されています。Auth Proxy クライアントを起動するときに、ユーザー管理のサービス アカウントとユーザー アカウントの認証情報を使用できない場合、Compute Engine のデフォルトのサービス アカウントの認証情報が自動的に検出され、使用されます。
AlloyDB インスタンスの接続 URI を収集する
Auth Proxy クライアントを起動するときに、接続する AlloyDB インスタンスを次の形式の接続 URI で指定します。
projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
すべてのインスタンスの接続 URI のリストを確認するには、gcloud CLI の alloydb instances list
コマンドを使用します。
接続する各インスタンスの接続 URI を収集します。
Auth Proxy クライアントを起動する
Auth Proxy クライアントを起動するときに、接続する AlloyDB インスタンスに関する情報を指定します。また、必要に応じて、これらの接続の認可に使用する認証情報も指定します。
Auth Proxy クライアントは、起動後に次の処理を行います。
- 構成済みの IAM プリンシパルの認証情報と IAM 権限を使用して、AlloyDB インスタンスへの接続を認可します。一連の手順を踏んで認証情報を検索します。
- インスタンスでパブリック IP が有効になっている場合は、接続元ネットワークへのパブリック IP 接続を自動的に認可します。
- 各インスタンスの Auth Proxy サーバーにプライベート TLS 1.3 接続を構成します。
- ローカル クライアントの接続リクエストのリッスンを開始します。
デフォルトでは、Auth Proxy クライアントは IP アドレス 127.0.0.1 で TCP 接続をリッスンします。ポート番号は 5432 から始まり、以降の AlloyDB インスタンスではインスタンスごとに番号を 1 つずつ大きくしていきます。Auth Proxy クライアントの起動時に、別のリスナー アドレスとポートを指定することもできます。
コマンドライン
./alloydb-auth-proxy INSTANCE_URI... \
[ --credentials-file PATH_TO_KEY_FILE \ ]
[ --token OAUTH_ACCESS_TOKEN \ ]
[ --port INITIAL_PORT_NUMBER \ ]
[ --address LOCAL_LISTENER_ADDRESS \ ]
[ --auto-iam-authn ] \
[ --psc] \
[ --public-ip]
次のように置き換えます。
INSTANCE_URI
: 接続先の AlloyDB インスタンスの接続 URI。次の形式で指定します。projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
Auth Proxy クライアントがインスタンスに使用するデフォルトのローカル リスナー ポートをオーバーライドする場合は、URI に
port
クエリ パラメータを追加します。"projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"
省略可:
PATH_TO_KEY_FILE
: 接続の認可に使用するユーザー管理のサービス アカウントの JSON 鍵ファイルのパス。省略可:
OAUTH_ACCESS_TOKEN
: 接続の認可に使用する OAuth2 トークンの値。省略可:
INITIAL_PORT_NUMBER
: ローカル TCP 接続をリッスンするときに、デフォルトのポート5432
の代わりに使用する開始ポート番号。省略可:
LOCAL_LISTENER_ADDRESS
: ローカル TCP 接続をリッスンするときに、デフォルトの127.0.0.1
の代わりに使用するリスナー アドレス。
オプションの --auto-iam-authn
フラグを使用すると、インスタンスの自動認証が可能です。これは、Auth Proxy クライアントを実行している IAM アカウントに関連付けられているデータベース ユーザーでのみ機能します。詳細については、Auth Proxy を使用して自動的に認証するをご覧ください。
オプションの --psc
フラグを使用すると、Auth Proxy は Private Service Connect が有効になっているインスタンスに接続できます。Private Service Connect で DNS を設定する方法については、DNS マネージド ゾーンと DNS レコードを構成するをご覧ください。
オプションの --public-ip
フラグを使用すると、Auth Proxy はインスタンスのパブリック IP アドレスを使用して、パブリック IP が有効になっているインスタンスに接続できます。パブリック IP の詳細については、パブリック IP を使用して接続するをご覧ください。
Docker コンテナ
docker run
コマンドを使用して Auth Proxy クライアントを起動します。
Compute Engine インスタンスから提供される認証情報を使用する場合は、次のようなコマンドを使用できます。
docker run \
--publish 127.0.0.1:PORT:PORT \
gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
--address 0.0.0.0 \
--port PORT \
INSTANCE_URI
次のように置き換えます。
PORT
: Auth Proxy クライアントへのローカル接続に使用するポート。デフォルトは5432
です。INSTANCE_URI
: 接続先の AlloyDB インスタンスの接続 URI。次の形式で指定します。projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
Auth Proxy クライアントがインスタンスに使用するデフォルトのローカル リスナー ポートをオーバーライドする場合は、URI に
port
クエリ パラメータを追加します。"projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"
Auth Proxy クライアントがローカルホストの外部に公開されないように、常に --publish
フラグに 127.0.0.1
接頭辞を指定します。
--address
フラグの 0.0.0.0
値は、Docker コンテナの外部からリスナーにアクセスできるようにするために必要です。
ローカル JSON ファイルに保存した認証情報を指定するには、docker run
コマンドを実行するときに --volume
フラグと --credentials-file
フラグを指定します。
docker run \
--volume PATH_TO_KEY_FILE:/key.json \
--publish 127.0.0.1:PORT:PORT \
gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
--address 0.0.0.0 \
--port PORT \
--credentials-file=/key.json \
INSTANCE_URI
PATH_TO_KEY_FILE
は、接続の認可に使用するユーザー管理のサービス アカウントの JSON 鍵ファイルのパスに置き換えます。
起動例
ここでは、Auth Proxy クライアントを起動する方法をいくつか紹介します。これらの例では、次のインスタンス接続 URI を使用します。
projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary
projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool
基本的な起動
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"
この例では、Auth Proxy クライアントは通常の認可手順の順序で接続を認可し、127.0.0.1:5432
で myprimary
インスタンスへのローカル接続のリッスンを開始します。
ユーザー管理のサービス アカウントを使用した起動
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
--credentials-file "myappaccount/key.json"
この例では、Auth Proxy クライアントは myappaccount/key.json
に保存されているユーザー管理のサービス アカウントの JSON 鍵を使用して接続を認可し、127.0.0.1:5432
で myprimary
インスタンスへのローカル接続のリッスンを開始します。
起動時に複数のインスタンスに接続する
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"
この例では、Auth Proxy クライアントは通常の認可手順の順序で接続を認可し、127.0.0.1:5432
で myprimary
インスタンス、127.0.0.1:5433
で myreadpool
インスタンスへのローカル接続のリッスンをそれぞれ開始します。
起動後にカスタムポートでリッスンする
他の PostgreSQL 接続用にポート 5432
を予約する必要がある場合は、Auth Proxy クライアントにカスタムポートを使用すると便利です。
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"
この例では、Auth Proxy クライアントは通常の認可手順の順序で接続を認可し、127.0.0.1:5000
で myprimary
インスタンス、127.0.0.1:5001
で myreadpool
インスタンスへのローカル接続のリッスンをそれぞれ開始します。
これらのカスタムポートは連続しているため、次の起動コマンドを使用すると、同じ効果を得ることができます。
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
--port 5000
起動後にカスタム IP アドレスでリッスンする
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
--address "0.0.0.0"
この例では、Auth Proxy クライアントは通常の認可手順の順序で接続を認可し、0.0.0.0:5432
で myprimary
インスタンスへのローカル接続のリッスンを開始します。
AlloyDB Auth Proxy を使用してアプリケーションをデータベースに接続する
次の例は、AlloyDB Auth Proxy を使用してアプリケーションをデータベースに接続する方法を示しています。
psql
の例は、コマンドライン ツールを接続する例を示しています。
いくつかのプログラミング言語では、AlloyDB Auth Proxy を使用して AlloyDB インスタンスに接続することは、Cloud SQL Auth Proxy を使用して Cloud SQL for PostgreSQL に接続することと同じです。そのため、ここで紹介する言語の例は Cloud SQL for PostgreSQL の場合と同じです。
これらの例は、Auth Proxy クライアントのデフォルトの起動に基づいており、127.0.0.1:5432
でローカル TCP 接続をリッスンします。
psql
psql -h 127.0.0.1 -p 5432 -U DB_USER
DB_USER
は、接続するデータベース ユーザー(postgres
など)に置き換えます。
DB_USER
ユーザーのパスワードを入力するように求められます。
Python
Java
Node.js
Go
このスニペットをウェブ アプリケーションのコンテキストで表示する方法については、GitHub の README をご覧ください。
C#
このスニペットをウェブ アプリケーションのコンテキストで表示する方法については、GitHub の README をご覧ください。
Ruby
このスニペットをウェブ アプリケーションのコンテキストで表示する方法については、GitHub の README をご覧ください。
PHP
このスニペットをウェブ アプリケーションのコンテキストで表示する方法については、GitHub の README をご覧ください。