Cloud SQL for Postgres

Runway supports provisioning and connecting to managed Cloud SQL for Postgres instances from your GKE workloads. Unlike unmanaged instances, Runway owns the lifecycle of the database — you do not need to enable PSC or obtain PSC details.

File an MR to add your database to config/runtimes/gke/cloud-sql/managed.yml in the Runway provisioner:

- name: my-service-db
  provider: GCP
  db_version: "POSTGRES_18"
  region: us-east1
  zone: us-east1-b
  env_configuration:
    staging:
      instance_type: 2xsmall
      disk_size_gb: 10
      backup_configuration:
        transaction_log_retention_days: 2
        retained_backups_count: 3
    production:
      instance_type: xsmall
      disk_size_gb: 10
      backup_configuration:
        transaction_log_retention_days: 7
        retained_backups_count: 7
  labels:
    owner_email_handle: my-team
    department: eng-infra
    department_group: eng-infra-my-group
    product_category: my-category

The name you choose here is your database name and is referenced in the steps below.

The application credentials (username and password) created for the app should be stored in Vault by the app owner and exposed to the workload as environment variables via workloadSecrets in gke-service.yaml — choose whatever variable names make sense for your application. See secrets management for details.

In config/runtimes/gke/workloads.yml, add a postgres_instances key to your workload entry with the database name from the previous step:

your-service-gke:
  postgres_instances:
    - my-service-db

This grants the GKE workload’s service account the IAM permissions required to connect to Cloud SQL.

Add cloudsql_instances to your gke-service.yaml. For managed instances, the project is always gitlab-runway-<env> (for example, gitlab-runway-staging or gitlab-runway-production), the region is whatever region you specified in managed.yml, and the instance name is your database name:

apiVersion: runway/v1
kind: RunwayKubernetesDeployment

your-service-gke:
  serviceMixins:
    - "runway-gke.service-mixin"

  cloudsql_instances:
    - instance_connection_name: gitlab-runway-<env>:<region>:<name>

For example:

cloudsql_instances:
  - instance_connection_name: gitlab-runway-staging:us-east1:my-service-db

Connecting to a managed Cloud SQL instance works the same as for unmanaged instances. The Cloud SQL Auth Proxy exposes databases on localhost with sequential ports starting at 5432:

Connect using:

• Host: 127.0.0.1
• Port: 5432 (first instance), 5433 (second), etc.
• Username and password via environment variables (see secrets management)