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.

AWS PrivateLink

If your private resources run in AWS, connect them with AWS PrivateLink instead of a GCP network attachment. You expose an internal service through a VPC endpoint service that allowlists Builder's AWS account, then Builder creates a matching interface endpoint to reach it. Traffic stays on the AWS and Google private backbones and never travels over the public internet.

How it works

You create a Network Load Balancer and a VPC endpoint service in your AWS account, and add Builder's AWS account to the endpoint service's allowlist. You paste the generated endpoint service name into Builder, along with the private hostnames and ports Fusion should reach. Builder provisions an interface VPC endpoint on its side and connects it to your service. Because the service requires acceptance, you approve that connection in AWS. Fusion then reaches your service privately through the endpoint.

PrivateLink exposes only the specific services you put behind the endpoint service, not your whole VPC. Each service you want Fusion to reach is one endpoint entry in Builder.

Prerequisites

Before you begin, ensure you have the following:

An AWS account with permission to create a Network Load Balancer and a VPC endpoint service, for example the AmazonVPCFullAccess policy or equivalent EC2 and Elastic Load Balancing permissions.
The internal service or services you want Fusion to reach, each addressable by a target the load balancer can forward to, such as instances, IP addresses, or an existing target group.
Your connection must be in the us-east-1 region. Builder's PrivateLink endpoints run there, so the endpoint service name you submit must be a us-east-1 service.

Step 1: create a Network Load Balancer

Create an internal Network Load Balancer in us-east-1, with a target group and listener for each port your service exposes. Point the target group at your internal service.

# Create an internal Network Load Balancer aws elbv2 create-load-balancer \ --name builder-privatelink-nlb \ --type network \ --scheme internal \ --subnets subnet-XXXX subnet-YYYY \ --region us-east-1 # Create a target group for your service port, then register your targets aws elbv2 create-target-group \ --name builder-svc-443 \ --protocol TCP --port 443 \ --vpc-id vpc-XXXX \ --target-type ip \ --region us-east-1

Step 2: create a VPC endpoint service

Create a VPC endpoint service in front of the load balancer, require acceptance, and add Builder's AWS account to the allowlist so only Builder can connect. Builder's AWS account principal is arn:aws:iam::597437435687:root.

AWS CLI

# Create the endpoint service in front of your NLB aws ec2 create-vpc-endpoint-service-configuration \ --network-load-balancer-arns <YOUR_NLB_ARN> \ --acceptance-required \ --region us-east-1 # Allowlist Builder's AWS account on the service aws ec2 modify-vpc-endpoint-service-permissions \ --service-id <YOUR_SERVICE_ID> \ --add-allowed-principals arn:aws:iam::597437435687:root \ --region us-east-1

AWS console

To create the endpoint service through the AWS Console:

Open VPC > Endpoint services > Create endpoint service.
Select your internal Network Load Balancer.
Enable Acceptance required.
Create the service, then open it and under Allow principals add arn:aws:iam::597437435687:root.
Copy the Service name. It looks like com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0.

Step 3: enter details into Builder

Open Private Cloud Connection in your Builder space settings. Set Connection type to AWS PrivateLink, then add an endpoint with:

Field	Value	Required?
Endpoint service name	The service name from Step 2. Must be a `us-east-1` service, for example `com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0`.	Yes
Hostnames	The private hostnames Fusion should resolve to this service, one per line or comma-separated. For example, `db.internal`.	Yes
Ports	The ports your service exposes, comma-separated. For example, `443, 8080`.	Yes

Add more endpoints for additional services, up to 10 per connection. Once you are done, click Save.

AWS PrivateLink connections do not use the Customer DNS servers field. Builder resolves the hostnames you list here directly to the matching endpoint.

Step 4: accept the connection and confirm

After you save, Builder creates an interface endpoint that connects to your endpoint service. Because the service requires acceptance, the connection starts as pending in your AWS account. Accept it to activate the link.

# Find the pending connection, then accept it aws ec2 describe-vpc-endpoint-connections \ --filters Name=service-id,Values=<YOUR_SERVICE_ID> \ --region us-east-1 aws ec2 accept-vpc-endpoint-connections \ --service-id <YOUR_SERVICE_ID> \ --vpc-endpoint-ids <VPCE_ID_FROM_ABOVE> \ --region us-east-1

Back in Builder, click Check status to review the configured endpoints. Once the connection is active, new Fusion environments route to your service automatically.

Endpoint status may show as unknown in Builder even when the link is healthy. Builder has no credentials to query your AWS account, so it reports what you configured rather than live AWS state. Confirm the connection is Available in your AWS console.

Firewall and security groups

PrivateLink traffic reaches your service through the load balancer. Confirm that your target group's security groups allow traffic from the load balancer on each service port, and that health checks pass. Only the ports you list on an endpoint are reachable.

Solve common issues

Save fails with a region or format error. The endpoint service name must be a us-east-1 service in the form com.amazonaws.vpce.us-east-1.vpce-svc-xxxxxxxxxxxxxxxxx.
The connection stays pending. Accept the endpoint connection in your AWS account, as described in Step 4. Builder cannot accept it for you.
Fusion cannot reach the service. Confirm the load balancer target group is healthy and its security groups allow the endpoint traffic on the listed ports.
Builder cannot connect after acceptance. Confirm you allowlisted arn:aws:iam::597437435687:root and that the hostnames and ports in Builder match the service.

Revoke access

To revoke access, remove arn:aws:iam::597437435687:root from your endpoint service's allowed principals, or delete the endpoint service. Remove the endpoint in Builder as well, and notify your Builder account team so the interface endpoint can be decommissioned.

What's next

Was this article helpful?