{"id":15221678,"url":"https://github.com/googlecloudplatform/alloydb-auth-proxy","last_synced_at":"2026-05-13T23:04:20.838Z","repository":{"id":37545383,"uuid":"465813029","full_name":"GoogleCloudPlatform/alloydb-auth-proxy","owner":"GoogleCloudPlatform","description":"A utility for connecting securely to your AlloyDB instances","archived":false,"fork":false,"pushed_at":"2025-03-14T20:34:54.000Z","size":4975,"stargazers_count":64,"open_issues_count":14,"forks_count":13,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-03-30T15:42:16.509Z","etag":null,"topics":["alloydb","libraries"],"latest_commit_sha":null,"homepage":"https://cloud.google.com/alloydb/docs/auth-proxy/overview?hl=hu","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-03T17:10:08.000Z","updated_at":"2025-03-15T16:38:04.000Z","dependencies_parsed_at":"2023-10-11T03:55:15.783Z","dependency_job_id":"dfe89bfb-4702-4a86-924d-16c167d34d55","html_url":"https://github.com/GoogleCloudPlatform/alloydb-auth-proxy","commit_stats":{"total_commits":484,"total_committers":16,"mean_commits":30.25,"dds":0.5454545454545454,"last_synced_commit":"5973792c1c5ece7763fc0c92ef1923fd410b474f"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-auth-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-auth-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-auth-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Falloydb-auth-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/alloydb-auth-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445671,"owners_count":20939958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alloydb","libraries"],"created_at":"2024-09-28T15:06:44.098Z","updated_at":"2026-05-13T23:04:20.823Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlloyDB Auth Proxy\n\n[![CI][ci-badge]][ci-build]\n[![Go Reference][pkg-badge]][pkg-docs]\n\n[ci-badge]: https://github.com/GoogleCloudPlatform/alloydb-auth-proxy/actions/workflows/tests.yaml/badge.svg?event=push\n[ci-build]: https://github.com/GoogleCloudPlatform/alloydb-auth-proxy/actions/workflows/tests.yaml?query=event%3Apush+branch%3Amain\n[pkg-badge]: https://pkg.go.dev/badge/github.com/GoogleCloudPlatform/alloydb-auth-proxy.svg\n[pkg-docs]: https://pkg.go.dev/github.com/GoogleCloudPlatform/alloydb-auth-proxy\n\nThe AlloyDB Auth Proxy is the recommended way to connect to AlloyDB. It provides:\n\n- **Secure connections** — TLS 1.3 encryption and identity verification, independent of the database protocol\n- **IAM-based authorization** — controls who can connect to your AlloyDB instances using Google Cloud IAM\n- **No certificate management** — no SSL certificates, firewall rules, or IP allowlisting required\n- **IAM database authentication** — optional support for automatic IAM DB authentication\n\n\u003e **Note:** The proxy does not configure the network. You must ensure it can\n\u003e reach your AlloyDB instance (e.g., by running the proxy inside the same VPC\n\u003e as your AlloyDB instance).\n\nIf you're using Go, Python, or Java, consider using the language connectors\ninstead—they embed the same functionality directly in your process:\n\n| Language | Connector |\n|----------|-----------|\n| Go | [alloydb-go-connector][] |\n| Python | [alloydb-python-connector][] |\n| Java | [alloydb-java-connector][] |\n\n[alloydb-go-connector]: https://github.com/GoogleCloudPlatform/alloydb-go-connector\n[alloydb-python-connector]: https://github.com/GoogleCloudPlatform/alloydb-python-connector\n[alloydb-java-connector]: https://github.com/GoogleCloudPlatform/alloydb-java-connector\n\n---\n\n## Quickstart\n\nGet connected in five steps.\n\n### 1. Install the proxy\n\nPick your platform below, or see [all installation options](#installation).\n\n\u003c!-- {x-release-please-start-version} --\u003e\n\u003cdetails open\u003e\n\u003csummary\u003eLinux (amd64)\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.linux.amd64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMac (Apple Silicon)\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.darwin.arm64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMac (Intel)\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.darwin.amd64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows (x64)\u003c/summary\u003e\n\n```powershell\nInvoke-WebRequest -Uri \"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4/alloydb-auth-proxy-x64.exe\" -OutFile \"alloydb-auth-proxy.exe\"\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eContainer image\u003c/summary\u003e\n\n```sh\ndocker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:1.14.4\n```\n\u003c/details\u003e\n\u003c!-- {x-release-please-end} --\u003e\n\n### 2. Authenticate\n\nThe proxy uses [Application Default Credentials (ADC)][adc] by default. Set\nthem up with gcloud:\n\n```sh\ngcloud auth application-default login\n```\n\nIn Google-managed environments (Cloud Run, GKE, Compute Engine), ADC is\navailable automatically—no additional setup needed.\n\n### 3. Find your instance URI\n\n```sh\ngcloud alloydb instances describe INSTANCE_NAME \\\n    --region=REGION \\\n    --cluster=CLUSTER_NAME \\\n    --format='value(name)'\n```\n\nThe URI has the form:\n```\nprojects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\n### 4. Start the proxy\n\n\u003cdetails open\u003e\n\u003csummary\u003eBinary (Linux / Mac)\u003c/summary\u003e\n\n```sh\n# By default, the proxy connects over Private Service Access—a private\n# connection within the same VPC as your AlloyDB instance. Add --public-ip\n# if your instance has a public IP and you are not connecting from within\n# the VPC.\n./alloydb-auth-proxy projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBinary (Windows)\u003c/summary\u003e\n\n```powershell\n.\\alloydb-auth-proxy.exe projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\u003c/details\u003e\n\n\u003c!-- {x-release-please-start-version} --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eContainer image\u003c/summary\u003e\n\n```sh\n# Mounts your local gcloud credentials into the container\ndocker run --rm \\\n  -v \"$HOME/.config/gcloud:/gcloud\" \\\n  -e GOOGLE_APPLICATION_CREDENTIALS=/gcloud/application_default_credentials.json \\\n  -p 1.14.4.1:5432:5432 \\\n  gcr.io/alloydb-connectors/alloydb-auth-proxy:1.14.4 \\\n  --address 1.14.4.0 \\\n  projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\u003c/details\u003e\n\u003c!-- {x-release-please-end} --\u003e\n\nYou should see output like:\n```\nAuthorizing with Application Default Credentials\nListening on 127.0.0.1:5432\nThe proxy has started successfully and is ready for new connections!\n```\n\n### 5. Connect\n\nIn a separate terminal, connect with any Postgres client:\n\n```sh\npsql \"host=127.0.0.1 port=5432 user=DB_USER dbname=DB_NAME\"\n```\n\n## Table of contents\n\n- [Installation](#installation)\n  - [Binary](#binary)\n  - [Container image](#container-image)\n  - [Build from source](#build-from-source)\n  - [Build your own container](#build-your-own-container)\n- [Authentication](#authentication)\n- [Usage](#usage)\n  - [Basic usage](#basic-usage)\n  - [Multiple instances](#multiple-instances)\n  - [Custom address and port](#custom-address-and-port)\n  - [Public IP](#public-ip)\n  - [Auto IAM Authentication](#auto-iam-authentication)\n  - [Per-instance configuration](#per-instance-configuration)\n  - [Unix sockets](#unix-sockets)\n  - [Config file](#config-file)\n  - [Environment variables](#environment-variables)\n- [Running behind a SOCKS5 proxy](#running-behind-a-socks5-proxy)\n- [Observability](#observability)\n  - [Health checks](#health-checks)\n  - [Prometheus metrics](#prometheus-metrics)\n  - [Cloud Monitoring and Cloud Trace](#cloud-monitoring-and-cloud-trace)\n  - [Debug logging](#debug-logging)\n  - [Admin server (pprof / graceful shutdown)](#admin-server-pprof--graceful-shutdown)\n- [Reference](#reference)\n- [Support policy](#support-policy)\n- [Contributing](#contributing)\n\n---\n\n## Installation\n\n### Binary\n\nDownload the latest binary for your OS and architecture from\n[releases][releases].\n\n\u003c!-- {x-release-please-start-version} --\u003e\n\u003cdetails open\u003e\n\u003csummary\u003eLinux amd64\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.linux.amd64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux 386\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.linux.386\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLinux arm64\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.linux.arm64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMac (Intel)\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.darwin.amd64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMac (Apple Silicon)\u003c/summary\u003e\n\n```sh\nURL=\"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4\"\nwget \"$URL/alloydb-auth-proxy.darwin.arm64\" -O alloydb-auth-proxy\nchmod +x alloydb-auth-proxy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows x64\u003c/summary\u003e\n\n```powershell\nInvoke-WebRequest -Uri \"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4/alloydb-auth-proxy-x64.exe\" -OutFile \"alloydb-auth-proxy.exe\"\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows x86\u003c/summary\u003e\n\n```powershell\nInvoke-WebRequest -Uri \"https://storage.googleapis.com/alloydb-auth-proxy/v1.14.4/alloydb-auth-proxy-x86.exe\" -OutFile \"alloydb-auth-proxy.exe\"\n```\n\u003c/details\u003e\n\u003c!-- {x-release-please-end} --\u003e\n\n### Container image\n\nContainer images are available from [Artifact Registry][]:\n\n- [`gcr.io/alloydb-connectors/alloydb-auth-proxy`](https://gcr.io/alloydb-connectors/alloydb-auth-proxy)\n- [`us.gcr.io/alloydb-connectors/alloydb-auth-proxy`](https://us.gcr.io/alloydb-connectors/alloydb-auth-proxy)\n- [`eu.gcr.io/alloydb-connectors/alloydb-auth-proxy`](https://eu.gcr.io/alloydb-connectors/alloydb-auth-proxy)\n- [`asia.gcr.io/alloydb-connectors/alloydb-auth-proxy`](https://asia.gcr.io/alloydb-connectors/alloydb-auth-proxy)\n\n\u003e [!NOTE]\n\u003e These images were migrated from Google Container Registry (deprecated) to\n\u003e Artifact Registry, which is why they still use the `gcr.io` naming prefix.\n\nEach image is tagged with the proxy version. Available tag variants:\n\nTag                | Base image\n------------------ | -------------------------------------------\n`VERSION`          | [distroless][] (default, non-root, minimal)\n`VERSION-alpine`   | Alpine\n`VERSION-bookworm` | Debian Bookworm\n\nUse Alpine or Debian variants when you need a shell or debugging tools.\n\n\u003c!-- {x-release-please-start-version} --\u003e\n```sh\n# Pull a specific version (recommended over :latest)\ndocker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:1.14.4\n```\n\u003c!-- {x-release-please-end} --\u003e\n\nPin to a specific version tag and use CI automation to keep it updated.\n\n**Running with Docker:**\n\n```sh\ndocker run --rm \\\n  -v \"$HOME/.config/gcloud:/gcloud\" \\\n  -e GOOGLE_APPLICATION_CREDENTIALS=/gcloud/application_default_credentials.json \\\n  -p 127.0.0.1:5432:5432 \\\n  gcr.io/alloydb-connectors/alloydb-auth-proxy:1.13.11 \\\n  projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \\\n  --address 0.0.0.0\n```\n\n### Build from source\n\nRequires the latest version of [Go](https://go.dev/doc/install).\n\n```sh\ngo install github.com/GoogleCloudPlatform/alloydb-auth-proxy@latest\n```\n\nThe binary is placed in `$GOPATH/bin` or `$HOME/go/bin`.\n\n### Build your own container\n\nYou can build and push your own container image using the provided Dockerfiles.\nThese Dockerfiles require `docker buildx` to correctly set the build platform\nand target architecture.\n\nIf you don't have a registry to push to, you can\n[set up an Artifact Registry][Artifact Registry] in Google Cloud.\n\nTo build the default container:\n\n```sh\ndocker buildx build --platform linux/amd64 -t my-custom-image-name --push .\n```\n\nAlternatively, you can build the Alpine or Bookworm variants:\n\n```sh\ndocker buildx build --platform linux/amd64 -t my-custom-alpine-image -f Dockerfile.alpine --push .\ndocker buildx build --platform linux/amd64 -t my-custom-bookworm-image -f Dockerfile.bookworm --push .\n```\n\n[Artifact Registry]: https://cloud.google.com/artifact-registry/docs/docker/store-docker-container-images\n[distroless]: https://github.com/GoogleContainerTools/distroless\n\n---\n\n## Authentication\n\nThe proxy uses [Application Default Credentials (ADC)][adc] by default and\nthis is the recommended approach for most use cases. ADC automatically picks\nup credentials from the environment—no flags needed:\n\n```sh\n# One-time setup on a developer machine\ngcloud auth application-default login\n```\n\nIn Google-managed environments (Cloud Run, GKE, Compute Engine), ADC is\nalready available and requires no additional configuration.\n\nFor less-common scenarios, the proxy also accepts explicit credentials via flags:\n\n| Flag | Description |\n|------|-------------|\n| `--credentials-file PATH` | Path to a service account key JSON file |\n| `--token TOKEN` | An OAuth2 Bearer token |\n\n**Required IAM roles** for any principal connecting through the proxy:\n\n- `roles/alloydb.client` (Cloud AlloyDB Client)\n- `roles/serviceusage.serviceUsageConsumer` (Service Usage Consumer)\n\nSee [Roles and Permissions in AlloyDB][roles-and-permissions] for details.\n\n**Service account impersonation** is also supported:\n\n```sh\n./alloydb-auth-proxy \\\n    --impersonate-service-account=SA@PROJECT.iam.gserviceaccount.com \\\n    projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\nFor delegation chains, supply a comma-separated list where the first entry is\nthe target and each subsequent entry is a delegate:\n\n```sh\n./alloydb-auth-proxy \\\n    --impersonate-service-account=TARGET_SA,DELEGATE_SA \\\n    projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\n---\n\n## Usage\n\nAll examples below assume valid credentials are present. Replace\n`INSTANCE_URI` with the full instance path:\n\n```\nprojects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\n```\n\n### Basic usage\n\n```sh\n# Listens on 127.0.0.1:5432 using private IP\n./alloydb-auth-proxy INSTANCE_URI\n```\n\n### Multiple instances\n\n```sh\n# First instance: 127.0.0.1:5432, second: 127.0.0.1:5433\n./alloydb-auth-proxy INSTANCE_URI_1 INSTANCE_URI_2\n```\n\n### Custom address and port\n\n```sh\n# Listen on all interfaces, port 6000\n./alloydb-auth-proxy --address 0.0.0.0 --port 6000 INSTANCE_URI\n```\n\n### Public IP\n\n```sh\n./alloydb-auth-proxy --public-ip INSTANCE_URI\n```\n\n### Auto IAM Authentication\n\nLets the proxy supply the IAM principal's OAuth2 token as the database\npassword—no password prompt needed for the client.\n\n```sh\n./alloydb-auth-proxy --auto-iam-authn INSTANCE_URI\n```\n\n### Per-instance configuration\n\nOverride address, port, or other settings for individual instances using a\nquery-string appended to the instance URI (wrap in quotes to protect `\u0026` from\nthe shell):\n\n```sh\n./alloydb-auth-proxy \\\n    'INSTANCE_URI_1?address=0.0.0.0\u0026port=6000' \\\n    'INSTANCE_URI_2?address=127.0.0.1\u0026port=7000\u0026auto-iam-authn=true'\n```\n\n### Unix sockets\n\n```sh\n# All instances use a Unix socket under /run/alloydb\n./alloydb-auth-proxy --unix-socket /run/alloydb INSTANCE_URI\n\n# Per-instance path (Postgres appends .s.PGSQL.5432 automatically)\n./alloydb-auth-proxy 'INSTANCE_URI?unix-socket-path=/path/to/socket'\n```\n\n### Config file\n\nInstead of flags, you can supply a TOML, YAML, or JSON config file:\n\n```sh\n./alloydb-auth-proxy --config-file config.toml\n```\n\nExample `config.toml`:\n\n```toml\ninstance-uri   = \"projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE\"\nauto-iam-authn = true\ndebug-logs     = true\n```\n\nMultiple instances:\n\n```toml\ninstance-uri-0 = \"INSTANCE_URI_1\"\ninstance-uri-1 = \"INSTANCE_URI_2\"\n```\n\n### Environment variables\n\nEvery flag has an environment variable equivalent using the\n`ALLOYDB_PROXY_` prefix (uppercase, underscores):\n\n```sh\n# Equivalent to --structured-logs\nALLOYDB_PROXY_STRUCTURED_LOGS=true ./alloydb-auth-proxy INSTANCE_URI\n\n# Single instance via env var\nALLOYDB_PROXY_INSTANCE_URI=INSTANCE_URI ./alloydb-auth-proxy\n\n# Multiple instances via env vars\nALLOYDB_PROXY_INSTANCE_URI_0=INSTANCE_URI_1 \\\nALLOYDB_PROXY_INSTANCE_URI_1=INSTANCE_URI_2 \\\n    ./alloydb-auth-proxy\n```\n\n---\n\n## Running behind a SOCKS5 proxy\n\n```sh\nALL_PROXY=socks5://localhost:8000 \\\nHTTPS_PROXY=socks5://localhost:8000 \\\n    ./alloydb-auth-proxy INSTANCE_URI\n```\n\n`ALL_PROXY` routes TCP traffic to AlloyDB (supports `socks5` and `socks5h`).\nUse `socks5h` to route DNS lookups through the proxy. `HTTPS_PROXY` routes\nHTTP(S) traffic to the AlloyDB Admin API (optional).\n\n---\n\n## Observability\n\n### Health checks\n\nEnable HTTP health check endpoints (useful for Kubernetes probes):\n\n```sh\n./alloydb-auth-proxy --health-check INSTANCE_URI\n```\n\n| Endpoint | Returns 200 when... |\n|----------|---------------------|\n| `/startup` | Proxy has finished starting up |\n| `/readiness` | Proxy is started, has available connections, and can reach all instances |\n| `/liveness` | Always 200 — if unresponsive, restart the proxy |\n\nConfigure address and port with `--http-address` and `--http-port` (default:\n`localhost:9090`).\n\n### Prometheus metrics\n\n```sh\n./alloydb-auth-proxy --prometheus INSTANCE_URI\n# Metrics available at http://localhost:9090/metrics\n```\n\nUse `--prometheus-namespace` to set a custom namespace prefix.\n\n### Cloud Monitoring and Cloud Trace\n\n```sh\n./alloydb-auth-proxy --telemetry-project=PROJECT_ID INSTANCE_URI\n```\n\nUse `--disable-metrics` or `--disable-traces` to opt out of either. Use\n`--telemetry-prefix` to customize the Cloud Monitoring metric prefix.\n\n**Supported metrics:**\n\n| Metric | Description |\n|--------|-------------|\n| `alloydbconn/dial_latency` | Distribution of dialer latencies (ms) |\n| `alloydbconn/open_connections` | Current number of open AlloyDB connections |\n| `alloydbconn/dial_failure_count` | Number of failed dial attempts |\n| `alloydbconn/refresh_success_count` | Successful certificate refresh operations |\n| `alloydbconn/refresh_failure_count` | Failed certificate refresh operations |\n\n### Debug logging\n\n```sh\n./alloydb-auth-proxy --debug-logs INSTANCE_URI\n```\n\nLogs internal certificate refresh operations. Useful when diagnosing\nunexpected proxy behavior.\n\n### Admin server (pprof / graceful shutdown)\n\nThe admin server runs on `localhost:9091` and is disabled by default.\n\n```sh\n# Enable Go profiler at /debug/pprof/\n./alloydb-auth-proxy --debug INSTANCE_URI\n\n# Enable graceful shutdown via POST /quitquitquit\n./alloydb-auth-proxy --quitquitquit INSTANCE_URI\n```\n\nChange the port with `--admin-port`. See the [pprof documentation][pprof] for\nprofiler usage.\n\n---\n\n## Reference\n\nRun `./alloydb-auth-proxy --help` for full flag documentation, or browse the\nrendered docs in [docs/cmd](docs/cmd).\n\n**Commonly used flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-a, --address` | `127.0.0.1` | Address for instance listeners |\n| `-p, --port` | `5432` | Starting port; subsequent instances increment |\n| `-i, --auto-iam-authn` | false | Enable Auto IAM Authentication |\n| `-c, --credentials-file` | | Path to service account key JSON |\n| `-t, --token` | | OAuth2 Bearer token |\n| `--public-ip` | false | Connect via public IP |\n| `--psc` | false | Connect via Private Service Connect |\n| `-u, --unix-socket` | | Directory for Unix socket listeners |\n| `--lazy-refresh` | false | Refresh certs on-demand (for throttled CPUs) |\n| `--health-check` | false | Enable `/startup`, `/liveness`, `/readiness` |\n| `--prometheus` | false | Enable Prometheus `/metrics` endpoint |\n| `--structured-logs` | false | Emit logs in LogEntry JSON format |\n| `--max-connections` | 0 (unlimited) | Maximum simultaneous connections |\n| `--config-file` | | Path to TOML/YAML/JSON config file |\n\n---\n\n## Support policy\n\nThis project follows [semantic versioning](https://semver.org/). We release a new\nversion monthly with features, bug fixes, and security updates. If no new\nfeatures are added, we still release a PATCH version with updated dependencies.\nWe recommend always using the latest version.\n\n---\n\n## Contributing\n\nContributions are welcome. See the [CONTRIBUTING][contributing] document for\ndetails.\n\nThis project is released with a [Contributor Code of Conduct][code-of-conduct].\nBy participating, you agree to abide by its terms.\n\n---\n\n[adc]:                   https://cloud.google.com/docs/authentication\n[code-of-conduct]:       CONTRIBUTING.md#contributor-code-of-conduct\n[contributing]:          CONTRIBUTING.md\n[pprof]:                 https://pkg.go.dev/net/http/pprof\n[releases]:              https://github.com/GoogleCloudPlatform/alloydb-auth-proxy/releases\n[roles-and-permissions]: https://cloud.google.com/alloydb/docs/auth-proxy/overview#how-authorized\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Falloydb-auth-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglecloudplatform%2Falloydb-auth-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Falloydb-auth-proxy/lists"}