Private Service Connect Consumer

Runway can connect your GKE workloads to external services that publish a Google Cloud Private Service Connect (PSC) service attachment — for example a Yugabyte Aeon cluster, or another GitLab-internal service running in a different project. Unlike unmanaged Cloud SQL, which has a purpose-built path, this is the generic mechanism for reaching any PSC producer from the Runway VPC.

Each connection creates a private endpoint inside the Runway VPC and a private DNS name your workload can resolve, so traffic stays on Google’s network and never traverses the public internet.

How it works

For every environment and region you declare, the provisioner creates — in the corresponding gitlab-runway-<env> project and GKE VPC:

• A PSC consumer endpoint named psc-<name>-<env>-<region> (where <env> is stg or prd): an internal IP address and forwarding rule in the GKE subnet that targets the producer’s service attachment.
• A private DNS zone named <name>-gke-<region> for <region>.runway-psc.goog., visible only inside the GKE VPC.
• An A record <name>.<region>.runway-psc.goog. pointing at the endpoint’s internal IP.

Your workload then reaches the service at:

<name>.<region>.runway-psc.goog

Allow-list the Runway project

PSC requires the producer to explicitly allow your consumer project before a connection can be established. Before adding any configuration, make sure the relevant Runway project is allow-listed on the producer for each environment you plan to use:

Environment	Consumer project
staging	gitlab-runway-staging
production	gitlab-runway-production

For a Yugabyte Aeon cluster, add these projects to the cluster’s PSC allow-list in the Yugabyte console. From the producer you also need the service attachment link for each region, which has the form:

projects/<producer-project>/regions/<region>/serviceAttachments/<attachment>

Allow-listing is per consumer project

staging and production are separate GCP projects, so each needs its own entry on the producer’s allow-list. A connection whose consumer project is not allow-listed will be created but stay in a PENDING state and never carry traffic.

Request a PSC connection

File an MR adding an entry to config/runtimes/gke/psc-connections.yml in the Runway provisioner:

config/runtimes/gke/psc-connections.yml

- name: iam-yugabyte
  labels:
    gl_service: iam
    gl_owner_email_handle: iam-team
    gl_dept: eng-infra
    gl_dept_group: eng-infra-platforms
  staging:
    us-east1:
      attachment_link: projects/yugabyte-cloud-prod/regions/us-east1/serviceAttachments/psc-l4t2iamwxfcvvkhiwwqk4rw3cq
  production:
    us-east1:
      attachment_link: projects/yugabyte-cloud-prod/regions/us-east1/serviceAttachments/psc-upjdrxa5bfaulbwqasxlvgy36m

The configuration is validated against schemas/runtimes/gke/psc-connections.schema.json.

Field	Required	Description
name	yes	Identifier for the connection. Becomes the DNS label, so workloads connect to <name>.<region>.runway-psc.goog. Lowercase letters, digits, and hyphens; max 30 characters (it is embedded in GCP resource names capped at 63).
labels	yes	Infrastructure labels for cost attribution, applied to the endpoint’s address and forwarding rule. gl_service is required; gl_owner_email_handle, gl_dept, gl_dept_group, and gl_product_category are optional.
staging / production	one of	A map keyed by GCP region; each region holds the producer’s attachment_link for that environment. At least one environment must be set.

One endpoint per region

The same name declared in multiple regions produces a distinct endpoint and A record per region (<name>.<region>.runway-psc.goog), so there is no collision. A given region can hold only one attachment link per environment.

Connect from your workload

The PSC endpoint forwards all ports to the service attachment, so the producer’s native protocol is available on the private DNS name at whatever port the producer exposes. Point your application at the DNS name and the producer’s port — for a Yugabyte Aeon YSQL endpoint:

• Host: <name>.<region>.runway-psc.goog (for example, iam-yugabyte.us-east1.runway-psc.goog)
• Port: 5433 (Yugabyte YSQL)

Store the producer credentials in Vault and expose them 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.

TLS hostname verification

Workloads connect through the Runway-owned *.runway-psc.goog name, not the producer’s own hostname. A TLS client that verifies the server hostname against the certificate — for Postgres-protocol clients, sslmode=verify-full — will fail, because the producer’s certificate is issued for its own domain. Use sslmode=verify-ca (verifies the CA chain but not the hostname) or configure your client’s trust settings accordingly.

Troubleshooting

Connection times out or is refused

1. Confirm the Runway consumer project for that environment (gitlab-runway-staging or gitlab-runway-production) is allow-listed on the producer.
2. Check the endpoint’s PSC connection status:

   gcloud compute forwarding-rules describe psc-<name>-<env>-<region> \
       --project gitlab-runway-<full-env> \
       --region <region> \
       --format='value(pscConnectionStatus)'

   It should read ACCEPTED. A PENDING or REJECTED status means the producer-side allow-list is missing or incomplete.
3. From a pod in the cluster, verify that <name>.<region>.runway-psc.goog resolves to an internal (RFC 1918) address.

TLS or certificate errors

See the caution above: connect with sslmode=verify-ca, or adjust your client’s certificate verification so it does not require the hostname to match the producer’s certificate.