Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

feat(store): support Private IP / PSC for metadata DB Cloud SQL IAM (#20716)

Vincent Huang5cdd690e464a
diff --git a/backend/store/dbauth/auth.go b/backend/store/dbauth/auth.go
index 753a021f08..5b1e63e52c 100644
--- a/backend/store/dbauth/auth.go
+++ b/backend/store/dbauth/auth.go
@@ -55,7 +55,7 @@ func configureAWS(ctx context.Context, authConfig *awsConfig) ([]stdlib.OptionOp
}
func configureGCP(ctx context.Context, pgxConfig *pgx.ConnConfig, authConfig *gcpConfig) ([]stdlib.OptionOpenDB, func() error, error) {
- dialer, err := newGCPMetadataDBDialer(ctx)
+ dialer, err := newGCPMetadataDBDialer(ctx, authConfig.ipType)
if err != nil {
return nil, nil, err
}
@@ -65,7 +65,7 @@ func configureGCP(ctx context.Context, pgxConfig *pgx.ConnConfig, authConfig *gc
// IsKeywordValueRuntimeParam reports whether key is a Bytebase metadata DB auth runtime parameter.
func IsKeywordValueRuntimeParam(key string) bool {
switch key {
- case awsRDSIAMParam, awsRegionParam, gcpCloudSQLIAMParam, gcpCloudSQLInstanceConnectionNameParam:
+ case awsRDSIAMParam, awsRegionParam, gcpCloudSQLIAMParam, gcpCloudSQLInstanceConnectionNameParam, gcpCloudSQLIPTypeParam:
return true
default:
return false
diff --git a/backend/store/dbauth/gcp.go b/backend/store/dbauth/gcp.go
index 2f88da237d..c1900cfc05 100644
--- a/backend/store/dbauth/gcp.go
+++ b/backend/store/dbauth/gcp.go
@@ -13,11 +13,17 @@ import (
const (
gcpCloudSQLIAMParam = "bytebase_gcp_cloud_sql_iam"
gcpCloudSQLInstanceConnectionNameParam = "bytebase_gcp_cloud_sql_instance_connection_name"
+ gcpCloudSQLIPTypeParam = "bytebase_gcp_cloud_sql_ip_type"
+
+ gcpCloudSQLIPTypePublic = "public"
+ gcpCloudSQLIPTypePrivate = "private"
+ gcpCloudSQLIPTypePSC = "psc"
)
type gcpConfig struct {
enabled bool
instanceConnectionName string
+ ipType string
}
type gcpDialer interface {
@@ -29,14 +35,29 @@ type gcpMetadataDBDialer struct {
dialer *cloudsqlconn.Dialer
}
-func newGCPMetadataDBDialer(ctx context.Context) (*gcpMetadataDBDialer, error) {
- dialer, err := cloudsqlconn.NewDialer(ctx, cloudsqlconn.WithIAMAuthN())
+func newGCPMetadataDBDialer(ctx context.Context, ipType string) (*gcpMetadataDBDialer, error) {
+ opts := append([]cloudsqlconn.Option{cloudsqlconn.WithIAMAuthN()}, gcpDialIPOptions(ipType)...)
+ dialer, err := cloudsqlconn.NewDialer(ctx, opts...)
if err != nil {
return nil, errors.Wrap(err, "failed to create GCP Cloud SQL dialer")
}
return &gcpMetadataDBDialer{dialer: dialer}, nil
}
+// gcpDialIPOptions selects the Cloud SQL IP type (private or PSC) for the metadata
+// database connection. Public IP is the cloudsqlconn default, so no option is
+// needed for public or unspecified.
+func gcpDialIPOptions(ipType string) []cloudsqlconn.Option {
+ switch ipType {
+ case gcpCloudSQLIPTypePrivate:
+ return []cloudsqlconn.Option{cloudsqlconn.WithDefaultDialOptions(cloudsqlconn.WithPrivateIP())}
+ case gcpCloudSQLIPTypePSC:
+ return []cloudsqlconn.Option{cloudsqlconn.WithDefaultDialOptions(cloudsqlconn.WithPSC())}
+ default:
+ return nil
+ }
+}
+
func (d *gcpMetadataDBDialer) Dial(ctx context.Context, instanceConnectionName string) (net.Conn, error) {
return d.dialer.Dial(ctx, instanceConnectionName)
}
@@ -48,8 +69,10 @@ func (d *gcpMetadataDBDialer) Close() error {
func gcpConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*gcpConfig, error) {
iamEnabled := pgxConfig.RuntimeParams[gcpCloudSQLIAMParam] == "true"
instanceConnectionName := pgxConfig.RuntimeParams[gcpCloudSQLInstanceConnectionNameParam]
+ ipType := pgxConfig.RuntimeParams[gcpCloudSQLIPTypeParam]
delete(pgxConfig.RuntimeParams, gcpCloudSQLIAMParam)
delete(pgxConfig.RuntimeParams, gcpCloudSQLInstanceConnectionNameParam)
+ delete(pgxConfig.RuntimeParams, gcpCloudSQLIPTypeParam)
if !iamEnabled {
return nil, nil
@@ -63,9 +86,16 @@ func gcpConfigFromPGXConfig(pgxConfig *pgx.ConnConfig) (*gcpConfig, error) {
return nil, errors.New("database user is required when metadata database GCP Cloud SQL IAM auth is enabled")
}
+ switch ipType {
+ case "", gcpCloudSQLIPTypePublic, gcpCloudSQLIPTypePrivate, gcpCloudSQLIPTypePSC:
+ default:
+ return nil, errors.Errorf("%s must be one of %q, %q, or %q", gcpCloudSQLIPTypeParam, gcpCloudSQLIPTypePublic, gcpCloudSQLIPTypePrivate, gcpCloudSQLIPTypePSC)
+ }
+
return &gcpConfig{
enabled: true,
instanceConnectionName: instanceConnectionName,
+ ipType: ipType,
}, nil
}
diff --git a/backend/store/dbauth/gcp_test.go b/backend/store/dbauth/gcp_test.go
index 92696548a1..f7bb2d6c97 100644
--- a/backend/store/dbauth/gcp_test.go
+++ b/backend/store/dbauth/gcp_test.go
@@ -136,3 +136,58 @@ func TestConfigureRejectsMultipleMetadataDBAuthProviders(t *testing.T) {
require.ErrorContains(t, err, "multiple metadata database IAM auth providers are enabled")
}
+
+func TestGCPConfigFromPGXConfigParsesIPType(t *testing.T) {
+ tests := []struct {
+ name string
+ param string
+ expect string
+ }{
+ {"default", "", ""},
+ {"public", "&bytebase_gcp_cloud_sql_ip_type=public", "public"},
+ {"private", "&bytebase_gcp_cloud_sql_ip_type=private", "private"},
+ {"psc", "&bytebase_gcp_cloud_sql_ip_type=psc", "psc"},
+ }
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?bytebase_gcp_cloud_sql_iam=true&bytebase_gcp_cloud_sql_instance_connection_name=project:region:instance"+tc.param)
+
+ authConfig, err := gcpConfigFromPGXConfig(pgxConfig)
+
+ require.NoError(t, err)
+ require.NotNil(t, authConfig)
+ require.Equal(t, tc.expect, authConfig.ipType)
+ require.NotContains(t, pgxConfig.RuntimeParams, gcpCloudSQLIPTypeParam)
+ })
+ }
+}
+
+func TestGCPConfigFromPGXConfigRejectsInvalidIPType(t *testing.T) {
+ pgxConfig := mustParsePGXConfig(t, "postgres://[email protected]:5432/bytebase?bytebase_gcp_cloud_sql_iam=true&bytebase_gcp_cloud_sql_instance_connection_name=project:region:instance&bytebase_gcp_cloud_sql_ip_type=bogus")
+
+ _, err := gcpConfigFromPGXConfig(pgxConfig)
+
+ require.ErrorContains(t, err, gcpCloudSQLIPTypeParam)
+}
+
+func TestGCPDialIPOptions(t *testing.T) {
+ tests := []struct {
+ name string
+ ipType string
+ wantLen int
+ }{
+ {"empty defaults to public", "", 0},
+ {"public", "public", 0},
+ {"private", "private", 1},
+ {"psc", "psc", 1},
+ }
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ require.Len(t, gcpDialIPOptions(tc.ipType), tc.wantLen)
+ })
+ }
+}
+
+func TestIsKeywordValueRuntimeParamIncludesIPType(t *testing.T) {
+ require.True(t, IsKeywordValueRuntimeParam(gcpCloudSQLIPTypeParam))
+}
diff --git a/docs/operations/high-availability.md b/docs/operations/high-availability.md
index 25c140d660..60714b53a5 100644
--- a/docs/operations/high-availability.md
+++ b/docs/operations/high-availability.md
@@ -44,6 +44,8 @@ [email protected] dbname=bytebase bytebase_gcp_cloud_sql_iam=true byte
The Cloud SQL IAM database user must exist and have the needed PostgreSQL privileges. The Google principal used by each Bytebase process must have permission to connect to the Cloud SQL instance, typically through ambient Application Default Credentials such as GKE Workload Identity. Do not put Google service account keys in `PG_URL`.
+By default the connector dials the instance's public IP. For a private-IP-only instance (the recommended production posture), add `bytebase_gcp_cloud_sql_ip_type=private` (or `psc` for Private Service Connect); `public` is the default. Bytebase must have a network path to the selected IP — for private IP, run it inside the same VPC (Private Service Access).
+
## How replica detection works
Bytebase tracks live replicas with heartbeats: