From 88456e3c1a6d9543d8b5500c8661a1235846c0a7 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Tue, 18 Aug 2026 18:23:21 -0700 Subject: [PATCH 01/21] feat: Support --universe-domain CLI flag for TPC environments Introduces the --universe-domain flag for configuring sovereign cloud and TPC universe domains. Enforces mutual exclusivity with --alloydbadmin-api-endpoint and propagates configuration to the AlloyDB connector dialer and IAM service account impersonation sources. --- cmd/root.go | 4 ++++ cmd/root_test.go | 39 ++++++++++++++++++++++++++++++++++ docs/cmd/alloydb-auth-proxy.md | 1 + internal/proxy/proxy.go | 7 ++++++ 4 files changed, 51 insertions(+) diff --git a/cmd/root.go b/cmd/root.go index d6d6cb6d..6c2dd0fe 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -643,6 +643,8 @@ the maximum time has passed. Defaults to 0s.`) localFlags.StringVar(&c.conf.APIEndpointURL, "alloydbadmin-api-endpoint", "https://alloydb.googleapis.com", "When set, the proxy uses this host as the base API path.") + localFlags.StringVar(&c.conf.UniverseDomain, "universe-domain", "", + "Universe Domain for non-GDU environments. (default: googleapis.com)") localFlags.StringVar(&c.conf.FUSEDir, "fuse", "", "Mount a directory at the path using FUSE to access AlloyDB instances.") localFlags.StringVar(&c.conf.FUSETempDir, "fuse-tmp-dir", @@ -907,6 +909,8 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { } if userHasSetLocal(cmd, "alloydbadmin-api-endpoint") { + localFlags.StringVar(&c.conf.UniverseDomain, "universe-domain", "", + "Universe Domain for non-GDU environments. (default: googleapis.com)") _, err := url.Parse(conf.APIEndpointURL) if err != nil { return newBadCommandError(fmt.Sprintf( diff --git a/cmd/root_test.go b/cmd/root_test.go index 23c1384b..8e1b48b8 100644 --- a/cmd/root_test.go +++ b/cmd/root_test.go @@ -1347,3 +1347,42 @@ func TestQuitQuitQuitWithErrors(t *testing.T) { t.Fatalf("want = %v, got = %v", errCloseFailed, got) } } + +func TestUniverseDomainFlag(t *testing.T) { + t.Parallel() + tcs := []struct { + desc string + args []string + want string + }{ + { + desc: "with universe domain specified", + args: []string{"--universe-domain", "my-universe.cloud", "projects/p/locations/r/clusters/c/instances/i"}, + want: "my-universe.cloud", + }, + } + for _, tc := range tcs { + t.Run(tc.desc, func(t *testing.T) { + c, err := parseArgs(tc.args) + if err != nil { + t.Fatalf("parseArgs failed: %v", err) + } + if c.conf.UniverseDomain != tc.want { + t.Errorf("got %q, want %q", c.conf.UniverseDomain, tc.want) + } + }) + } +} + +func TestUniverseDomainMutualExclusion(t *testing.T) { + t.Parallel() + args := []string{ + "--alloydbadmin-api-endpoint", "https://alloydb.googleapis.com", + "--universe-domain", "my-universe.cloud", + "projects/p/locations/r/clusters/c/instances/i", + } + _, err := parseArgs(args) + if err == nil { + t.Fatal("expected error when both --alloydbadmin-api-endpoint and --universe-domain are provided, got nil") + } +} diff --git a/docs/cmd/alloydb-auth-proxy.md b/docs/cmd/alloydb-auth-proxy.md index bff89a70..b6d2b276 100644 --- a/docs/cmd/alloydb-auth-proxy.md +++ b/docs/cmd/alloydb-auth-proxy.md @@ -298,6 +298,7 @@ alloydb-auth-proxy instance_uri... [flags] -a, --address string (*) Address on which to bind AlloyDB instance listeners. (default "127.0.0.1") --admin-port string Port for localhost-only admin server (default "9091") --alloydbadmin-api-endpoint string When set, the proxy uses this host as the base API path. (default "https://alloydb.googleapis.com") + --universe-domain string Universe Domain for non-GDU environments. (default: googleapis.com) -i, --auto-iam-authn (*) Enables Automatic IAM Authentication for all instances --config-file string Path to a TOML file containing configuration options. -c, --credentials-file string Path to a service account key to use for authentication. diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go index d5afab6f..cb1c2853 100644 --- a/internal/proxy/proxy.go +++ b/internal/proxy/proxy.go @@ -272,6 +272,9 @@ func credentialsOpt(c Config, l alloydb.Logger) (alloydbconn.Option, error) { // credentials token source. if c.ImpersonationChain != "" { var iopts []option.ClientOption + if c.UniverseDomain != "" { + iopts = append(iopts, option.WithUniverseDomain(c.UniverseDomain)) + } switch { case c.Token != "": l.Infof("Impersonating service account with OAuth2 token") @@ -366,6 +369,10 @@ func (c *Config) DialerOptions(l alloydb.Logger) ([]alloydbconn.Option, error) { opts = append(opts, alloydbconn.WithAdminAPIEndpoint(c.APIEndpointURL)) } + if c.UniverseDomain != "" { + opts = append(opts, alloydbconn.WithUniverseDomain(c.UniverseDomain)) + } + if c.AutoIAMAuthNEnabled() { opts = append(opts, alloydbconn.WithIAMAuthN()) switch { From 9fd7b755d05b2bc5258db91855493a30b8fc0006 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Tue, 18 Aug 2026 18:40:26 -0700 Subject: [PATCH 02/21] add universeDomain --- internal/proxy/proxy.go | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go index cb1c2853..210420b7 100644 --- a/internal/proxy/proxy.go +++ b/internal/proxy/proxy.go @@ -137,6 +137,10 @@ type Config struct { // APIEndpointURL is the URL of the AlloyDB Admin API. APIEndpointURL string + // UniverseDomain is the universe domain for the TPC environment. When left + // blank, the proxy will use the Google Default Universe (GDU): googleapis.com + UniverseDomain string + // Instances are configuration for individual instances. Instance // configuration takes precedence over global configuration. Instances []InstanceConnConfig From feac02ccde47565607e774e81da1cf899b3031bb Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 09:47:29 -0700 Subject: [PATCH 03/21] pin alloydb-go-connector and fix lint --- cmd/root.go | 19 +++++-------------- go.mod | 2 +- go.sum | 4 ++-- 3 files changed, 8 insertions(+), 17 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index 6c2dd0fe..bd918178 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -908,20 +908,11 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { return newBadCommandError("cannot specify --json-credentials and --gcloud-auth flags at the same time") } - if userHasSetLocal(cmd, "alloydbadmin-api-endpoint") { - localFlags.StringVar(&c.conf.UniverseDomain, "universe-domain", "", - "Universe Domain for non-GDU environments. (default: googleapis.com)") - _, err := url.Parse(conf.APIEndpointURL) - if err != nil { - return newBadCommandError(fmt.Sprintf( - "provided value for --alloydbadmin-api-endpoint is not a valid url, %v", - conf.APIEndpointURL, - )) - } - - // Remove trailing '/' if included - conf.APIEndpointURL = strings.TrimSuffix(conf.APIEndpointURL, "/") - cmd.logger.Infof("Using API Endpoint %v", conf.APIEndpointURL) + if userHasSetLocal(cmd, "alloydbadmin-api-endpoint") && userHasSetLocal(cmd, "universe-domain") { + return newBadCommandError(fmt.Sprintf( + "provided value for --alloydbadmin-api-endpoint is not a valid url, %v", + conf.APIEndpointURL, + )) } if userHasSetGlobal(cmd, "http-port") && !userHasSetLocal(cmd, "prometheus") && !userHasSetLocal(cmd, "health-check") { diff --git a/go.mod b/go.mod index f4baedfc..cfb60dfc 100644 --- a/go.mod +++ b/go.mod @@ -3,7 +3,7 @@ module github.com/GoogleCloudPlatform/alloydb-auth-proxy go 1.25.8 require ( - cloud.google.com/go/alloydbconn v1.18.6 + cloud.google.com/go/alloydbconn v1.18.7-0.20260827155541-3eabf98461a9 contrib.go.opencensus.io/exporter/prometheus v0.4.2 contrib.go.opencensus.io/exporter/stackdriver v0.13.14 github.com/coreos/go-systemd/v22 v22.7.0 diff --git a/go.sum b/go.sum index 83c38e03..e5c7e2ad 100644 --- a/go.sum +++ b/go.sum @@ -17,8 +17,8 @@ cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE= cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU= cloud.google.com/go/alloydb v1.26.0 h1:UTzyumJ8tEo0CqwzLkV4WMGnCxvvhw3BDy1nXfCt9KE= cloud.google.com/go/alloydb v1.26.0/go.mod h1:oqHGc/Xb5fWtH+wIDpu2wcPJX9oML/fGJuH/sp8ysyo= -cloud.google.com/go/alloydbconn v1.18.6 h1:vtRmNRk1kq0QjJ8lbrPLeooIVqCbKcDxKycRtmb6gsQ= -cloud.google.com/go/alloydbconn v1.18.6/go.mod h1:P70koybK8sRT5E11jBlCQxthyWc3+Y0gKhA4hL1favE= +cloud.google.com/go/alloydbconn v1.18.7-0.20260827155541-3eabf98461a9 h1:UjA0HtMMTcM+eSiGGwMHJYnQr3KF0KKZrYUcqzuWceQ= +cloud.google.com/go/alloydbconn v1.18.7-0.20260827155541-3eabf98461a9/go.mod h1:P70koybK8sRT5E11jBlCQxthyWc3+Y0gKhA4hL1favE= cloud.google.com/go/auth v0.23.0 h1:6Gg1CMgpgubRG7DGz5Vf1pcoNo8RfiRiRAPS4crTp54= cloud.google.com/go/auth v0.23.0/go.mod h1:4DhBRcqvtljQN3dJ57qtqbib5ZGCYE5f2crfiiC2EM0= cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc= From 58f25388cfc3b8fff43a7523e338e87ad419aa63 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 09:51:23 -0700 Subject: [PATCH 04/21] fix parse args --- cmd/root_test.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cmd/root_test.go b/cmd/root_test.go index 8e1b48b8..1172dad2 100644 --- a/cmd/root_test.go +++ b/cmd/root_test.go @@ -1363,9 +1363,9 @@ func TestUniverseDomainFlag(t *testing.T) { } for _, tc := range tcs { t.Run(tc.desc, func(t *testing.T) { - c, err := parseArgs(tc.args) + c, err := invokeProxyCommand(tc.args) if err != nil { - t.Fatalf("parseArgs failed: %v", err) + t.Fatalf("invokeProxyCommand failed: %v", err) } if c.conf.UniverseDomain != tc.want { t.Errorf("got %q, want %q", c.conf.UniverseDomain, tc.want) @@ -1381,7 +1381,7 @@ func TestUniverseDomainMutualExclusion(t *testing.T) { "--universe-domain", "my-universe.cloud", "projects/p/locations/r/clusters/c/instances/i", } - _, err := parseArgs(args) + _, err := invokeProxyCommand(args) if err == nil { t.Fatal("expected error when both --alloydbadmin-api-endpoint and --universe-domain are provided, got nil") } From bf8c9e3aa8bd21f19213c523dabdf409aeec0b5f Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 09:58:12 -0700 Subject: [PATCH 05/21] trim suffix / --- cmd/root.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/cmd/root.go b/cmd/root.go index bd918178..642c46c2 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -914,6 +914,16 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { conf.APIEndpointURL, )) } + if conf.APIEndpointURL != "" { + conf.APIEndpointURL = strings.TrimSuffix(conf.APIEndpointURL, "/") + _, err := url.Parse(conf.APIEndpointURL) + if err != nil { + return newBadCommandError(fmt.Sprintf( + "value %q is not a valid URL", + conf.APIEndpointURL, + )) + } + } if userHasSetGlobal(cmd, "http-port") && !userHasSetLocal(cmd, "prometheus") && !userHasSetLocal(cmd, "health-check") { cmd.logger.Infof("Ignoring --http-port because --prometheus or --health-check was not set") From 0d6abdc6124d1c44150255dba0093a4ae7433499 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 10:12:36 -0700 Subject: [PATCH 06/21] conditionally add admin-api-endpoint --- internal/proxy/proxy.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go index 210420b7..70b90011 100644 --- a/internal/proxy/proxy.go +++ b/internal/proxy/proxy.go @@ -369,7 +369,7 @@ func (c *Config) DialerOptions(l alloydb.Logger) ([]alloydbconn.Option, error) { } opts = append(opts, co) - if c.APIEndpointURL != "" { + if c.APIEndpointURL != "" && c.APIEndpointURL != "https://alloydb.googleapis.com" { opts = append(opts, alloydbconn.WithAdminAPIEndpoint(c.APIEndpointURL)) } From 416182773b9bcbee96c023bb00ee8d272eb99381 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 10:29:00 -0700 Subject: [PATCH 07/21] fmt --- cmd/root.go | 20 ++++++++++---------- internal/proxy/proxy.go | 4 ++++ 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index 642c46c2..f8390393 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -914,16 +914,16 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { conf.APIEndpointURL, )) } - if conf.APIEndpointURL != "" { - conf.APIEndpointURL = strings.TrimSuffix(conf.APIEndpointURL, "/") - _, err := url.Parse(conf.APIEndpointURL) - if err != nil { - return newBadCommandError(fmt.Sprintf( - "value %q is not a valid URL", - conf.APIEndpointURL, - )) - } - } + if conf.APIEndpointURL != "" { + conf.APIEndpointURL = strings.TrimSuffix(conf.APIEndpointURL, "/") + _, err := url.Parse(conf.APIEndpointURL) + if err != nil { + return newBadCommandError(fmt.Sprintf( + "value %q is not a valid URL", + conf.APIEndpointURL, + )) + } + } if userHasSetGlobal(cmd, "http-port") && !userHasSetLocal(cmd, "prometheus") && !userHasSetLocal(cmd, "health-check") { cmd.logger.Infof("Ignoring --http-port because --prometheus or --health-check was not set") diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go index 70b90011..12ed7949 100644 --- a/internal/proxy/proxy.go +++ b/internal/proxy/proxy.go @@ -17,6 +17,7 @@ package proxy import ( "bytes" "context" + "errors" "fmt" "io" "net" @@ -750,6 +751,9 @@ func (c *Client) serveSocketMount(_ context.Context, s *socketMount) error { for { cConn, err := s.Accept() if err != nil { + if errors.Is(err, net.ErrClosed) { + return nil + } if nerr, ok := err.(net.Error); ok && nerr.Timeout() { c.logger.Errorf("[%s] Error accepting connection: %v", s.instShort, err) // For transient errors, wait a small amount of time to see if it resolves itself From b82a96f6c9e6e651683023639b76ebad25bcdecb Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 10:35:35 -0700 Subject: [PATCH 08/21] docs regeneration --- docs/cmd/alloydb-auth-proxy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cmd/alloydb-auth-proxy.md b/docs/cmd/alloydb-auth-proxy.md index b6d2b276..a8300bb8 100644 --- a/docs/cmd/alloydb-auth-proxy.md +++ b/docs/cmd/alloydb-auth-proxy.md @@ -298,7 +298,6 @@ alloydb-auth-proxy instance_uri... [flags] -a, --address string (*) Address on which to bind AlloyDB instance listeners. (default "127.0.0.1") --admin-port string Port for localhost-only admin server (default "9091") --alloydbadmin-api-endpoint string When set, the proxy uses this host as the base API path. (default "https://alloydb.googleapis.com") - --universe-domain string Universe Domain for non-GDU environments. (default: googleapis.com) -i, --auto-iam-authn (*) Enables Automatic IAM Authentication for all instances --config-file string Path to a TOML file containing configuration options. -c, --credentials-file string Path to a service account key to use for authentication. @@ -355,6 +354,7 @@ alloydb-auth-proxy instance_uri... [flags] --telemetry-sample-rate int Configure the denominator of the probabilistic sample rate of traces sent to Cloud Trace (e.g., 10,000 traces 1/10,000 calls). (default 10000) -t, --token string Bearer token used for authorization. + --universe-domain string Universe Domain for non-GDU environments. (default: googleapis.com) -u, --unix-socket string (*) Enables Unix sockets for all listeners using the provided directory. --user-agent string Space separated list of additional user agents, e.g. custom-agent/0.0.1 -v, --version Print the alloydb-auth-proxy version From c8804787d31c5fed730b78d013b10e15b9a6c4eb Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 12:15:07 -0700 Subject: [PATCH 09/21] Add env var to test --- tests/alloydb_test.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/alloydb_test.go b/tests/alloydb_test.go index f884953d..1b4b83fe 100644 --- a/tests/alloydb_test.go +++ b/tests/alloydb_test.go @@ -57,6 +57,11 @@ projects//locations//clusters//instances/`, os.Getenv("ALLOYDB_DB"), "Name of the database to connect to.", ) + alloydbUniverseDomain = flag.String( + "alloydb_universe_domain", + os.Getenv("ALLOYDB_UNIVERSE_DOMAIN"), + "Universe domain for the AlloyDB instances.", + ) ) func requirePostgresVars(t *testing.T) { From e2773510cbf80a41b611538835775212292c0671 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 12:30:28 -0700 Subject: [PATCH 10/21] test env fixes --- cmd/root.go | 5 +---- cmd/root_test.go | 4 ++++ tests/connection_test.go | 3 +++ 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index f8390393..804977c9 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -909,10 +909,7 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { } if userHasSetLocal(cmd, "alloydbadmin-api-endpoint") && userHasSetLocal(cmd, "universe-domain") { - return newBadCommandError(fmt.Sprintf( - "provided value for --alloydbadmin-api-endpoint is not a valid url, %v", - conf.APIEndpointURL, - )) + return newBadCommandError("cannot specify --alloydbadmin-api-endpoint and --universe-domain flags at the same time") } if conf.APIEndpointURL != "" { conf.APIEndpointURL = strings.TrimSuffix(conf.APIEndpointURL, "/") diff --git a/cmd/root_test.go b/cmd/root_test.go index 1172dad2..f2bf9548 100644 --- a/cmd/root_test.go +++ b/cmd/root_test.go @@ -1385,4 +1385,8 @@ func TestUniverseDomainMutualExclusion(t *testing.T) { if err == nil { t.Fatal("expected error when both --alloydbadmin-api-endpoint and --universe-domain are provided, got nil") } + want := "cannot specify --alloydbadmin-api-endpoint and --universe-domain flags at the same time" + if !strings.Contains(err.Error(), want) { + t.Errorf("got %q, want error containing %q", err, want) + } } diff --git a/tests/connection_test.go b/tests/connection_test.go index a215f799..3d3c7b9f 100644 --- a/tests/connection_test.go +++ b/tests/connection_test.go @@ -81,6 +81,9 @@ func proxyConnTestWithReady(t *testing.T, args []string, driver, dsn string, rea ctx, cancel := context.WithTimeout(context.Background(), connTestTimeout) defer cancel() // Start the proxy + if *alloydbUniverseDomain != "" { + args = append(args, "--universe-domain", *alloydbUniverseDomain) + } p, err := StartProxy(ctx, args...) if err != nil { t.Fatalf("unable to start proxy: %v", err) From 329dd278cb29d38db6257bd3200a8817f893c153 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 13:11:00 -0700 Subject: [PATCH 11/21] cleaner default --- cmd/root.go | 2 +- internal/proxy/proxy.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index 804977c9..c54109fa 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -641,7 +641,7 @@ to close after receiving a TERM signal. The proxy will shut down when the number of open connections reaches 0 or when the maximum time has passed. Defaults to 0s.`) localFlags.StringVar(&c.conf.APIEndpointURL, "alloydbadmin-api-endpoint", - "https://alloydb.googleapis.com", + "", "When set, the proxy uses this host as the base API path.") localFlags.StringVar(&c.conf.UniverseDomain, "universe-domain", "", "Universe Domain for non-GDU environments. (default: googleapis.com)") diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go index 12ed7949..bf445b4f 100644 --- a/internal/proxy/proxy.go +++ b/internal/proxy/proxy.go @@ -370,7 +370,7 @@ func (c *Config) DialerOptions(l alloydb.Logger) ([]alloydbconn.Option, error) { } opts = append(opts, co) - if c.APIEndpointURL != "" && c.APIEndpointURL != "https://alloydb.googleapis.com" { + if c.APIEndpointURL != "" { opts = append(opts, alloydbconn.WithAdminAPIEndpoint(c.APIEndpointURL)) } From 25acb828f64e268766ea4f162721fef61c5f3305 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 13:17:22 -0700 Subject: [PATCH 12/21] default test fixes --- cmd/root_test.go | 3 --- 1 file changed, 3 deletions(-) diff --git a/cmd/root_test.go b/cmd/root_test.go index f2bf9548..bf92314b 100644 --- a/cmd/root_test.go +++ b/cmd/root_test.go @@ -101,9 +101,6 @@ func withDefaults(c *proxy.Config) *proxy.Config { if c.TelemetryTracingSampleRate == 0 { c.TelemetryTracingSampleRate = 10_000 } - if c.APIEndpointURL == "" { - c.APIEndpointURL = "https://alloydb.googleapis.com" - } return c } From 0d5fdf9777f9aa284633f08826c754bce498da95 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 13:19:05 -0700 Subject: [PATCH 13/21] regen docs --- docs/cmd/alloydb-auth-proxy.md | 2 +- internal/proxy/proxy_test.go | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/cmd/alloydb-auth-proxy.md b/docs/cmd/alloydb-auth-proxy.md index a8300bb8..47b4b218 100644 --- a/docs/cmd/alloydb-auth-proxy.md +++ b/docs/cmd/alloydb-auth-proxy.md @@ -297,7 +297,7 @@ alloydb-auth-proxy instance_uri... [flags] ``` -a, --address string (*) Address on which to bind AlloyDB instance listeners. (default "127.0.0.1") --admin-port string Port for localhost-only admin server (default "9091") - --alloydbadmin-api-endpoint string When set, the proxy uses this host as the base API path. (default "https://alloydb.googleapis.com") + --alloydbadmin-api-endpoint string When set, the proxy uses this host as the base API path. -i, --auto-iam-authn (*) Enables Automatic IAM Authentication for all instances --config-file string Path to a TOML file containing configuration options. -c, --credentials-file string Path to a service account key to use for authentication. diff --git a/internal/proxy/proxy_test.go b/internal/proxy/proxy_test.go index 9bdddea7..76d220ab 100644 --- a/internal/proxy/proxy_test.go +++ b/internal/proxy/proxy_test.go @@ -519,6 +519,10 @@ func (s *spyHandler) wasCalled() bool { } func TestClientInitializationWithCustomHost(t *testing.T) { + t.Setenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN", "") + ctx := context.Background() + testDir, cleanup := createTempDir(t) + defer cleanup() if testing.Short() { t.Skip("skipping client initialization test that requires valid credentials") } From 9d230a32326552d95a1492c13d70e71e9fd2ddf2 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 13:21:12 -0700 Subject: [PATCH 14/21] remove unused --- internal/proxy/proxy_test.go | 2 -- 1 file changed, 2 deletions(-) diff --git a/internal/proxy/proxy_test.go b/internal/proxy/proxy_test.go index 76d220ab..0f62a182 100644 --- a/internal/proxy/proxy_test.go +++ b/internal/proxy/proxy_test.go @@ -520,8 +520,6 @@ func (s *spyHandler) wasCalled() bool { func TestClientInitializationWithCustomHost(t *testing.T) { t.Setenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN", "") - ctx := context.Background() - testDir, cleanup := createTempDir(t) defer cleanup() if testing.Short() { t.Skip("skipping client initialization test that requires valid credentials") From 7782946363d47fc064643edd0d4d428163803dba Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Fri, 28 Aug 2026 13:23:29 -0700 Subject: [PATCH 15/21] fix test --- internal/proxy/proxy_test.go | 2 -- 1 file changed, 2 deletions(-) diff --git a/internal/proxy/proxy_test.go b/internal/proxy/proxy_test.go index 0f62a182..9bdddea7 100644 --- a/internal/proxy/proxy_test.go +++ b/internal/proxy/proxy_test.go @@ -519,8 +519,6 @@ func (s *spyHandler) wasCalled() bool { } func TestClientInitializationWithCustomHost(t *testing.T) { - t.Setenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN", "") - defer cleanup() if testing.Short() { t.Skip("skipping client initialization test that requires valid credentials") } From 9bc42508e6d5db9fecdd5d1b7516494b942a68ba Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Mon, 31 Aug 2026 16:23:28 -0700 Subject: [PATCH 16/21] Add back log --- cmd/root.go | 1 + 1 file changed, 1 insertion(+) diff --git a/cmd/root.go b/cmd/root.go index c54109fa..3b556473 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -920,6 +920,7 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { conf.APIEndpointURL, )) } + cmd.logger.Infof("Using API Endpoint %v", conf.APIEndpointURL) } if userHasSetGlobal(cmd, "http-port") && !userHasSetLocal(cmd, "prometheus") && !userHasSetLocal(cmd, "health-check") { From 57b08931edcb11d9a6c502739919cca5ce78fe88 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Mon, 31 Aug 2026 16:28:36 -0700 Subject: [PATCH 17/21] formatting fixes --- cmd/root.go | 448 ++++++++++++++++++++++++++-------------------------- go.mod | 2 +- go.sum | 4 +- 3 files changed, 227 insertions(+), 227 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index 3b556473..e81b5218 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -89,7 +89,7 @@ func Execute() { // Command represents an invocation of the AlloyDB Auth Proxy. type Command struct { *cobra.Command - conf *proxy.Config + conf *proxy.Config logger alloydb.Logger dialer alloydb.Dialer cleanup func() error @@ -116,349 +116,349 @@ func WithDialer(d alloydb.Dialer) Option { var longHelp = ` Overview - The AlloyDB Auth proxy is a utility for ensuring secure connections - to your AlloyDB instances. It provides IAM authorization, allowing you - to control who can connect to your instances through IAM permissions, and TLS - 1.3 encryption, without having to manage certificates. + The AlloyDB Auth proxy is a utility for ensuring secure connections + to your AlloyDB instances. It provides IAM authorization, allowing you + to control who can connect to your instances through IAM permissions, and TLS + 1.3 encryption, without having to manage certificates. - NOTE: The proxy does not configure the network. You MUST ensure the proxy - can reach your AlloyDB instance, either by deploying it in a VPC that has - access to your instance, or by ensuring a network path to the instance. + NOTE: The proxy does not configure the network. You MUST ensure the proxy + can reach your AlloyDB instance, either by deploying it in a VPC that has + access to your instance, or by ensuring a network path to the instance. - For every provided instance connection name, the proxy creates: + For every provided instance connection name, the proxy creates: - - a socket that mimics a database running locally, and - - an encrypted connection using TLS 1.3 back to your AlloyDB instance. + - a socket that mimics a database running locally, and + - an encrypted connection using TLS 1.3 back to your AlloyDB instance. - The proxy uses an ephemeral certificate to establish a secure connection to - your AlloyDB instance. The proxy will refresh those certificates on an - hourly basis. Existing client connections are unaffected by the refresh - cycle. + The proxy uses an ephemeral certificate to establish a secure connection to + your AlloyDB instance. The proxy will refresh those certificates on an + hourly basis. Existing client connections are unaffected by the refresh + cycle. Authentication - The Proxy uses Application Default Credentials by default. Enable these - credentials with gcloud: + The Proxy uses Application Default Credentials by default. Enable these + credentials with gcloud: - gcloud auth application-default login + gcloud auth application-default login - In Google-run environments, Application Default Credentials are already - available and do not need to be retrieved. + In Google-run environments, Application Default Credentials are already + available and do not need to be retrieved. - The Proxy will use the environment's IAM principal when authenticating to - the backend. To use a specific set of credentials, use the - --credentials-file flag, e.g., + The Proxy will use the environment's IAM principal when authenticating to + the backend. To use a specific set of credentials, use the + --credentials-file flag, e.g., - ./alloydb-auth-proxy --credentials-file /path/to/key.json \ - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy --credentials-file /path/to/key.json \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - See the individual flags below, for more options. + See the individual flags below, for more options. Starting the Proxy - To start the proxy, you will need your instance URI, which may be found in - the AlloyDB instance overview page or by using gcloud with the following - command: + To start the proxy, you will need your instance URI, which may be found in + the AlloyDB instance overview page or by using gcloud with the following + command: - gcloud alpha alloydb instances describe INSTANCE_NAME \ - --region=REGION --cluster CLUSTER_NAME --format='value(name)' + gcloud alpha alloydb instances describe INSTANCE_NAME \ + --region=REGION --cluster CLUSTER_NAME --format='value(name)' - For example, if your instance URI is: + For example, if your instance URI is: - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - Starting the proxy will look like: + Starting the proxy will look like: - ./alloydb-auth-proxy \ - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - By default, the proxy will start a TCP listener on Postgres' default port - 5432. If multiple instances are specified which all use the same database - engine, the first will be started on the default port and subsequent - instances will be incremented from there (e.g., 5432, 5433, 5434, etc.) To - disable this behavior, use the --port flag. All subsequent listeners will - increment from the provided value. + By default, the proxy will start a TCP listener on Postgres' default port + 5432. If multiple instances are specified which all use the same database + engine, the first will be started on the default port and subsequent + instances will be incremented from there (e.g., 5432, 5433, 5434, etc.) To + disable this behavior, use the --port flag. All subsequent listeners will + increment from the provided value. - All socket listeners use the localhost network interface. To override this - behavior, use the --address flag. + All socket listeners use the localhost network interface. To override this + behavior, use the --address flag. Instance Level Configuration - The proxy supports overriding configuration on an instance-level with an - optional query string syntax using the corresponding full flag name. The - query string takes the form of a URL query string and should be appended to - the instance URI, e.g., + The proxy supports overriding configuration on an instance-level with an + optional query string syntax using the corresponding full flag name. The + query string takes the form of a URL query string and should be appended to + the instance URI, e.g., - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?key1=value1' + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?key1=value1' - When using the optional query string syntax, quotes must wrap the instance - connection name and query string to prevent conflicts with the shell. For - example, to override the address and port for one instance but otherwise use - the default behavior, use: + When using the optional query string syntax, quotes must wrap the instance + connection name and query string to prevent conflicts with the shell. For + example, to override the address and port for one instance but otherwise use + the default behavior, use: - ./alloydb-auth-proxy \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1' \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2?address=0.0.0.0&port=7000' + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1' \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2?address=0.0.0.0&port=7000' - When necessary, you may specify the full path to a Unix socket. Set the - unix-socket-path query parameter to the absolute path of the Unix socket for - the database instance. The parent directory of the unix-socket-path must - exist when the proxy starts or else socket creation will fail. For Postgres - instances, the proxy will ensure that the last path element is - '.s.PGSQL.5432' appending it if necessary. For example, + When necessary, you may specify the full path to a Unix socket. Set the + unix-socket-path query parameter to the absolute path of the Unix socket for + the database instance. The parent directory of the unix-socket-path must + exist when the proxy starts or else socket creation will fail. For Postgres + instances, the proxy will ensure that the last path element is + '.s.PGSQL.5432' appending it if necessary. For example, - ./alloydb-auth-proxy \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1?unix-socket-path=/path/to/socket' + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1?unix-socket-path=/path/to/socket' Automatic IAM Authentication - The Auth Proxy support Automatic IAM Authentication where the Proxy - retrieves the environment's IAM principal's OAuth2 token and supplies it to - the backend. When a client connects to the Proxy, there is no need to supply - a database user password. + The Auth Proxy support Automatic IAM Authentication where the Proxy + retrieves the environment's IAM principal's OAuth2 token and supplies it to + the backend. When a client connects to the Proxy, there is no need to supply + a database user password. - To enable the feature, run: + To enable the feature, run: - ./alloydb-auth-proxy \ - --auto-iam-authn \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE' + ./alloydb-auth-proxy \ + --auto-iam-authn \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE' - In addition, Auto IAM AuthN may be enabled on a per-instance basis with the - query string syntax described above. + In addition, Auto IAM AuthN may be enabled on a per-instance basis with the + query string syntax described above. - ./alloydb-auth-proxy \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?auto-iam-authn=true' + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?auto-iam-authn=true' Health checks - When enabling the --health-check flag, the proxy will start an HTTP server - on localhost with three endpoints: + When enabling the --health-check flag, the proxy will start an HTTP server + on localhost with three endpoints: - - /startup: Returns 200 status when the proxy has finished starting up. - Otherwise returns 503 status. + - /startup: Returns 200 status when the proxy has finished starting up. + Otherwise returns 503 status. - - /readiness: Returns 200 status when the proxy has started, has available - connections if max connections have been set with the --max-connections - flag, and when the proxy can connect to all registered instances. Otherwise, - returns a 503 status. + - /readiness: Returns 200 status when the proxy has started, has available + connections if max connections have been set with the --max-connections + flag, and when the proxy can connect to all registered instances. Otherwise, + returns a 503 status. - - /liveness: Always returns 200 status. If this endpoint is not responding, - the proxy is in a bad state and should be restarted. + - /liveness: Always returns 200 status. If this endpoint is not responding, + the proxy is in a bad state and should be restarted. - To configure the address, use --http-address. To configure the port, use - --http-port. + To configure the address, use --http-address. To configure the port, use + --http-port. Service Account Impersonation - The proxy supports service account impersonation with the - --impersonate-service-account flag and matches gcloud's flag. When enabled, - all API requests are made impersonating the supplied service account. The - IAM principal must have the iam.serviceAccounts.getAccessToken permission or - the role roles/iam.serviceAccounts.serviceAccountTokenCreator. + The proxy supports service account impersonation with the + --impersonate-service-account flag and matches gcloud's flag. When enabled, + all API requests are made impersonating the supplied service account. The + IAM principal must have the iam.serviceAccounts.getAccessToken permission or + the role roles/iam.serviceAccounts.serviceAccountTokenCreator. - For example: + For example: - ./alloydb-auth-proxy \ - --impersonate-service-account=impersonated@my-project.iam.gserviceaccount.com - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy \ + --impersonate-service-account=impersonated@my-project.iam.gserviceaccount.com + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - In addition, the flag supports an impersonation delegation chain where the - value is a comma-separated list of service accounts. The first service - account in the list is the impersonation target. Each subsequent service - account is a delegate to the previous service account. When delegation is - used, each delegate must have the permissions named above on the service - account it is delegating to. + In addition, the flag supports an impersonation delegation chain where the + value is a comma-separated list of service accounts. The first service + account in the list is the impersonation target. Each subsequent service + account is a delegate to the previous service account. When delegation is + used, each delegate must have the permissions named above on the service + account it is delegating to. - For example: + For example: - ./alloydb-auth-proxy \ - --impersonate-service-account=SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2,SERVICE_ACCOUNT_3 - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy \ + --impersonate-service-account=SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2,SERVICE_ACCOUNT_3 + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - In this example, the environment's IAM principal impersonates - SERVICE_ACCOUNT_3 which impersonates SERVICE_ACCOUNT_2 which then - impersonates the target SERVICE_ACCOUNT_1. + In this example, the environment's IAM principal impersonates + SERVICE_ACCOUNT_3 which impersonates SERVICE_ACCOUNT_2 which then + impersonates the target SERVICE_ACCOUNT_1. Configuration using environment variables - Instead of using CLI flags, the proxy may be configured using environment - variables. Each environment variable uses "ALLOYDB_PROXY" as a prefix and - is the uppercase version of the flag using underscores as word delimiters. - For example, the --structured-logs flag may be set with the environment - variable ALLOYDB_PROXY_STRUCTURED_LOGS. An invocation of the proxy using - environment variables would look like the following: + Instead of using CLI flags, the proxy may be configured using environment + variables. Each environment variable uses "ALLOYDB_PROXY" as a prefix and + is the uppercase version of the flag using underscores as word delimiters. + For example, the --structured-logs flag may be set with the environment + variable ALLOYDB_PROXY_STRUCTURED_LOGS. An invocation of the proxy using + environment variables would look like the following: - ALLOYDB_PROXY_STRUCTURED_LOGS=true \ - ./alloydb-auth-proxy \ - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ALLOYDB_PROXY_STRUCTURED_LOGS=true \ + ./alloydb-auth-proxy \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - In addition to CLI flags, instance URIs may also be specified with - environment variables. If invoking the proxy with only one instance URI, - use ALLOYDB_PROXY_INSTANCE_URI. For example: + In addition to CLI flags, instance URIs may also be specified with + environment variables. If invoking the proxy with only one instance URI, + use ALLOYDB_PROXY_INSTANCE_URI. For example: - ALLOYDB_PROXY_INSTANCE_URI=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \ - ./alloydb-auth-proxy + ALLOYDB_PROXY_INSTANCE_URI=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \ + ./alloydb-auth-proxy - If multiple instance URIs are used, add the index of the instance URI as a - suffix. For example: + If multiple instance URIs are used, add the index of the instance URI as a + suffix. For example: - ALLOYDB_PROXY_INSTANCE_URI_0=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1 \ - ALLOYDB_PROXY_INSTANCE_URI_1=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2 \ - ./alloydb-auth-proxy + ALLOYDB_PROXY_INSTANCE_URI_0=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1 \ + ALLOYDB_PROXY_INSTANCE_URI_1=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2 \ + ./alloydb-auth-proxy Configuration using a configuration file - Instead of using CLI flags, the Proxy may be configured using a configuration - file. The configuration file is a TOML, YAML or JSON file with the same keys - as the environment variables. The configuration file is specified with the - --config-file flag. An invocation of the Proxy using a configuration file - would look like the following: + Instead of using CLI flags, the Proxy may be configured using a configuration + file. The configuration file is a TOML, YAML or JSON file with the same keys + as the environment variables. The configuration file is specified with the + --config-file flag. An invocation of the Proxy using a configuration file + would look like the following: - ./alloydb-auth-proxy --config-file=config.toml + ./alloydb-auth-proxy --config-file=config.toml - The configuration file may look like the following: + The configuration file may look like the following: - instance-uri = "" - auto-iam-authn = true + instance-uri = "" + auto-iam-authn = true - If multiple instance URIs are used, add the index of the instance URI as a - suffix. For example: + If multiple instance URIs are used, add the index of the instance URI as a + suffix. For example: - instance-uri-0 = "" - instance-uri-1 = "" + instance-uri-0 = "" + instance-uri-1 = "" - The configuration file may also contain the same keys as the environment - variables and flags. For example: + The configuration file may also contain the same keys as the environment + variables and flags. For example: - auto-iam-authn = true - debug = true - max-connections = 5 + auto-iam-authn = true + debug = true + max-connections = 5 Localhost Admin Server - The Proxy includes support for an admin server on localhost. By default, - the admin server is not enabled. To enable the server, pass the --debug or - --quitquitquit flag. This will start the server on localhost at port 9091. - To change the port, use the --admin-port flag. + The Proxy includes support for an admin server on localhost. By default, + the admin server is not enabled. To enable the server, pass the --debug or + --quitquitquit flag. This will start the server on localhost at port 9091. + To change the port, use the --admin-port flag. - When --debug is set, the admin server enables Go's profiler available at - /debug/pprof/. + When --debug is set, the admin server enables Go's profiler available at + /debug/pprof/. - See the documentation on pprof for details on how to use the - profiler at https://pkg.go.dev/net/http/pprof. + See the documentation on pprof for details on how to use the + profiler at https://pkg.go.dev/net/http/pprof. - When --quitquitquit is set, the admin server adds an endpoint at - /quitquitquit. The admin server exits gracefully when it receives a POST - request at /quitquitquit. + When --quitquitquit is set, the admin server adds an endpoint at + /quitquitquit. The admin server exits gracefully when it receives a POST + request at /quitquitquit. Debug logging - On occasion, it can help to enable debug logging which will report on - internal certificate refresh operations. To enable debug logging, use: + On occasion, it can help to enable debug logging which will report on + internal certificate refresh operations. To enable debug logging, use: - ./alloydb-auth-proxy --debug-logs + ./alloydb-auth-proxy --debug-logs Waiting for Startup - See the wait subcommand's help for details. + See the wait subcommand's help for details. (*) indicates a flag that may be used as a query parameter Third Party Licenses - To view all licenses for third party dependencies used within this - distribution please see: + To view all licenses for third party dependencies used within this + distribution please see: - https://storage.googleapis.com/alloydb-auth-proxy/v1.16.0/third_party/licenses.tar.gz {x-release-please-version} + https://storage.googleapis.com/alloydb-auth-proxy/v1.16.0/third_party/licenses.tar.gz {x-release-please-version} Static Connection Info - In development contexts, it can be helpful to populate the Proxy with static - connection info. This is a *dev-only* feature and NOT for use in production. - The file format is subject to breaking changes. - - The format is: - - { - "publicKey": "", - "privateKey": "", - "projects//locations//clusters//instances/": { - "ipAddress": "", - "publicIpAddress": "", - "pscInstanceConfig": { - "pscDnsName": "" - }, - "pemCertificateChain": [ - "", "", "" - ], - "caCert": "" - } - } + In development contexts, it can be helpful to populate the Proxy with static + connection info. This is a *dev-only* feature and NOT for use in production. + The file format is subject to breaking changes. + + The format is: + + { + "publicKey": "", + "privateKey": "", + "projects//locations//clusters//instances/": { + "ipAddress": "", + "publicIpAddress": "", + "pscInstanceConfig": { + "pscDnsName": "" + }, + "pemCertificateChain": [ + "", "", "" + ], + "caCert": "" + } + } ` var shutdownHelp = ` Shutting Down the Proxy - The shutdown command signals a running Proxy process to gracefully shut - down. This is useful for scripting and for Kubernetes environments. + The shutdown command signals a running Proxy process to gracefully shut + down. This is useful for scripting and for Kubernetes environments. - The shutdown command requires that the Proxy be started in another process - with the admin server enabled. For example: + The shutdown command requires that the Proxy be started in another process + with the admin server enabled. For example: - ./alloydb-auth-proxy --quitquitquit + ./alloydb-auth-proxy --quitquitquit - Invoke the shutdown command like this: + Invoke the shutdown command like this: - # signals another Proxy process to shut down - ./alloydb-auth-proxy shutdown + # signals another Proxy process to shut down + ./alloydb-auth-proxy shutdown Configuration - If the running Proxy is configured with a non-default admin port, the - shutdown command must also be told to use the same custom value: + If the running Proxy is configured with a non-default admin port, the + shutdown command must also be told to use the same custom value: - ./alloydb-auth-proxy shutdown --admin-port 9192 + ./alloydb-auth-proxy shutdown --admin-port 9192 ` var waitHelp = ` - Sometimes it is necessary to wait for the Proxy to start. + Sometimes it is necessary to wait for the Proxy to start. - To help ensure the Proxy is up and ready, the Proxy includes a wait - subcommand with an optional --max flag to set the maximum time to wait. + To help ensure the Proxy is up and ready, the Proxy includes a wait + subcommand with an optional --max flag to set the maximum time to wait. - Invoke the wait command, like this: + Invoke the wait command, like this: - ./alloydb-auth-proxy wait + ./alloydb-auth-proxy wait - By default, the Proxy will wait up to the maximum time for the startup - endpoint to respond. The wait command requires that the Proxy be started in - another process with the HTTP health check enabled. If an alternate health - check port or address is used, as in: + By default, the Proxy will wait up to the maximum time for the startup + endpoint to respond. The wait command requires that the Proxy be started in + another process with the HTTP health check enabled. If an alternate health + check port or address is used, as in: - ./alloydb-auth-proxy \ - --http-address 0.0.0.0 \ - --http-port 9191 + ./alloydb-auth-proxy \ + --http-address 0.0.0.0 \ + --http-port 9191 - Then the wait command must also be told to use the same custom values: + Then the wait command must also be told to use the same custom values: - ./alloydb-auth-proxy wait \ - --http-address 0.0.0.0 \ - --http-port 9191 + ./alloydb-auth-proxy wait \ + --http-address 0.0.0.0 \ + --http-port 9191 - By default the wait command will wait 30 seconds. To alter this value, - use: + By default the wait command will wait 30 seconds. To alter this value, + use: - ./alloydb-auth-proxy wait --max 10s + ./alloydb-auth-proxy wait --max 10s ` const envPrefix = "ALLOYDB_PROXY" func instanceFromEnv(args []string) []string { // This supports naming the first instance first with: - // INSTANCE_URI + // INSTANCE_URI // or if that's not defined, with: - // INSTANCE_URI_0 + // INSTANCE_URI_0 inst := os.Getenv(fmt.Sprintf("%s_INSTANCE_URI", envPrefix)) if inst == "" { inst = os.Getenv(fmt.Sprintf("%s_INSTANCE_URI_0", envPrefix)) @@ -486,7 +486,7 @@ const ( waitMaxFlag = "max" adminPortFlag = "admin-port" httpAddressFlag = "http-address" - httpPortFlag = "http-port" + httpPortFlag = "http-port" ) func runShutdownCmd(c *cobra.Command, _ []string) error { @@ -920,7 +920,7 @@ func parseConfig(cmd *Command, conf *proxy.Config, args []string) error { conf.APIEndpointURL, )) } - cmd.logger.Infof("Using API Endpoint %v", conf.APIEndpointURL) + cmd.logger.Infof("Using API Endpoint %v", conf.APIEndpointURL) } if userHasSetGlobal(cmd, "http-port") && !userHasSetLocal(cmd, "prometheus") && !userHasSetLocal(cmd, "health-check") { @@ -1097,7 +1097,7 @@ func runSignalWrapper(cmd *Command) (err error) { enableTraces := !cmd.conf.DisableTraces if cmd.conf.TelemetryProject != "" && (enableMetrics || enableTraces) { sd, err := stackdriver.NewExporter(stackdriver.Options{ - ProjectID: cmd.conf.TelemetryProject, + ProjectID: cmd.conf.TelemetryProject, MetricPrefix: cmd.conf.TelemetryPrefix, }) if err != nil { @@ -1188,7 +1188,7 @@ func runSignalWrapper(cmd *Command) (err error) { var ( needsHTTPServer bool - mux = http.NewServeMux() + mux = http.NewServeMux() notifyStarted = func() {} notifyStopped = func() {} ) @@ -1229,7 +1229,7 @@ func runSignalWrapper(cmd *Command) (err error) { var ( needsAdminServer bool - m = http.NewServeMux() + m = http.NewServeMux() ) if cmd.conf.QuitQuitQuit { needsAdminServer = true @@ -1296,7 +1296,7 @@ func quitquitquit(quitOnce *sync.Once, shutdownCh chan<- error) http.HandlerFunc func startHTTPServer(ctx context.Context, l alloydb.Logger, addr string, mux *http.ServeMux, shutdownCh chan<- error) { server := &http.Server{ - Addr: addr, + Addr: addr, Handler: mux, } // Start the HTTP server. diff --git a/go.mod b/go.mod index cfb60dfc..f4baedfc 100644 --- a/go.mod +++ b/go.mod @@ -3,7 +3,7 @@ module github.com/GoogleCloudPlatform/alloydb-auth-proxy go 1.25.8 require ( - cloud.google.com/go/alloydbconn v1.18.7-0.20260827155541-3eabf98461a9 + cloud.google.com/go/alloydbconn v1.18.6 contrib.go.opencensus.io/exporter/prometheus v0.4.2 contrib.go.opencensus.io/exporter/stackdriver v0.13.14 github.com/coreos/go-systemd/v22 v22.7.0 diff --git a/go.sum b/go.sum index e5c7e2ad..83c38e03 100644 --- a/go.sum +++ b/go.sum @@ -17,8 +17,8 @@ cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE= cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU= cloud.google.com/go/alloydb v1.26.0 h1:UTzyumJ8tEo0CqwzLkV4WMGnCxvvhw3BDy1nXfCt9KE= cloud.google.com/go/alloydb v1.26.0/go.mod h1:oqHGc/Xb5fWtH+wIDpu2wcPJX9oML/fGJuH/sp8ysyo= -cloud.google.com/go/alloydbconn v1.18.7-0.20260827155541-3eabf98461a9 h1:UjA0HtMMTcM+eSiGGwMHJYnQr3KF0KKZrYUcqzuWceQ= -cloud.google.com/go/alloydbconn v1.18.7-0.20260827155541-3eabf98461a9/go.mod h1:P70koybK8sRT5E11jBlCQxthyWc3+Y0gKhA4hL1favE= +cloud.google.com/go/alloydbconn v1.18.6 h1:vtRmNRk1kq0QjJ8lbrPLeooIVqCbKcDxKycRtmb6gsQ= +cloud.google.com/go/alloydbconn v1.18.6/go.mod h1:P70koybK8sRT5E11jBlCQxthyWc3+Y0gKhA4hL1favE= cloud.google.com/go/auth v0.23.0 h1:6Gg1CMgpgubRG7DGz5Vf1pcoNo8RfiRiRAPS4crTp54= cloud.google.com/go/auth v0.23.0/go.mod h1:4DhBRcqvtljQN3dJ57qtqbib5ZGCYE5f2crfiiC2EM0= cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc= From 081bdf30265cd34f73600c64a42b7865a5947d0e Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Mon, 31 Aug 2026 16:29:33 -0700 Subject: [PATCH 18/21] fix spacing --- cmd/root.go | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index e81b5218..7ce65c49 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -89,7 +89,7 @@ func Execute() { // Command represents an invocation of the AlloyDB Auth Proxy. type Command struct { *cobra.Command - conf *proxy.Config + conf *proxy.Config logger alloydb.Logger dialer alloydb.Dialer cleanup func() error @@ -1097,7 +1097,7 @@ func runSignalWrapper(cmd *Command) (err error) { enableTraces := !cmd.conf.DisableTraces if cmd.conf.TelemetryProject != "" && (enableMetrics || enableTraces) { sd, err := stackdriver.NewExporter(stackdriver.Options{ - ProjectID: cmd.conf.TelemetryProject, + ProjectID: cmd.conf.TelemetryProject, MetricPrefix: cmd.conf.TelemetryPrefix, }) if err != nil { @@ -1188,7 +1188,7 @@ func runSignalWrapper(cmd *Command) (err error) { var ( needsHTTPServer bool - mux = http.NewServeMux() + mux = http.NewServeMux() notifyStarted = func() {} notifyStopped = func() {} ) @@ -1229,7 +1229,7 @@ func runSignalWrapper(cmd *Command) (err error) { var ( needsAdminServer bool - m = http.NewServeMux() + m = http.NewServeMux() ) if cmd.conf.QuitQuitQuit { needsAdminServer = true @@ -1296,7 +1296,7 @@ func quitquitquit(quitOnce *sync.Once, shutdownCh chan<- error) http.HandlerFunc func startHTTPServer(ctx context.Context, l alloydb.Logger, addr string, mux *http.ServeMux, shutdownCh chan<- error) { server := &http.Server{ - Addr: addr, + Addr: addr, Handler: mux, } // Start the HTTP server. From a341110f1baa2c4d3761c8ddd02751beca055e38 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Mon, 31 Aug 2026 16:31:10 -0700 Subject: [PATCH 19/21] fix spacing --- cmd/root.go | 436 ++++++++++++++++++++++++++-------------------------- 1 file changed, 218 insertions(+), 218 deletions(-) diff --git a/cmd/root.go b/cmd/root.go index 7ce65c49..5ddaadce 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -116,349 +116,349 @@ func WithDialer(d alloydb.Dialer) Option { var longHelp = ` Overview - The AlloyDB Auth proxy is a utility for ensuring secure connections - to your AlloyDB instances. It provides IAM authorization, allowing you - to control who can connect to your instances through IAM permissions, and TLS - 1.3 encryption, without having to manage certificates. + The AlloyDB Auth proxy is a utility for ensuring secure connections + to your AlloyDB instances. It provides IAM authorization, allowing you + to control who can connect to your instances through IAM permissions, and TLS + 1.3 encryption, without having to manage certificates. - NOTE: The proxy does not configure the network. You MUST ensure the proxy - can reach your AlloyDB instance, either by deploying it in a VPC that has - access to your instance, or by ensuring a network path to the instance. + NOTE: The proxy does not configure the network. You MUST ensure the proxy + can reach your AlloyDB instance, either by deploying it in a VPC that has + access to your instance, or by ensuring a network path to the instance. - For every provided instance connection name, the proxy creates: + For every provided instance connection name, the proxy creates: - - a socket that mimics a database running locally, and - - an encrypted connection using TLS 1.3 back to your AlloyDB instance. + - a socket that mimics a database running locally, and + - an encrypted connection using TLS 1.3 back to your AlloyDB instance. - The proxy uses an ephemeral certificate to establish a secure connection to - your AlloyDB instance. The proxy will refresh those certificates on an - hourly basis. Existing client connections are unaffected by the refresh - cycle. + The proxy uses an ephemeral certificate to establish a secure connection to + your AlloyDB instance. The proxy will refresh those certificates on an + hourly basis. Existing client connections are unaffected by the refresh + cycle. Authentication - The Proxy uses Application Default Credentials by default. Enable these - credentials with gcloud: + The Proxy uses Application Default Credentials by default. Enable these + credentials with gcloud: - gcloud auth application-default login + gcloud auth application-default login - In Google-run environments, Application Default Credentials are already - available and do not need to be retrieved. + In Google-run environments, Application Default Credentials are already + available and do not need to be retrieved. - The Proxy will use the environment's IAM principal when authenticating to - the backend. To use a specific set of credentials, use the - --credentials-file flag, e.g., + The Proxy will use the environment's IAM principal when authenticating to + the backend. To use a specific set of credentials, use the + --credentials-file flag, e.g., - ./alloydb-auth-proxy --credentials-file /path/to/key.json \ - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy --credentials-file /path/to/key.json \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - See the individual flags below, for more options. + See the individual flags below, for more options. Starting the Proxy - To start the proxy, you will need your instance URI, which may be found in - the AlloyDB instance overview page or by using gcloud with the following - command: + To start the proxy, you will need your instance URI, which may be found in + the AlloyDB instance overview page or by using gcloud with the following + command: - gcloud alpha alloydb instances describe INSTANCE_NAME \ - --region=REGION --cluster CLUSTER_NAME --format='value(name)' + gcloud alpha alloydb instances describe INSTANCE_NAME \ + --region=REGION --cluster CLUSTER_NAME --format='value(name)' - For example, if your instance URI is: + For example, if your instance URI is: - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - Starting the proxy will look like: + Starting the proxy will look like: - ./alloydb-auth-proxy \ - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - By default, the proxy will start a TCP listener on Postgres' default port - 5432. If multiple instances are specified which all use the same database - engine, the first will be started on the default port and subsequent - instances will be incremented from there (e.g., 5432, 5433, 5434, etc.) To - disable this behavior, use the --port flag. All subsequent listeners will - increment from the provided value. + By default, the proxy will start a TCP listener on Postgres' default port + 5432. If multiple instances are specified which all use the same database + engine, the first will be started on the default port and subsequent + instances will be incremented from there (e.g., 5432, 5433, 5434, etc.) To + disable this behavior, use the --port flag. All subsequent listeners will + increment from the provided value. - All socket listeners use the localhost network interface. To override this - behavior, use the --address flag. + All socket listeners use the localhost network interface. To override this + behavior, use the --address flag. Instance Level Configuration - The proxy supports overriding configuration on an instance-level with an - optional query string syntax using the corresponding full flag name. The - query string takes the form of a URL query string and should be appended to - the instance URI, e.g., + The proxy supports overriding configuration on an instance-level with an + optional query string syntax using the corresponding full flag name. The + query string takes the form of a URL query string and should be appended to + the instance URI, e.g., - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?key1=value1' + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?key1=value1' - When using the optional query string syntax, quotes must wrap the instance - connection name and query string to prevent conflicts with the shell. For - example, to override the address and port for one instance but otherwise use - the default behavior, use: + When using the optional query string syntax, quotes must wrap the instance + connection name and query string to prevent conflicts with the shell. For + example, to override the address and port for one instance but otherwise use + the default behavior, use: - ./alloydb-auth-proxy \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1' \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2?address=0.0.0.0&port=7000' + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1' \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2?address=0.0.0.0&port=7000' - When necessary, you may specify the full path to a Unix socket. Set the - unix-socket-path query parameter to the absolute path of the Unix socket for - the database instance. The parent directory of the unix-socket-path must - exist when the proxy starts or else socket creation will fail. For Postgres - instances, the proxy will ensure that the last path element is - '.s.PGSQL.5432' appending it if necessary. For example, + When necessary, you may specify the full path to a Unix socket. Set the + unix-socket-path query parameter to the absolute path of the Unix socket for + the database instance. The parent directory of the unix-socket-path must + exist when the proxy starts or else socket creation will fail. For Postgres + instances, the proxy will ensure that the last path element is + '.s.PGSQL.5432' appending it if necessary. For example, - ./alloydb-auth-proxy \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1?unix-socket-path=/path/to/socket' + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1?unix-socket-path=/path/to/socket' Automatic IAM Authentication - The Auth Proxy support Automatic IAM Authentication where the Proxy - retrieves the environment's IAM principal's OAuth2 token and supplies it to - the backend. When a client connects to the Proxy, there is no need to supply - a database user password. + The Auth Proxy support Automatic IAM Authentication where the Proxy + retrieves the environment's IAM principal's OAuth2 token and supplies it to + the backend. When a client connects to the Proxy, there is no need to supply + a database user password. - To enable the feature, run: + To enable the feature, run: - ./alloydb-auth-proxy \ - --auto-iam-authn \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE' + ./alloydb-auth-proxy \ + --auto-iam-authn \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE' - In addition, Auto IAM AuthN may be enabled on a per-instance basis with the - query string syntax described above. + In addition, Auto IAM AuthN may be enabled on a per-instance basis with the + query string syntax described above. - ./alloydb-auth-proxy \ - 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?auto-iam-authn=true' + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?auto-iam-authn=true' Health checks - When enabling the --health-check flag, the proxy will start an HTTP server - on localhost with three endpoints: + When enabling the --health-check flag, the proxy will start an HTTP server + on localhost with three endpoints: - - /startup: Returns 200 status when the proxy has finished starting up. - Otherwise returns 503 status. + - /startup: Returns 200 status when the proxy has finished starting up. + Otherwise returns 503 status. - - /readiness: Returns 200 status when the proxy has started, has available - connections if max connections have been set with the --max-connections - flag, and when the proxy can connect to all registered instances. Otherwise, - returns a 503 status. + - /readiness: Returns 200 status when the proxy has started, has available + connections if max connections have been set with the --max-connections + flag, and when the proxy can connect to all registered instances. Otherwise, + returns a 503 status. - - /liveness: Always returns 200 status. If this endpoint is not responding, - the proxy is in a bad state and should be restarted. + - /liveness: Always returns 200 status. If this endpoint is not responding, + the proxy is in a bad state and should be restarted. - To configure the address, use --http-address. To configure the port, use - --http-port. + To configure the address, use --http-address. To configure the port, use + --http-port. Service Account Impersonation - The proxy supports service account impersonation with the - --impersonate-service-account flag and matches gcloud's flag. When enabled, - all API requests are made impersonating the supplied service account. The - IAM principal must have the iam.serviceAccounts.getAccessToken permission or - the role roles/iam.serviceAccounts.serviceAccountTokenCreator. + The proxy supports service account impersonation with the + --impersonate-service-account flag and matches gcloud's flag. When enabled, + all API requests are made impersonating the supplied service account. The + IAM principal must have the iam.serviceAccounts.getAccessToken permission or + the role roles/iam.serviceAccounts.serviceAccountTokenCreator. - For example: + For example: - ./alloydb-auth-proxy \ - --impersonate-service-account=impersonated@my-project.iam.gserviceaccount.com - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy \ + --impersonate-service-account=impersonated@my-project.iam.gserviceaccount.com + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - In addition, the flag supports an impersonation delegation chain where the - value is a comma-separated list of service accounts. The first service - account in the list is the impersonation target. Each subsequent service - account is a delegate to the previous service account. When delegation is - used, each delegate must have the permissions named above on the service - account it is delegating to. + In addition, the flag supports an impersonation delegation chain where the + value is a comma-separated list of service accounts. The first service + account in the list is the impersonation target. Each subsequent service + account is a delegate to the previous service account. When delegation is + used, each delegate must have the permissions named above on the service + account it is delegating to. - For example: + For example: - ./alloydb-auth-proxy \ - --impersonate-service-account=SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2,SERVICE_ACCOUNT_3 - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ./alloydb-auth-proxy \ + --impersonate-service-account=SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2,SERVICE_ACCOUNT_3 + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - In this example, the environment's IAM principal impersonates - SERVICE_ACCOUNT_3 which impersonates SERVICE_ACCOUNT_2 which then - impersonates the target SERVICE_ACCOUNT_1. + In this example, the environment's IAM principal impersonates + SERVICE_ACCOUNT_3 which impersonates SERVICE_ACCOUNT_2 which then + impersonates the target SERVICE_ACCOUNT_1. Configuration using environment variables - Instead of using CLI flags, the proxy may be configured using environment - variables. Each environment variable uses "ALLOYDB_PROXY" as a prefix and - is the uppercase version of the flag using underscores as word delimiters. - For example, the --structured-logs flag may be set with the environment - variable ALLOYDB_PROXY_STRUCTURED_LOGS. An invocation of the proxy using - environment variables would look like the following: + Instead of using CLI flags, the proxy may be configured using environment + variables. Each environment variable uses "ALLOYDB_PROXY" as a prefix and + is the uppercase version of the flag using underscores as word delimiters. + For example, the --structured-logs flag may be set with the environment + variable ALLOYDB_PROXY_STRUCTURED_LOGS. An invocation of the proxy using + environment variables would look like the following: - ALLOYDB_PROXY_STRUCTURED_LOGS=true \ - ./alloydb-auth-proxy \ - projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + ALLOYDB_PROXY_STRUCTURED_LOGS=true \ + ./alloydb-auth-proxy \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE - In addition to CLI flags, instance URIs may also be specified with - environment variables. If invoking the proxy with only one instance URI, - use ALLOYDB_PROXY_INSTANCE_URI. For example: + In addition to CLI flags, instance URIs may also be specified with + environment variables. If invoking the proxy with only one instance URI, + use ALLOYDB_PROXY_INSTANCE_URI. For example: - ALLOYDB_PROXY_INSTANCE_URI=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \ - ./alloydb-auth-proxy + ALLOYDB_PROXY_INSTANCE_URI=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \ + ./alloydb-auth-proxy - If multiple instance URIs are used, add the index of the instance URI as a - suffix. For example: + If multiple instance URIs are used, add the index of the instance URI as a + suffix. For example: - ALLOYDB_PROXY_INSTANCE_URI_0=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1 \ - ALLOYDB_PROXY_INSTANCE_URI_1=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2 \ - ./alloydb-auth-proxy + ALLOYDB_PROXY_INSTANCE_URI_0=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1 \ + ALLOYDB_PROXY_INSTANCE_URI_1=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2 \ + ./alloydb-auth-proxy Configuration using a configuration file - Instead of using CLI flags, the Proxy may be configured using a configuration - file. The configuration file is a TOML, YAML or JSON file with the same keys - as the environment variables. The configuration file is specified with the - --config-file flag. An invocation of the Proxy using a configuration file - would look like the following: + Instead of using CLI flags, the Proxy may be configured using a configuration + file. The configuration file is a TOML, YAML or JSON file with the same keys + as the environment variables. The configuration file is specified with the + --config-file flag. An invocation of the Proxy using a configuration file + would look like the following: - ./alloydb-auth-proxy --config-file=config.toml + ./alloydb-auth-proxy --config-file=config.toml - The configuration file may look like the following: + The configuration file may look like the following: - instance-uri = "" - auto-iam-authn = true + instance-uri = "" + auto-iam-authn = true - If multiple instance URIs are used, add the index of the instance URI as a - suffix. For example: + If multiple instance URIs are used, add the index of the instance URI as a + suffix. For example: - instance-uri-0 = "" - instance-uri-1 = "" + instance-uri-0 = "" + instance-uri-1 = "" - The configuration file may also contain the same keys as the environment - variables and flags. For example: + The configuration file may also contain the same keys as the environment + variables and flags. For example: - auto-iam-authn = true - debug = true - max-connections = 5 + auto-iam-authn = true + debug = true + max-connections = 5 Localhost Admin Server - The Proxy includes support for an admin server on localhost. By default, - the admin server is not enabled. To enable the server, pass the --debug or - --quitquitquit flag. This will start the server on localhost at port 9091. - To change the port, use the --admin-port flag. + The Proxy includes support for an admin server on localhost. By default, + the admin server is not enabled. To enable the server, pass the --debug or + --quitquitquit flag. This will start the server on localhost at port 9091. + To change the port, use the --admin-port flag. - When --debug is set, the admin server enables Go's profiler available at - /debug/pprof/. + When --debug is set, the admin server enables Go's profiler available at + /debug/pprof/. - See the documentation on pprof for details on how to use the - profiler at https://pkg.go.dev/net/http/pprof. + See the documentation on pprof for details on how to use the + profiler at https://pkg.go.dev/net/http/pprof. - When --quitquitquit is set, the admin server adds an endpoint at - /quitquitquit. The admin server exits gracefully when it receives a POST - request at /quitquitquit. + When --quitquitquit is set, the admin server adds an endpoint at + /quitquitquit. The admin server exits gracefully when it receives a POST + request at /quitquitquit. Debug logging - On occasion, it can help to enable debug logging which will report on - internal certificate refresh operations. To enable debug logging, use: + On occasion, it can help to enable debug logging which will report on + internal certificate refresh operations. To enable debug logging, use: - ./alloydb-auth-proxy --debug-logs + ./alloydb-auth-proxy --debug-logs Waiting for Startup - See the wait subcommand's help for details. + See the wait subcommand's help for details. (*) indicates a flag that may be used as a query parameter Third Party Licenses - To view all licenses for third party dependencies used within this - distribution please see: + To view all licenses for third party dependencies used within this + distribution please see: - https://storage.googleapis.com/alloydb-auth-proxy/v1.16.0/third_party/licenses.tar.gz {x-release-please-version} + https://storage.googleapis.com/alloydb-auth-proxy/v1.16.0/third_party/licenses.tar.gz {x-release-please-version} Static Connection Info - In development contexts, it can be helpful to populate the Proxy with static - connection info. This is a *dev-only* feature and NOT for use in production. - The file format is subject to breaking changes. - - The format is: - - { - "publicKey": "", - "privateKey": "", - "projects//locations//clusters//instances/": { - "ipAddress": "", - "publicIpAddress": "", - "pscInstanceConfig": { - "pscDnsName": "" - }, - "pemCertificateChain": [ - "", "", "" - ], - "caCert": "" - } - } + In development contexts, it can be helpful to populate the Proxy with static + connection info. This is a *dev-only* feature and NOT for use in production. + The file format is subject to breaking changes. + + The format is: + + { + "publicKey": "", + "privateKey": "", + "projects//locations//clusters//instances/": { + "ipAddress": "", + "publicIpAddress": "", + "pscInstanceConfig": { + "pscDnsName": "" + }, + "pemCertificateChain": [ + "", "", "" + ], + "caCert": "" + } + } ` var shutdownHelp = ` Shutting Down the Proxy - The shutdown command signals a running Proxy process to gracefully shut - down. This is useful for scripting and for Kubernetes environments. + The shutdown command signals a running Proxy process to gracefully shut + down. This is useful for scripting and for Kubernetes environments. - The shutdown command requires that the Proxy be started in another process - with the admin server enabled. For example: + The shutdown command requires that the Proxy be started in another process + with the admin server enabled. For example: - ./alloydb-auth-proxy --quitquitquit + ./alloydb-auth-proxy --quitquitquit - Invoke the shutdown command like this: + Invoke the shutdown command like this: - # signals another Proxy process to shut down - ./alloydb-auth-proxy shutdown + # signals another Proxy process to shut down + ./alloydb-auth-proxy shutdown Configuration - If the running Proxy is configured with a non-default admin port, the - shutdown command must also be told to use the same custom value: + If the running Proxy is configured with a non-default admin port, the + shutdown command must also be told to use the same custom value: - ./alloydb-auth-proxy shutdown --admin-port 9192 + ./alloydb-auth-proxy shutdown --admin-port 9192 ` var waitHelp = ` - Sometimes it is necessary to wait for the Proxy to start. + Sometimes it is necessary to wait for the Proxy to start. - To help ensure the Proxy is up and ready, the Proxy includes a wait - subcommand with an optional --max flag to set the maximum time to wait. + To help ensure the Proxy is up and ready, the Proxy includes a wait + subcommand with an optional --max flag to set the maximum time to wait. - Invoke the wait command, like this: + Invoke the wait command, like this: - ./alloydb-auth-proxy wait + ./alloydb-auth-proxy wait - By default, the Proxy will wait up to the maximum time for the startup - endpoint to respond. The wait command requires that the Proxy be started in - another process with the HTTP health check enabled. If an alternate health - check port or address is used, as in: + By default, the Proxy will wait up to the maximum time for the startup + endpoint to respond. The wait command requires that the Proxy be started in + another process with the HTTP health check enabled. If an alternate health + check port or address is used, as in: - ./alloydb-auth-proxy \ - --http-address 0.0.0.0 \ - --http-port 9191 + ./alloydb-auth-proxy \ + --http-address 0.0.0.0 \ + --http-port 9191 - Then the wait command must also be told to use the same custom values: + Then the wait command must also be told to use the same custom values: - ./alloydb-auth-proxy wait \ - --http-address 0.0.0.0 \ - --http-port 9191 + ./alloydb-auth-proxy wait \ + --http-address 0.0.0.0 \ + --http-port 9191 - By default the wait command will wait 30 seconds. To alter this value, - use: + By default the wait command will wait 30 seconds. To alter this value, + use: - ./alloydb-auth-proxy wait --max 10s + ./alloydb-auth-proxy wait --max 10s ` const envPrefix = "ALLOYDB_PROXY" func instanceFromEnv(args []string) []string { // This supports naming the first instance first with: - // INSTANCE_URI + // INSTANCE_URI // or if that's not defined, with: - // INSTANCE_URI_0 + // INSTANCE_URI_0 inst := os.Getenv(fmt.Sprintf("%s_INSTANCE_URI", envPrefix)) if inst == "" { inst = os.Getenv(fmt.Sprintf("%s_INSTANCE_URI_0", envPrefix)) @@ -486,7 +486,7 @@ const ( waitMaxFlag = "max" adminPortFlag = "admin-port" httpAddressFlag = "http-address" - httpPortFlag = "http-port" + httpPortFlag = "http-port" ) func runShutdownCmd(c *cobra.Command, _ []string) error { From 5fa907fb7aa7df06e4b0d98e01280f312c534e5d Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Tue, 1 Sep 2026 10:06:10 -0700 Subject: [PATCH 20/21] chore: trigger pipeline From 986c0b69fc0930936ad54e0cb2164c158f788d59 Mon Sep 17 00:00:00 2001 From: Warren Tian Date: Wed, 2 Sep 2026 16:48:45 -0700 Subject: [PATCH 21/21] chore: trigger pipeline