Skip to main content

Private Network Access Best Practices

A common networking requirement for enterprise applications on CloudBase: services (cloud functions, Cloud Run) need to access resources inside the company's own VPC — internal databases, internal services, or an IDC connected via Direct Connect — and it is usually multiple services accessing the same internal network. This guide covers the recommended approach, focusing on one frequent question: can the shared part of the network configuration be done once, instead of configuring every service by hand?

Core Concept: the Three-Layer Model​

Private network access actually consists of three layers with different configuration granularity. Once you separate them, it becomes clear which parts only need to be done once:

LayerWhat it doesGranularityHow many times
Network connectionConnect the CloudBase-side VPC with your business VPC (peering / CCN)Per VPCOnce. Adding a new VPC later is just an extra association
Cloud Run service bindingEnable "Private Network" in service settings and select the VPC/subnetPer serviceOnce per service, at creation time or afterwards
Cloud function bindingEach function's VpcConfig specifies vpcId/subnetIdPer functionPer function at the platform level, but you can declare once in a config file and push in batch (see below)

Step 1: Plan the CIDRs (the Easiest Place to Get Rework)​

Before connecting anything, confirm that the CloudBase-side VPC and the business VPC have non-overlapping CIDR ranges. CIDR conflicts are the most common cause of failed private network integration, and fixing them later is costly — changing the network configuration of a live service triggers a service update, and re-planning CIDRs means redoing the entire connection chain.

Reference plan: CloudBase side 192.168.0.0/16, business side 172.16.0.0/16.

List existing VPCs and subnets under your account:

tcb api vpc DescribeVpcs --api-version 2017-03-12 --body '{"Limit":"20"}' --json
tcb api vpc DescribeSubnets --api-version 2017-03-12 --body '{"Limit":"20"}' --json

Step 2: Connect the Networks (One-Time Work)​

MethodApplicable when
PeeringThe two VPCs' CIDR ranges do not overlap at all
Cloud Connect Network (CCN)Cross-region connectivity is needed (the official guide covers the single-account scenario), or primary CIDRs overlap but subnets do not

Using CCN as the example:

  1. Create a CCN instance in the CCN console. The default free bandwidth is only enough for connectivity testing; purchase bandwidth per region pair for production
  2. Associate the VPCs: associate both the CloudBase-side VPC and the business VPC with the CCN instance, then confirm in the instance's route table that both routes are "Enabled"
  3. Open the security group: allow the CloudBase-side VPC CIDR on the relevant ports in the business VPC's security group

Adding another business VPC later only requires repeating step 2 — routes are maintained automatically. This layer is inherently "configure once". For the complete cross-region walkthrough, see Cross-Region VPC Connectivity via CCN.

Step 3: Bind Services — Two Paths by Service Form​

Cloud Run: Enable Private Network in Service Settings​

A Cloud Run service's private network is configured per service. It can be specified at creation time, or adjusted afterwards: open the service detail page, go to "Service Settings", enable or edit "Private Network" in the network configuration, select the VPC and subnet, and save. Note: changing the private network configuration triggers a service update — do it during off-peak hours and avoid frequent switching. See Cloud Run VPC Configuration.

Also, enabling a private network does not automatically provide public internet egress — if the service needs both internal and public access, make sure a NAT gateway exists in the VPC.

Cloud Functions: Declare Once in a Config File, Push in Batch​

Cloud function VPC binding is per function, but you do not need to configure each one by hand. Declare it once in functionDefaultConfig in cloudbaserc.json and every function inherits it; when an individual function needs a different network, override it in that function's entry:

{
  "$schema": "https://static.cloudbase.net/cli/cloudbaserc.schema.json",
  "version": "2.0",
  "envId": "your-env-id",
  "functionRoot": "./functions",
  "functionDefaultConfig": {
    "vpc": { "vpcId": "vpc-xxxx", "subnetId": "subnet-xxxx" }
  },
  "functions": [
    { "name": "svc-a" },
    { "name": "svc-b" },
    { "name": "svc-c", "vpc": { "vpcId": "vpc-yyyy", "subnetId": "subnet-yyyy" } }
  ]
}

Push to all functions, or just one:

tcb config update fn --all
tcb config update fn svc-a

The configuration in functionDefaultConfig is merged into every function, and a function's own settings take precedence (in the example above, svc-c uses its own VPC).

Three important behaviors:

  • Incremental updates: tcb config update fn only updates the declared configuration items; it does not wipe existing environment variables or other settings on the function

  • Verifying it took effect: the Network configuration line in tcb fn detail <funcName> -e <envId> shows the bound VPC and subnet (with names and CIDRs); it shows None when unbound. You can also verify with the native SCF API:

    tcb api scf GetFunction --api-version 2018-04-16 \
      --body '{"FunctionName":"<funcName>","Namespace":"<envId>"}' --json

    Note that Namespace is the environment ID

  • Unbinding goes through the API: passing an empty value to the CLI's --vpc flag does not clear the configuration. To unbind a function's VPC, call the SCF API with an empty VpcConfig:

    tcb api scf UpdateFunctionConfiguration --api-version 2018-04-16 \
      --body '{"FunctionName":"<funcName>","Namespace":"<envId>","VpcConfig":{"VpcId":"","SubnetId":""}}'

The Reverse Direction: Accessing CloudBase from Your Internal Network​

If the requirement is the other way around — an internal network reaching the CloudBase gateway without touching the public internet — use Tencent Cloud Private Link: the service provider publishes an "endpoint service", and you create an "endpoint" in your own VPC associated with it. The channel is established at the VPC level — build it once and every service in the internal network shares it, with no per-service configuration.

Verification and Troubleshooting​

After connecting, make a real call to the business service from inside a function using its internal address. If it fails, check in this order:

  1. Are both routes "Enabled" in the CCN route table? (CIDR conflicts disable routes)
  2. Does the business VPC's security group allow the CloudBase-side VPC CIDR on the target port?
  3. Is the function bound to the correct VPC? (check the Network configuration line in tcb fn detail)
  4. Is the business backend actually listening on the target port?
  5. Check the function logs to distinguish connection timeouts (routing/security group issues) from connection refused (port not listening)

Do's and Don'ts​

✓ Do✗ Don't
Plan CIDRs before connecting and keep ranges non-overlappingCreate VPCs with default CIDRs and rebuild after conflicts
Declare function VPC once via functionDefaultConfig and push in batchConfigure functions one by one and miss new ones
Verify every function's binding with tcb fn detailPush without verifying and start troubleshooting from scratch later
Decide the Cloud Run private network at service creation timeFrequently switch a live service's private network (every change triggers a service update)
Add new business VPCs by associating them with the existing CCNBuild a new connection chain for every addition

FAQ​

Multiple services access the same internal network — how many times do I configure?

Connect the network once; for Cloud Run, select the same VPC per service in service settings (doing it at creation avoids later service updates); for cloud functions, declare once in cloudbaserc.json then push with tcb config update fn --all — new functions inherit by being added to the config file. In no case do you re-connect the network.

What if the CIDRs overlap?

Peering cannot be established; if only the primary CIDRs overlap but subnets do not, use CCN instead (its restrictions can be narrowed to the subnet level). If subnets also conflict, one side's CIDR must be re-planned.

How do I quickly check whether a function is bound to a VPC?

tcb fn detail <funcName> -e <envId> — the Network configuration line shows the VPC/subnet IDs, names, and CIDRs when bound, or None when unbound.

The function lost public internet access after binding a VPC?

Inside a VPC, the public egress path differs from the default environment. To access both internal and public networks, configure a NAT gateway / public access for the VPC, or deploy public-only functions separately from internal-network functions.