AlloyDB Auth Proxy

The AlloyDB Auth Proxy is a binary that provides IAM-based authorization and encryption when connecting to an AlloyDB instance.

See the Connecting Overview page for more information on connecting to an AlloyDB instance, or the About the proxy page for details on how the AlloyDB Auth Proxy works.

Note: The Proxy cannot provide a network path to an AlloyDB instance if one is not already present (e.g., the proxy cannot access a VPC if it does not already have access to it).

Installation

Check for the latest version on the releases page and use the following instructions for your OS and CPU architecture.

Linux amd64

# see Releases for other versions
URL="https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0"

wget "$URL/alloydb-auth-proxy.linux.amd64" -O alloydb-auth-proxy

chmod +x alloydb-auth-proxy

Linux 386

# see Releases for other versions
URL="https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0"

wget "$URL/alloydb-auth-proxy.linux.386" -O alloydb-auth-proxy

chmod +x alloydb-auth-proxy

Linux arm64

# see Releases for other versions
URL="https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0"

wget "$URL/alloydb-auth-proxy.linux.arm64" -O alloydb-auth-proxy

chmod +x alloydb-auth-proxy

Linux arm

# see Releases for other versions
URL="https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0"

wget "$URL/alloydb-auth-proxy.linux.arm" -O alloydb-auth-proxy

chmod +x alloydb-auth-proxy

Mac (Intel)

# see Releases for other versions
URL="https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0"

wget "$URL/alloydb-auth-proxy.darwin.amd64" -O alloydb-auth-proxy

chmod +x alloydb-auth-proxy

Mac (Apple Silicon)

# see Releases for other versions
URL="https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0"

wget "$URL/alloydb-auth-proxy.darwin.arm64" -O alloydb-auth-proxy

chmod +x alloydb-auth-proxy

Windows x64

# see Releases for other versions
wget https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0/alloydb-auth-proxy-x64.exe -O alloydb-auth-proxy.exe

Windows x86

# see Releases for other versions
wget https://storage.googleapis.com/alloydb-auth-proxy/v0.1.0/alloydb-auth-proxy-x86.exe -O alloydb-auth-proxy.exe

Container Images

There are containerized versions of the proxy available from the following Google Cloud Container Registry repositories:

gcr.io/alloydb-connectors/alloydb-auth-proxy
us.gcr.io/alloydb-connectors/alloydb-auth-proxy
eu.gcr.io/alloydb-connectors/alloydb-auth-proxy
asia.gcr.io/alloydb-connectors/alloydb-auth-proxy

Each image is tagged with the associated proxy version. The following tags are currently supported:

$VERSION - default image (recommended)
$VERSION-alpine - uses alpine:3 as a base image
$VERSION-buster - uses debian:buster as
$VERSION-bullseye - uses debian:bullseye as a base image

We recommend using the latest version of the proxy and updating the version regularly. However, we also recommend pinning to a specific tag and avoid the latest tag. Note: the tagged version is only that of the proxy. Changes in base images may break specific setups, even on non-major version increments. As such, it's a best practice to test changes before deployment, and use automated rollbacks to revert potential failures.

Install from Source

To install from source, ensure you have the latest version of Go installed.

Then, simply run:

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

The alloydb-auth-proxy will be placed in $GOPATH/bin or $HOME/go/bin.

Credentials

The AlloyDB Auth Proxy uses a Cloud IAM account to authorize connections against an AlloyDB instance. The proxy supports the following options:

A -credential-file flag for a service account key file.
A -token flag for a OAuth2 Bearer token
Application Default Credentials (ADC) if neither of the above have been set.

Note: Any account connecting to AlloyDB instance will need one of the following IAM roles:

Cloud AlloyDB Client (roles/alloydb.client) (preferred)
Cloud AlloyDB Admin (roles/alloydb.admin)

See Roles and Permissions in AlloyDB for details.

When the proxy authenticates under the Compute Engine VM's default service account, the VM must have the cloud-platform API scope (i.e., "https://www.googleapis.com/auth/cloud-platform") and the associated project must have the AlloyDB Admin API enabled. The default service account must also have at least writer or editor privileges to any projects of target AlloyDB instances.

Usage

All the following invocations assume valid credentials are present in the environment. The following examples all reference an INSTANCE_URI, which takes the form:

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

To find the INSTANCE_URI, take the name from:

# To find your instance in among all instances
gcloud alpha alloydb instances list

# or to describe your particular instance
gcloud alpha alloydb instances describe \
    --cluster <CLUSTER_NAME> \
    --region <REGION> \
    <INSTANCE_NAME>

Example invocations

Note: the following invocations assume you have downloaded the alloydb-auth-proxy into the same directory. Consider moving the proxy into a well-known location to have it available on your PATH.

# Starts the proxy listening on 127.0.0.1:5432
./alloydb-auth-proxy <INSTANCE_URI>

To connect to multiple instances, use:

# For instance 1, the proxy listens on 127.0.0.1:5432
# For instance 2, the proxy listens on 127.0.0.1:5433
./alloydb-auth-proxy <INSTANCE_URI_1> <INSTANCE_URI_2>

To override the default address the proxy listens on, use the --address flag:

# Starts the proxy listening on 0.0.0.0:5432
./alloydb-auth-proxy --address 0.0.0.0 <INSTANCE_URI>

To override the default port, use the --port flag:

# Starts the proxy listening on 127.0.0.1:6000
./alloydb-auth-proxy --port 6000 <INSTANCE_URI>

In addition, both address and port may be overrided on a per-instance level with a query-string style syntax:

./alloydb-auth-proxy \
    '<INSTANCE_URI_1>?address=0.0.0.0&port=6000' \
    '<INSTANCE_URI_2>?address=127.0.0.1&port=7000'

Note: when using the query-string syntax, the instance URI and query parameters must be wrapped in quotes.

Running behind a Socks5 proxy

The AlloyDB Auth Proxy includes support for sending requests through a SOCKS5 proxy. If a SOCKS5 proxy is running on localhost:8000, the command to start the AlloyDB Auth Proxy would look like:

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

The ALL_PROXY environment variable specifies the proxy for all TCP traffic to and from a AlloyDB instance. The ALL_PROXY environment variable supports socks5 and socks5h protocols. To route DNS lookups through a proxy, use the socks5h protocol.

The HTTPS_PROXY (or HTTP_PROXY) specifies the proxy for all HTTP(S) traffic to the AlloyDB Admin API. Specifying HTTPS_PROXY or HTTP_PROXY is only necessary when you want to proxy this traffic. Otherwise, it is optional. See http.ProxyFromEnvironment for possible values.

Support policy

Major version lifecycle

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version:

Active - Active versions get all new features and security fixes (that wouldn’t otherwise introduce a breaking change). New major versions are guaranteed to be "active" for a minimum of 1 year.

Deprecated - Deprecated versions continue to receive security and critical bug fixes, but do not receive new features. Deprecated versions will be publicly supported for 1 year.

Unsupported - Any major version that has been deprecated for >=1 year is considered publicly unsupported.

Supported Go Versions

We test and support at least the latest 3 Go versions. Changes in supported Go versions will be considered a minor change, and will be noted in the release notes.

Release cadence

The AlloyDB Auth Proxy aims for a minimum monthly release cadence. If no new features or fixes have been added, a new PATCH version with the latest dependencies is released.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING document for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.

# README