From ce91293390c3b90478b4115e5987364cc76d6a31 Mon Sep 17 00:00:00 2001 From: Ricardo Antunes Date: Wed, 25 Mar 2026 11:25:47 +0000 Subject: [PATCH] [Workers VPC] Add VPC Networks documentation --- src/content/docs/workers-vpc/api/index.mdx | 58 ++++----- .../configuration/vpc-networks/index.mdx | 120 ++++++++++++++++++ 2 files changed, 149 insertions(+), 29 deletions(-) create mode 100644 src/content/docs/workers-vpc/configuration/vpc-networks/index.mdx diff --git a/src/content/docs/workers-vpc/api/index.mdx b/src/content/docs/workers-vpc/api/index.mdx index b8bda299618b051..25b2a4c23d2c716 100644 --- a/src/content/docs/workers-vpc/api/index.mdx +++ b/src/content/docs/workers-vpc/api/index.mdx @@ -1,15 +1,14 @@ --- title: Workers Binding API pcx_content_type: reference +description: API reference for VPC Service and VPC Network bindings in Workers. sidebar: order: 4 --- import { Tabs, TabItem } from "~/components"; -VPC Service bindings provide a convenient API for accessing VPC Services from your Worker. Each binding represents a connection to a service in your private network through a Cloudflare Tunnel. - -Each request made on the binding will route to the specific service that was configured for the VPC Service, while restricting access to the rest of your private network. +VPC bindings provide a `fetch()` API for accessing private services from your Worker through Cloudflare Tunnel. Both [VPC Services](/workers-vpc/configuration/vpc-services/) and [VPC Networks](/workers-vpc/configuration/vpc-networks/) expose the same `fetch()` method — the difference is in routing scope. :::note @@ -17,41 +16,39 @@ Workers VPC is currently in beta. Features and APIs may change before general av ::: -## VPC Service binding +## Binding types -A VPC Service binding is accessed via the `env` parameter in your Worker's fetch handler. It provides a `fetch()` method for making HTTP requests to your private service. +### VPC Service -:::note[Required roles] -To bind a VPC Service in a Worker, your user needs `Connectivity Directory Bind` (or `Connectivity Directory Admin`). For role definitions, refer to [Roles](/fundamentals/manage-members/roles/#account-scoped-roles). -::: +A VPC Service binding routes requests to a specific pre-registered host and port. The host and port configured in the VPC Service always determine the connection target — the URL passed to `fetch()` does not control routing. The `Host` header and SNI value for HTTPS requests are derived from the URL provided to `fetch()`. + +### VPC Network + +A VPC Network binding grants access to any service reachable through the bound tunnel or [Cloudflare Mesh](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/). The URL passed to `fetch()` determines the actual destination — hostname or IP address and port. + +## Required roles + +To bind a VPC Service or VPC Network in a Worker, your user needs `Connectivity Directory Bind` (or `Connectivity Directory Admin`). For role definitions, refer to [Roles](/fundamentals/manage-members/roles/#account-scoped-roles). ## fetch() Makes an HTTP request to the private service through the configured tunnel. ```js -const response = await env.VPC_SERVICE_BINDING.fetch(resource, options); +const response = await env.MY_BINDING.fetch(resource, options); ``` -:::note -The [VPC Service configurations](/workers-vpc/configuration/vpc-services/#vpc-service-configuration) will always be used to connect and route requests to your services in external networks, even if a different URL or host is present in the actual `fetch()` operation of the Worker code. - -The host provided in the `fetch()` operation is not used to route requests, and instead only populates the `Host` field for a HTTP request that can be parsed by the server and used for Server Name Indication (SNI), when the `https` scheme is specified. - -The port provided in the `fetch()` operation is ignored — the port specified in the VPC Service configuration will be used. -::: - ### Parameters -- `resource` (string | URL | Request) - The URL to fetch. This must be an absolute URL including protocol, host, and path (for example, `http://internal-api/api/users`) -- `options` (optional RequestInit) - Standard fetch options including: - - `method` - HTTP method (GET, POST, PUT, DELETE, etc.) - - `headers` - Request headers - - `body` - Request body - - `signal` - AbortSignal for request cancellation +- `resource` (string | URL | Request) — The URL to fetch. Must be an absolute URL including protocol, host, and path (for example, `http://internal-api/api/users`). +- `options` (optional RequestInit) — Standard fetch options including: + - `method` — HTTP method (GET, POST, PUT, DELETE, etc.) + - `headers` — Request headers + - `body` — Request body + - `signal` — AbortSignal for request cancellation -:::note[Absolute URLs Required] -VPC Service fetch requests must use absolute URLs including the protocol (`http`/`https`), host, and path. Relative paths are not supported. +:::note[Absolute URLs required] +VPC binding fetch requests must use absolute URLs including the protocol (`http`/`https`), host, and path. Relative paths are not supported. ::: ### Return value @@ -60,6 +57,8 @@ Returns a `Promise` that resolves to a [standard Fetch API Response ob ### Examples +The following examples apply to both VPC Service and VPC Network bindings. + #### Basic GET request ```js @@ -68,7 +67,7 @@ export default { const privateRequest = new Request( "http://internal-api.company.local/users", ); - const response = await env.VPC_SERVICE_BINDING.fetch(privateRequest); + const response = await env.MY_BINDING.fetch(privateRequest); const users = await response.json(); return new Response(JSON.stringify(users), { @@ -98,7 +97,7 @@ export default { }, ); - const response = await env.VPC_SERVICE_BINDING.fetch(privateRequest); + const response = await env.MY_BINDING.fetch(privateRequest); if (!response.ok) { return new Response("Failed to create user", { status: response.status }); @@ -118,7 +117,7 @@ export default { export default { async fetch(request, env) { const privateRequest = new Request("https://10.0.1.50/api/data"); - const response = await env.VPC_SERVICE_BINDING.fetch(privateRequest); + const response = await env.MY_BINDING.fetch(privateRequest); return response; }, @@ -127,5 +126,6 @@ export default { ## Next steps -- Configure [service bindings in your Wrangler configuration file](/workers-vpc/configuration/vpc-services/) +- Configure [VPC Services](/workers-vpc/configuration/vpc-services/) +- Configure [VPC Networks](/workers-vpc/configuration/vpc-networks/) - Refer to [usage examples](/workers-vpc/examples/) diff --git a/src/content/docs/workers-vpc/configuration/vpc-networks/index.mdx b/src/content/docs/workers-vpc/configuration/vpc-networks/index.mdx new file mode 100644 index 000000000000000..c98d1355930bd20 --- /dev/null +++ b/src/content/docs/workers-vpc/configuration/vpc-networks/index.mdx @@ -0,0 +1,120 @@ +--- +title: VPC Networks +pcx_content_type: concept +sidebar: + order: 2 +--- + +import { WranglerConfig } from "~/components"; + +VPC Networks allow your Workers to access any service in your private network through a Cloudflare Tunnel without pre-registering individual hosts or ports. A single VPC Network binding grants tunnel-wide access to your private network. + +A VPC Network connects your Worker to an entire Cloudflare Tunnel. At runtime, your Worker can make requests to any service accessible through that tunnel using any hostname or IP address. This differs from VPC Services, which require you to create a separate service binding for each target host and port combination. + +:::note + +Workers VPC is currently in beta. Features and APIs may change before general availability. While in beta, Workers VPC is available for free to all Workers plans. + +::: + +## When to use VPC Networks + +Use VPC Networks when: + +- You need to access many services through the same tunnel +- Your internal hostnames or IP addresses change frequently +- You need tunnel-wide access without pre-registering individual services +- You want dynamic hostname or IP resolution + +Use VPC Services when: + +- You have a fixed set of known targets +- You want fine-grained per-service configuration +- You need explicit service cataloging and access control + +## Bind to a tunnel + +Reference a specific Cloudflare Tunnel directly by its UUID: + + +```jsonc +{ + "vpc_networks": [ + { + "binding": "MY_VPC", + "tunnel_id": "550e8400-e29b-41d4-a716-446655440000", + "remote": true + } + ] +} +``` + + +The `remote` flag must be set to `true` to enable remote bindings during local development. + +## Bind to Cloudflare Mesh + +[Cloudflare Mesh](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/) enables private networking between your services, devices, and Workers through Cloudflare's global network. When you bind a Worker to Cloudflare Mesh using `network_id: "cf1:network"`, your Worker can reach any private service accessible through your account's Mesh nodes and Cloudflare Tunnels — without specifying a particular tunnel UUID. + +Use Cloudflare Mesh when: + +- Your Workers need to reach private services across multiple tunnels or Mesh nodes +- You want to access your entire private network from a Worker without managing individual tunnel bindings +- Your private network topology may change (new tunnels, new nodes) and you do not want to update Worker configuration each time + +:::note + +Your account must have at least one active [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) or [Mesh node](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/warp-connector/) that can reach the target services. + +::: + +Bind to Cloudflare Mesh using `network_id: "cf1:network"`: + + +```jsonc +{ + "vpc_networks": [ + { + "binding": "MY_VPC", + "network_id": "cf1:network", + "remote": true + } + ] +} +``` + + +## Runtime usage + +Access any service in your network at runtime: + +```typescript +export default { + async fetch(request: Request, env: Env) { + // Access any hostname or IP in your network + const response = await env.MY_VPC.fetch("http://internal-api.local/data"); + + // Or access by IP address + const dbResponse = await env.MY_VPC.fetch("http://10.0.5.42:5432"); + + return response; + }, +}; +``` + +When a VPC Network cannot establish a connection to your target service, `fetch()` throws an exception. + +## VPC Networks vs VPC Services + +| Feature | VPC Networks | VPC Services | +| -------------------- | ---------------------------------------------------------------------- | ------------------------- | +| Scope | Tunnel-wide access | Specific host + port | +| Configuration | `tunnel_id` or `cf1:network` | `service_id` | +| Service registration | Not required | Required for each target | +| Use when | Dynamic discovery, tunnel-wide access, entire private network via Mesh | Fixed, cataloged services | + +## Next steps + +- Set up [Cloudflare Tunnel](/workers-vpc/configuration/tunnel/) +- View [examples](/workers-vpc/examples/) +- Learn about the [Network Binding API](/workers-vpc/api/)