Redirected from github.com/googlecloudplatform/alloydb-auth-proxy.

alloydb-auth-proxy

command module

v1.14.1 Latest Latest Go to latest Published: Mar 11, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README ¶

AlloyDB Auth Proxy

The AlloyDB Auth Proxy is the recommended way to connect to AlloyDB. It provides:

Secure connections — TLS 1.3 encryption and identity verification, independent of the database protocol
IAM-based authorization — controls who can connect to your AlloyDB instances using Google Cloud IAM
No certificate management — no SSL certificates, firewall rules, or IP allowlisting required
IAM database authentication — optional support for automatic IAM DB authentication

Note: The proxy does not configure the network. You must ensure it can reach your AlloyDB instance (e.g., by running the proxy inside the same VPC as your AlloyDB instance).

If you're using Go, Python, or Java, consider using the language connectors instead—they embed the same functionality directly in your process:

Language	Connector
Go	alloydb-go-connector
Python	alloydb-python-connector
Java	alloydb-java-connector

Quickstart

Get connected in five steps.

1. Install the proxy

Pick your platform below, or see all installation options.

Linux (amd64)

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.linux.amd64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Mac (Apple Silicon)

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.darwin.arm64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Mac (Intel)

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.darwin.amd64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Windows (x64)

Invoke-WebRequest -Uri "https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1/alloydb-auth-proxy-x64.exe" -OutFile "alloydb-auth-proxy.exe"

Container image

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

2. Authenticate

The proxy uses Application Default Credentials (ADC) by default. Set them up with gcloud:

gcloud auth application-default login

In Google-managed environments (Cloud Run, GKE, Compute Engine), ADC is available automatically—no additional setup needed.

3. Find your instance URI

gcloud alloydb instances describe INSTANCE_NAME \
    --region=REGION \
    --cluster=CLUSTER_NAME \
    --format='value(name)'

The URI has the form:

projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

4. Start the proxy

Binary (Linux / Mac)

# By default, the proxy connects over Private Service Access—a private
# connection within the same VPC as your AlloyDB instance. Add --public-ip
# if your instance has a public IP and you are not connecting from within
# the VPC.
./alloydb-auth-proxy projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

Binary (Windows)

.\alloydb-auth-proxy.exe projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

Container image

# Mounts your local gcloud credentials into the container
docker run --rm \
  -v "$HOME/.config/gcloud:/gcloud" \
  -e GOOGLE_APPLICATION_CREDENTIALS=/gcloud/application_default_credentials.json \
  -p 1.14.1.1:5432:5432 \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:1.14.1 \
  --address 1.14.1.0 \
  projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

You should see output like:

Authorizing with Application Default Credentials
Listening on 127.0.0.1:5432
The proxy has started successfully and is ready for new connections!

5. Connect

In a separate terminal, connect with any Postgres client:

psql "host=127.0.0.1 port=5432 user=DB_USER dbname=DB_NAME"

Installation

Binary

Download the latest binary for your OS and architecture from releases.

Linux amd64

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.linux.amd64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Linux 386

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.linux.386" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Linux arm64

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.linux.arm64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Linux arm

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.linux.arm" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Mac (Intel)

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.darwin.amd64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Mac (Apple Silicon)

URL="https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1"
wget "$URL/alloydb-auth-proxy.darwin.arm64" -O alloydb-auth-proxy
chmod +x alloydb-auth-proxy

Windows x64

Invoke-WebRequest -Uri "https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1/alloydb-auth-proxy-x64.exe" -OutFile "alloydb-auth-proxy.exe"

Windows x86

Invoke-WebRequest -Uri "https://storage.googleapis.com/alloydb-auth-proxy/v1.14.1/alloydb-auth-proxy-x86.exe" -OutFile "alloydb-auth-proxy.exe"

Container image

Container images are available from Artifact Registry:

[!NOTE] These images were migrated from Google Container Registry (deprecated) to Artifact Registry, which is why they still use the gcr.io naming prefix.

Each image is tagged with the proxy version. Available tag variants:

Tag	Base image
`VERSION`	distroless (default, non-root, minimal)
`VERSION-alpine`	Alpine
`VERSION-bookworm`	Debian Bookworm

Use Alpine or Debian variants when you need a shell or debugging tools.

# Pull a specific version (recommended over :latest)
docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:1.14.1

Pin to a specific version tag and use CI automation to keep it updated.

Running with Docker:

docker run --rm \
  -v "$HOME/.config/gcloud:/gcloud" \
  -e GOOGLE_APPLICATION_CREDENTIALS=/gcloud/application_default_credentials.json \
  -p 127.0.0.1:5432:5432 \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:1.13.11 \
  projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \
  --address 0.0.0.0

