Connect using the AlloyDB Auth Proxy

This page shows how to set up and use the AlloyDB Auth Proxy to make authorized, encrypted connections to AlloyDB instances.

To use the AlloyDB Auth Proxy, you perform several one-time setup steps, then you start the Auth Proxy client, and then you connect to databases using it:

1. Setup steps:
   1. Download the Auth Proxy client to your client host.
   2. Choose the IAM principal to use for authorization, make sure it has the required permissions, and make its credentials are available on your client host.
   3. Gather connection URIs for the AlloyDB instances you want to connect to.
2. Start the Auth Proxy client on your client host.
3. Connect an application to a database by opening a local connection to the Auth Proxy client.

Before you begin

The client host must meet these requirements:

• It must have network visibility to the VPC network where the instances you want to connect to reside. Client hosts (like Compute Engine instances) in this VPC network inherently have this visibility. Client hosts in external networks (on-premises networks or different VPC networks) have this visibility if the AlloyDB instance's VPC network has been connected to the external network using a Cloud VPN tunnel or a VLAN attachment for Dedicated Interconnect or Partner Interconnect.
• If the client host has an outbound firewall policy, it must allow outgoing connections to port 5433 on your AlloyDB instances' IP addresses and allow outgoing connections to port 443 (the standard HTTPS port) to all IP addresses.
• If you are using a Compute Engine instance as the client host, it must have the https://www.googleapis.com/auth/cloud-platform access scope so that it can use the AlloyDB API. If necessary, change its access scope to include this scope.

Download the Auth Proxy client

Linux

64-bit (AMD)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
         

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
           

32-bit (AMD)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy
         

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
           

64-bit (ARM)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy
         

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
           

32-bit (ARM)

1. Download the Auth Proxy client:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy
         

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
           

macOS

M1

1. Download the Auth Proxy client:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.darwin.arm64
             

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
             

64-bit

1. Download the Auth Proxy client:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.darwin.amd64
           

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
           

32-bit

1. Download the Auth Proxy client:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy.darwin.386
           

2. Make the Auth Proxy client executable:

   chmod +x alloydb-auth-proxy
           

Windows

64-bit

Right-click https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy-x64.exe and select Save Link As to download the Auth Proxy client. Rename the file to alloydb-auth-proxy.exe.

32-bit

Right-click https://storage.googleapis.com/alloydb-auth-proxy/v1.2.4/alloydb-auth-proxy-x86.exe and select Save Link As to download the Auth Proxy client. Rename the file to alloydb-auth-proxy.exe.

Docker image

For convenience, several container images that contain the Auth Proxy client are available in the Container Registry. You can pull the latest image to your local machine using Docker with the following command:

docker pull  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Other OS

For other operating systems not included here, you can compile the Auth Proxy client from source.

Choose the IAM principal and prepare it for authorization

The AlloyDB Auth Proxy supports the use of these types of IAM principals to authorize connections between your client and an AlloyDB instance:

• A user-managed service account. You can create an IAM service account for your application and then authorize connections using it.

  Google strongly recommends that you use a service account for authorization in production environments.

• Your user account. You can use your own IAM user account to authorize connections.

  Using your own user account is convenient in development environments where you are managing AlloyDB resources using the gcloud CLI, developing the database using a tool like psql, and developing application code all on the same host.

• The Compute Engine default service account. If the client host is a Compute Engine instance, you can use the Compute Engine default service account to authorize connections.

After choosing which IAM principal to use, you need to make sure it has the required IAM permissions and make its credentials are available on your client host.

Required IAM permissions

The IAM principal you use to authorize connections must have the permissions provided by the roles/alloydb.client (Cloud AlloyDB Client) predefined role.

Note: The roles/alloydb.admin (Cloud AlloyDB Admin) role also provides the required permissions.

In order to assign the Cloud AlloyDB Client role to an IAM principal:

• The Resource Manager API must be enabled in the Google Cloud project.
• You must have the roles/owner (Owner) basic IAM role in the Google Cloud project, or a role that grants these permissions:
  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  To gain these permissions while following the principle of least privilege, ask your administrator to grant you the roles/resourcemanager.projectIamAdmin (Project IAM Admin) role.

Make IAM credentials available on the client host

How you make IAM credentials available on the client host depends on which type of IAM principal you are using to authorize connections:

• User-managed service account

  To provide IAM credentials for a user-managed service account, create a JSON-format service account key and download it to your client host. When you start the Auth Proxy client, specify the location of the key file using the --credentials-file flag.

• Your user account

  To provide IAM credentials for your user account, install the Google Cloud CLI on your client host and then run the gcloud init command to initialize it using your user account. When you start the Auth Proxy client, it automatically discovers and uses your user account credentials if you don't provide user-managed service account credentials.

• Compute Engine default service account

  If you are using a Compute Engine instance as your client host, the credentials for Compute Engine default service account are already on the host. When you start the Auth Proxy client, it automatically discovers and uses these credentials if user-managed service account and user account credentials are unavailable.

Gather connection URIs for the AlloyDB instances

When you start the Auth Proxy client, you identify the AlloyDB instance or instances you want to connect to using this connection URI format:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

To see a list of all of your instances' connection URIs, use the gcloud CLI beta alloydb instances list command.

Gather the instance connection URI for each instance you want to connect to.

