Private Cloud Connection

Private Cloud Connection lets your Fusion environments securely reach resources inside your private network. This includes internal Git servers, package registries, staging databases, and internal APIs. Traffic does not travel over the public internet.

How it works

You create a network attachment in your VPC and allow Builder's GCP project to connect to it. Builder's proxy VM connects through that attachment and routes your Fusion environments' traffic into your network.

From your network's point of view, this traffic originates from a standard IP address inside your own subnet. Your existing firewall rules apply without modification. There is no VPC peering and no direct connection to Builder's infrastructure. The network attachment is the only link between the two networks. You control which projects can use it.

Vertical diagram showing how Private Cloud Connection works: Fusion environments send traffic down to Builder's proxy VM, which connects via Private Service Connect to a network attachment and subnet in your VPC, routing traffic to your internal resources. No VPC peering or direct connection to Builder's infrastructure.

Prerequisites

Before you begin, ensure you have access to the following:

The Google Cloud project that contains the VPC you want to connect.
The compute.networkAttachments.create IAM permission, included in roles/compute.networkAdmin or roles/editor.
A subnet in us-central1 within that VPC, or the ability to create one. The network attachment must be in us-central1 to match Builder's proxy region.

Establish your connection

Follow the steps below to establish a connection.

Step 1: create a subnet

If you do not already have a subnet in us-central1, create one. A /28 subnet provides 16 IP addresses. This range is sufficient because the network attachment only requires a small number of addresses to establish the proxy connection.

gcloud compute networks subnets create builder-attachment-subnet \ --project=YOUR_GCP_PROJECT_ID \ --network=YOUR_VPC_NAME \ --region=us-central1 \ --range=10.1.2.0/28

Step 2: create the network attachment

This step authorizes Builder's project to connect to your subnet. Builder's project ID is builder-3b0a2.

gcloud CLI

gcloud compute network-attachments create builder-connection \ --project=YOUR_GCP_PROJECT_ID \ --region=us-central1 \ --subnets=YOUR_SUBNET_NAME \ --connection-preference=ACCEPT_MANUAL \ --producer-accept-list=builder-3b0a2

GCP console

To create the network attachment through the GCP Console:

Open Network Attachments > Create in the GCP Console.
Enter a name such as builder-connection.
Set Region to us-central1. Select your VPC and subnet.
Under Connection preference, choose Accept connections for selected projects.
Add builder-3b0a2 as an accepted project.
Click Create.

Step 3: enter details into Builder

Open Private Cloud Connection in your Builder space settings and fill in:

FIeld	Value	Required?
GCP Project ID	The ID of the GCP project that contains your VPC and network attachment. For example, `my-company-prod`.	Yes
Network attachment name	The name of the network attachment you create in `us-central1`. For example, `builder-connection`.	Yes
Customer DNS servers	IP addresses of your internal DNS resolvers. one per line or comma-separated. Leave empty to use public DNS.	No

Once you are done, click Save.

Step 4: confirm the connection

Click Check status.

Builder verifies the attachment exists, confirms its project is accepted, and confirms the proxy VM is connected. After the status is confirmed as healthy, new Fusion environments route through the connection automatically.

If the check fails, confirm that builder-3b0a2 is on your attachment's accept list. Confirm that the project ID and attachment name match exactly.

DNS resolution

By default, Fusion resolves hostnames using public DNS. This is sufficient if your resources are public or if you connect to them by IP address. To resolve private hostnames, add your internal DNS resolver IP addresses in Customer DNS servers. An example of a private hostname is git.corp.example.com.

Builder forwards DNS queries to those resolvers through the network attachment. Confirm that your resolvers are reachable from the subnet created in Step 1. Confirm that your firewall allows DNS traffic on UDP and TCP port 53 from that subnet.

If your private hostnames use Google Cloud DNS private zones instead of a resolver IP address, leave this field blank. Contact your Builder account team, since private zones require additional setup.

Firewall considerations

Traffic from Fusion appears to originate from an IP address in your subnet. Confirm that your firewall allows that subnet to reach the required resources.

Resource	Port	Notes
Git server	TCP 443	HTTPS clones and API calls
Git server	TCP 22	SSH, if your team uses SSH URLs
Package registry	TCP 443	For installing dependencies
Internal APIs	TCP 443 or TCP 80	As required by your applications
DNS servers	UDP and TCP 53	Only if using custom DNS

Scope firewall rules to the subnet CIDR, not to a single IP address. For example, use 10.1.2.0/28. The proxy VM's IP address can change during maintenance.

Solve common issues

Check status fails immediately after saving. Confirm that builder-3b0a2 is accepted. Confirm that the project ID and attachment name match exactly.
Fusion cannot resolve an internal hostname. Confirm that your DNS resolver IP addresses are entered correctly. Confirm that they are reachable. Confirm that your firewall allows port 53 from your subnet.
The hostname resolves but the connection fails. This is usually caused by a firewall rule. Allow traffic from the subnet to the target resource on the required port.

Revoke access

To revoke access, remove builder-3b0a2 from your attachment's accepted projects. Notify your Builder account team so they can decommission the connection.

What's next

Was this article helpful?