Build from source

Requires the latest version of Go.

go install github.com/GoogleCloudPlatform/alloydb-auth-proxy@latest

The binary is placed in $GOPATH/bin or $HOME/go/bin.

Authentication

The proxy uses Application Default Credentials (ADC) by default and this is the recommended approach for most use cases. ADC automatically picks up credentials from the environment—no flags needed:

# One-time setup on a developer machine
gcloud auth application-default login

In Google-managed environments (Cloud Run, GKE, Compute Engine), ADC is already available and requires no additional configuration.

For less-common scenarios, the proxy also accepts explicit credentials via flags:

Flag	Description
`--credentials-file PATH`	Path to a service account key JSON file
`--token TOKEN`	An OAuth2 Bearer token

Required IAM roles for any principal connecting through the proxy:

roles/alloydb.client (Cloud AlloyDB Client)
roles/serviceusage.serviceUsageConsumer (Service Usage Consumer)

See Roles and Permissions in AlloyDB for details.

Service account impersonation is also supported:

./alloydb-auth-proxy \
    --impersonate-service-account=SA@PROJECT.iam.gserviceaccount.com \
    projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

For delegation chains, supply a comma-separated list where the first entry is the target and each subsequent entry is a delegate:

./alloydb-auth-proxy \
    --impersonate-service-account=TARGET_SA,DELEGATE_SA \
    projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

Usage

All examples below assume valid credentials are present. Replace INSTANCE_URI with the full instance path:

projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE

Basic usage

# Listens on 127.0.0.1:5432 using private IP
./alloydb-auth-proxy INSTANCE_URI

Multiple instances

# First instance: 127.0.0.1:5432, second: 127.0.0.1:5433
./alloydb-auth-proxy INSTANCE_URI_1 INSTANCE_URI_2

Custom address and port

# Listen on all interfaces, port 6000
./alloydb-auth-proxy --address 0.0.0.0 --port 6000 INSTANCE_URI

Public IP

./alloydb-auth-proxy --public-ip INSTANCE_URI

Auto IAM Authentication

Lets the proxy supply the IAM principal's OAuth2 token as the database password—no password prompt needed for the client.

./alloydb-auth-proxy --auto-iam-authn INSTANCE_URI

Per-instance configuration

Override address, port, or other settings for individual instances using a query-string appended to the instance URI (wrap in quotes to protect & from the shell):

./alloydb-auth-proxy \
    'INSTANCE_URI_1?address=0.0.0.0&port=6000' \
    'INSTANCE_URI_2?address=127.0.0.1&port=7000&auto-iam-authn=true'

Unix sockets

# All instances use a Unix socket under /run/alloydb
./alloydb-auth-proxy --unix-socket /run/alloydb INSTANCE_URI

# Per-instance path (Postgres appends .s.PGSQL.5432 automatically)
./alloydb-auth-proxy 'INSTANCE_URI?unix-socket-path=/path/to/socket'

Config file

Instead of flags, you can supply a TOML, YAML, or JSON config file:

./alloydb-auth-proxy --config-file config.toml

Example config.toml:

instance-uri   = "projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE"
auto-iam-authn = true
debug-logs     = true

Multiple instances:

instance-uri-0 = "INSTANCE_URI_1"
instance-uri-1 = "INSTANCE_URI_2"

Environment variables

Every flag has an environment variable equivalent using the ALLOYDB_PROXY_ prefix (uppercase, underscores):

# Equivalent to --structured-logs
ALLOYDB_PROXY_STRUCTURED_LOGS=true ./alloydb-auth-proxy INSTANCE_URI

# Single instance via env var
ALLOYDB_PROXY_INSTANCE_URI=INSTANCE_URI ./alloydb-auth-proxy

# Multiple instances via env vars
ALLOYDB_PROXY_INSTANCE_URI_0=INSTANCE_URI_1 \
ALLOYDB_PROXY_INSTANCE_URI_1=INSTANCE_URI_2 \
    ./alloydb-auth-proxy

Running behind a SOCKS5 proxy

ALL_PROXY=socks5://localhost:8000 \
HTTPS_PROXY=socks5://localhost:8000 \
    ./alloydb-auth-proxy INSTANCE_URI

ALL_PROXY routes TCP traffic to AlloyDB (supports socks5 and socks5h). Use socks5h to route DNS lookups through the proxy. HTTPS_PROXY routes HTTP(S) traffic to the AlloyDB Admin API (optional).

Observability

Health checks

Enable HTTP health check endpoints (useful for Kubernetes probes):

./alloydb-auth-proxy --health-check INSTANCE_URI

Endpoint	Returns 200 when...
`/startup`	Proxy has finished starting up
`/readiness`	Proxy is started, has available connections, and can reach all instances
`/liveness`	Always 200 — if unresponsive, restart the proxy

Configure address and port with --http-address and --http-port (default: localhost:9090).

Prometheus metrics

./alloydb-auth-proxy --prometheus INSTANCE_URI
# Metrics available at http://localhost:9090/metrics

Use --prometheus-namespace to set a custom namespace prefix.

Cloud Monitoring and Cloud Trace

./alloydb-auth-proxy --telemetry-project=PROJECT_ID INSTANCE_URI

Use --disable-metrics or --disable-traces to opt out of either. Use --telemetry-prefix to customize the Cloud Monitoring metric prefix.

Supported metrics:

Metric	Description
`alloydbconn/dial_latency`	Distribution of dialer latencies (ms)
`alloydbconn/open_connections`	Current number of open AlloyDB connections
`alloydbconn/dial_failure_count`	Number of failed dial attempts
`alloydbconn/refresh_success_count`	Successful certificate refresh operations
`alloydbconn/refresh_failure_count`	Failed certificate refresh operations

Debug logging

./alloydb-auth-proxy --debug-logs INSTANCE_URI

Logs internal certificate refresh operations. Useful when diagnosing unexpected proxy behavior.

Admin server (pprof / graceful shutdown)

The admin server runs on localhost:9091 and is disabled by default.

# Enable Go profiler at /debug/pprof/
./alloydb-auth-proxy --debug INSTANCE_URI

# Enable graceful shutdown via POST /quitquitquit
./alloydb-auth-proxy --quitquitquit INSTANCE_URI

Change the port with --admin-port. See the pprof documentation for profiler usage.

Reference

Run ./alloydb-auth-proxy --help for full flag documentation, or browse the rendered docs in docs/cmd.

Commonly used flags:

Flag	Default	Description
`-a, --address`	`127.0.0.1`	Address for instance listeners
`-p, --port`	`5432`	Starting port; subsequent instances increment
`-i, --auto-iam-authn`	false	Enable Auto IAM Authentication
`-c, --credentials-file`		Path to service account key JSON
`-t, --token`		OAuth2 Bearer token
`--public-ip`	false	Connect via public IP
`--psc`	false	Connect via Private Service Connect
`-u, --unix-socket`		Directory for Unix socket listeners
`--lazy-refresh`	false	Refresh certs on-demand (for throttled CPUs)
`--health-check`	false	Enable `/startup`, `/liveness`, `/readiness`
`--prometheus`	false	Enable Prometheus `/metrics` endpoint
`--structured-logs`	false	Emit logs in LogEntry JSON format
`--max-connections`	0 (unlimited)	Maximum simultaneous connections
`--config-file`		Path to TOML/YAML/JSON config file

Support policy

Major version lifecycle

This project follows semantic versioning.

Status	Description
Active	Receives all new features and security fixes. Guaranteed for at least 1 year.
Deprecated	Security and critical bug fixes only. Publicly supported for 1 year after deprecation.
Unsupported	Major versions deprecated for ≥ 1 year.

Release cadence

The proxy targets a monthly release cadence. If no new features or fixes are added, a new PATCH version is released with the latest dependencies.

Contributing

Contributions are welcome. See the CONTRIBUTING document for details.

This project is released with a Contributor Code of Conduct. By participating, you agree to abide by its terms.

Documentation ¶

Rendered for

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

Path	Synopsis
alloydb
cmd
gendocs command
examples
go module
internal
gcloud
healthcheck Package healthcheck tests and communicates the health of the AlloyDB Auth proxy.	Package healthcheck tests and communicates the health of the AlloyDB Auth proxy.
log
proxy

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

AlloyDB Auth Proxy

Quickstart

1. Install the proxy

2. Authenticate

3. Find your instance URI

4. Start the proxy

5. Connect

Table of contents

Installation

Binary

Container image

Build from source

Authentication

Usage

Basic usage

Multiple instances

Custom address and port

Public IP

Auto IAM Authentication

Per-instance configuration

Unix sockets

Config file

Environment variables

Running behind a SOCKS5 proxy

Observability

Health checks

Prometheus metrics

Cloud Monitoring and Cloud Trace

Debug logging

Admin server (pprof / graceful shutdown)

Reference

Support policy

Major version lifecycle

Release cadence

Contributing

Documentation ¶

Source Files ¶

Directories ¶