Start the Auth Proxy client

When you start the Auth Proxy client, you provide it information about what AlloyDB instances to connect to and, if necessary, credential information to use when authorizing these connections.

When it starts, the Auth Proxy client:

• Authorizes connections to AlloyDB instances using the credentials and IAM permissions of the IAM principal you have configured. It looks for credentials by following a specific sequence of steps.
• Configures a private, TLS 1.3 connection to each instance's Auth Proxy server.
• Begins listening for local client connection requests.

By default, the Auth Proxy client listens for TCP connections on IP address 127.0.0.1, starting at port 5432 and incrementing by one port number for each AlloyDB instance beyond the first. You can specify a different listener address and different ports when you start the Auth Proxy client.

Warning: Be careful when binding the Auth Proxy client to an external interface. Anyone with access to that interface/port will be authorized to connect to your instance.

Google recommends that you run the Auth Proxy client as a persistent service in production environments.

Command line

./alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS ]

• INSTANCE_URI: The instance connection URI of an AlloyDB instance to connect to, specified using this format:

  projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  You can override the default local listener port that the Auth Proxy client will use for the instance by adding the port query parameter to the URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• (Optional) PATH_TO_KEY_FILE: The path to the JSON key file of the user-managed service account to use for connection authorization.
• (Optional) OAUTH_ACCESS_TOKEN: An OAuth2 token value to use for connection authorization.
• (Optional) INITIAL_PORT_NUMBER: The starting port number to use instead of the default port 5432 when listening for local TCP connections.
• (Optional) LOCAL_LISTENER_ADDRESS: The listener address to use instead of the default 127.0.0.1 when listening for local TCP connections.

Docker container

Start the Auth Proxy client using this docker run command.

docker run -d \
  -v PATH_TO_KEY_FILE:/config \
  -c=/config \
  -p 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:VERSION_TAG \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

If you are using the credentials provided by your Compute Engine instance, do not include the -v PATH_TO_KEY_FILE:/config or -credential_file=/config flags.

Always specify 127.0.0.1 prefix in the -p flag so that the Auth Proxy client is not exposed outside the local host. The 0.0.0.0 value in the --address flag is required to make the listener accessible from outside of the Docker container.

Startup Examples

The following examples show various ways to start the Auth Proxy client. They use these example instance connection URIs:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary
projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Basic startup

./alloydb-auth-proxy \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 127.0.0.1:5432.

Startup using a user-managed service account

./alloydb-auth-proxy \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  --credentials-file "myappaccount/key.json"

In this example, the Auth Proxy client authorizes the connection using the user-managed service account's JSON key stored at myappaccount/key.json and then starts listening for local connections to the myprimary instance on 127.0.0.1:5432.

Startup connecting to multiple instances

./alloydb-auth-proxy \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 127.0.0.1:5432 and to the myreadpool instance on 127.0.0.1:5433.

Startup listening on custom ports

Tip: Using custom ports for the Auth Proxy client can be useful when you need to reserve port 5432 for other PostgreSQL connections.

./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"

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 127.0.0.1:5000 and to the myreadpool instance on 127.0.0.1:5001.

Because these custom ports are sequential, the same effect can be achieved using this startup command:

./alloydb-auth-proxy \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \\
  --port 5000

Startup listening on a custom IP address

./alloydb-auth-proxy \\
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  --address "0.0.0.0"

In this example, the Auth Proxy client authorizes the connection by following its normal sequence of authorization steps and then starts listening for local connections to the myprimary instance on 0.0.0.0:5432.

Connect an application to a database using the AlloyDB Auth Proxy

The following examples show how you can connect an application to a database using the AlloyDB Auth Proxy.

The psql example provides an example of connecting a command-line tool.

Connecting to an AlloyDB instance using the AlloyDB Auth Proxy is, for several programming languages, identical to connecting to a Cloud SQL for PostgreSQL using the Cloud SQL Auth proxy, so the language examples here are the same as those for Cloud SQL for PostgreSQL.

These examples are based on a default startup of the Auth Proxy client so that it is listening for local TCP connections on 127.0.0.1:5432.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER -d DB_NAME

You will be prompted to enter the password of the DB_USER user.

Python

To see this snippet in the context of a web application, view the README on GitHub.

examples/python/connect_tcp.py

View on GitHub

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    INSTANCE_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

To see this snippet in the context of a web application, view the README on GitHub.

examples/java/src/main/java/com/example/alloydb/TcpConnectionPoolFactory.java

View on GitHub

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

To see this snippet in the context of a web application, view the README on GitHub.

examples/nodejs/connect-tcp.js

View on GitHub

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

To see this snippet in the context of a web application, view the README on GitHub.

examples/go/connect_tcp.go

View on GitHub

package alloydb

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v4/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

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

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

	// ...

	return dbPool, nil
}

C#

To see this snippet in the context of a web application, view the README on GitHub.

cloud-sql/postgres/ConnectTcp.cs

View on GitHub

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

To see this snippet in the context of a web application, view the README on GitHub.

cloud-sql/postgres/activerecord/config/database.yml

View on GitHub

development:
  adapter: postgresql
  # 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")  { 5432 }%>

PHP

To see this snippet in the context of a web application, view the README on GitHub.

cloud_sql/postgres/pdo/src/DBInitializer.php

View on GitHub

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

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

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