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. For a conceptual overview of the Auth Proxy, see About the AlloyDB Auth Proxy.

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.

Download the Auth Proxy client

The machine that you download the Auth Proxy client to depends on whether you want to connect to your AlloyDB instances from within its VPC network, or from outside of it.

If you want to connect to your cluster using private services access, then you can download the Auth Proxy client onto a Compute Engine virtual machine (VM) instance running within the VPC network that has private services access to your cluster.

If you intend to connect to your cluster from outside the VPC, then the machine you install it on depends on which external connection strategy you use. For example, you can install the Auth Proxy client onto a macOS or Windows machine that's local to your application, and then use a SOCKS server running within your AlloyDB VPC network as a connection intermediary. For more information, see Connect to a cluster from outside its VPC.

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

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) and roles/serviceusage.serviceUsageConsumer (Service Usage Consumer) predefined roles.

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

• The Cloud 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 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.

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

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

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

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

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 -h 127.0.0.1 -p 5432 -U DB_USER

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

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);
  }
}

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);
};

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/v5/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
}

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;
        }
    }
}

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 }%>

// $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);