GCP Database Connections

​

Prerequisites: Service Account Setup

• GCE - VMs with attached service accounts
• GKE - Pods with Workload Identity

​

Create Service Account

1. Go to IAM & Admin → Service Accounts
2. Create service account named bytebase
3. Grant roles as needed:
   • Cloud SQL Client and Cloud SQL Instance User - for Cloud SQL
   • Cloud Spanner Database Admin - for Spanner
   • Secret Manager Secret Accessor - for Secret Manager
4. Note the email: bytebase@PROJECT_ID.iam.gserviceaccount.com

​

Attach Service Account

1. Create VM in Compute Engine
2. Set service account: bytebase@PROJECT_ID.iam.gserviceaccount.com
3. Set access scopes: “Allow full access to all Cloud APIs”

# Create Kubernetes service account
kubectl create serviceaccount bytebase-ksa

# Bind to Google service account
kubectl annotate serviceaccount bytebase-ksa \
  iam.gke.io/gcp-service-account=bytebase@PROJECT_ID.iam.gserviceaccount.com

# Allow impersonation
gcloud iam service-accounts add-iam-policy-binding bytebase@PROJECT_ID.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/bytebase-ksa]"

​

Alternative: Service Account Keys

1. Create a service account with required roles
2. Download the JSON key file
3. Set environment variable:
   -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
   

​

Cloud SQL with IAM Authentication

​

Step 1: Configure Cloud SQL Instance

1. In Cloud SQL, edit your instance
2. Add flag: cloudsql_iam_authentication = on
3. Save (SSL is enabled by default)

​

Step 2: Add Service Account User

gcloud sql users create bytebase@PROJECT_ID.iam.gserviceaccount.com \
  --instance=INSTANCE_NAME \
  --type=cloud_iam_service_account

​

Step 3: Connect from Bytebase

1. Click New Instance in Bytebase
2. Configure connection details:
   • Host: Your Cloud SQL connection name (PROJECT_ID:REGION:INSTANCE_ID)
     • Find this in Cloud SQL console → Instance details
   • Port: 3306 (MySQL) or 5432 (PostgreSQL)
   • Username:
     • MySQL: bytebase (service account name only)
     • PostgreSQL: bytebase@PROJECT_ID.iam (with project ID)
   • Authentication: Select Google Cloud SQL IAM
3. Click Test Connection then Create

​

Cloud Spanner

​

Step 1: Find the Project ID and Instance ID

​

Step 2: Connect from Bytebase

1. Go to Instances, click Connect instance, and choose Spanner.
2. Enter the Project ID and Instance ID.
3. Under Credential Source, choose how Bytebase signs in:
   • Leave Specific Credential off to use the credentials of the Bytebase server: the file that GOOGLE_APPLICATION_CREDENTIALS points to, or else the attached service account.
   • Turn on Specific Credential and paste the contents of the service account’s JSON key file, or drop the file onto the field. A Workload Identity Federation credential configuration file also works. Bytebase Cloud requires a specific credential.
4. Click Test Connection, then Create.

​

GCP Secret Manager

​

Step 1: Create Secret

1. Go to Secret Manager Console
2. Click Create Secret
3. Enter secret name (e.g., db-password) and your database password as value
4. Click Create and note the resource name: projects/PROJECT_ID/secrets/SECRET_NAME

​

Step 2: Configure in Bytebase

1. In your database instance settings, find the password field
2. Click the key icon to use external secret
3. Select GCP Secret Manager
4. Enter the secret resource name from Step 1
5. Test connection and save

​

Private IP and VPC Peering

​

Step 1: Configure VPC Peering

1. Enable Service Networking API
2. Reserve IP range for services:
   gcloud compute addresses create google-managed-services-default \
     --global \
     --purpose=VPC_PEERING \
     --prefix-length=16 \
     --network=default
   
3. Create private connection:
   gcloud services vpc-peerings connect \
     --service=servicenetworking.googleapis.com \
     --ranges=google-managed-services-default \
     --network=default
   

​

Step 2: Connect from Bytebase

1. Deploy Bytebase in the same VPC or a peered VPC
2. Use the private IP address for the Cloud SQL instance
3. Configure connection as normal with private IP

​

Database-Specific Configuration

• PostgreSQL, for Cloud SQL for PostgreSQL and AlloyDB
• MySQL, for Cloud SQL for MySQL

​

Best Practices

1. Use Service Accounts over Keys: Always prefer attached service accounts
2. Enable Private IP: Use VPC peering for enhanced security
3. Use Secret Manager: Centralize password management
4. Follow Least Privilege: Grant only necessary IAM roles
5. Enable Audit Logging: Monitor database access with Cloud Audit Logs

​

Troubleshooting

​

Connection Refused

• Verify Cloud SQL instance allows connections from your IP/network
• Check authorized networks configuration
• Ensure VPC peering is properly configured for private IP

​

IAM Authentication Failed

• Verify service account has Cloud SQL Instance User role
• Check database user was created with correct type
• Ensure cloudsql_iam_authentication flag is enabled

​

Secret Manager Access Denied

• Verify service account has Secret Manager Secret Accessor role
• Check secret resource name is correct
• Ensure secret exists in the correct project

​

Private IP Connection Issues

• Verify VPC peering is active
• Check firewall rules allow traffic
• Ensure Bytebase is deployed in the correct VPC