Skip to content

Commit 9f434db

Browse files
thomasgauvinthomasgauvin
committed
adjust examples to include s3 example, more context across examples
1 parent 2323909 commit 9f434db

File tree

6 files changed

+298
-108
lines changed

6 files changed

+298
-108
lines changed

‎src/content/docs/workers-vpc/api/index.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,12 @@ Makes an HTTP request to the private service through the configured tunnel.
2929
const response = await env.VPC_SERVICE_BINDING.fetch(resource, options);
3030
```
3131

32+
:::note
33+
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.
34+
35+
The information 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).
36+
:::
37+
3238
### Parameters
3339

3440
- `resource` (string | URL | Request) - The URL to fetch. This must be an absolute URL including protocol, host, and path (for example, `http://internal-api:8080/api/users`)
@@ -39,7 +45,7 @@ const response = await env.VPC_SERVICE_BINDING.fetch(resource, options);
3945
- `signal` - AbortSignal for request cancellation
4046

4147
:::note[Absolute URLs Required]
42-
VPC Service fetch requests must use absolute URLs including the protocol (http/https), host, and path. Relative paths are not supported.
48+
VPC Service fetch requests must use absolute URLs including the protocol (`http`/`https`), host, and path. Relative paths are not supported.
4349
:::
4450

4551
### Return value

‎src/content/docs/workers-vpc/configuration/tunnel/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ For platform-specific tunnel deployment instructions for production workloads:
5959

6060
Refer to the full Cloudflare Tunnel documentation on [how to setup Tunnels for high availability and failover with replicas](/cloudflare-one/connections/connect-networks/configure-tunnels/tunnel-availability/).
6161

62+
:::note
63+
We do not recommend using `cloudflared` in autoscaling setups because downscaling (removing replicas) will break existing user connections to that replica. Additionally, `cloudflared` does not load balance across replicas; replicas are strictly for high availability and requests are routed to the nearest replica.
64+
:::
65+
6266
## Next steps
6367

6468
- Configure [VPC Services](/workers-vpc/configuration/vpc-services/) to connect your tunnels to Workers

‎src/content/docs/workers-vpc/configuration/vpc-services.mdx‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,12 @@ A VPC Service consists of:
3535
- **Hostname or IPv4/IPv6 addresses**: The hostname, or IPv4 and/or IPv6 addresses to use to route to your service from the tunnel in your private network
3636
- **Ports**: HTTP and/or HTTPS port configuration (optional, defaults to 80/443)
3737

38+
:::note
39+
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.
40+
41+
The information 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).
42+
:::
43+
3844
## Configuration example
3945

4046
The following is an example of a VPC Service for a service using custom HTTP and HTTPS ports, and both IPv4 and IPv6 addresses. These configurations represent the expected contract of the [REST API for creating a VPC Service](https://developers.cloudflare.com/api/resources/zero_trust/subresources/connectivity/subresources/directory/subresources/services/), a type of service within the broader connectivity directory.
@@ -95,7 +101,7 @@ binding = "PRIVATE_API"
95101
service_id = "5634563546"
96102
remote = true
97103

98-
```
104+
````
99105
</WranglerConfig>
100106

101107
You can have multiple service bindings:
@@ -117,7 +123,7 @@ binding = "INTERNAL_CACHE"
117123
service_id = "3412345678"
118124
remote = true
119125

120-
```
126+
````
121127

122128
</WranglerConfig>
123129

‎src/content/docs/workers-vpc/examples/private-api.mdx‎

Lines changed: 40 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Access private API
2+
title: Access a private API or website
33
pcx_content_type: example
44
---
55

@@ -9,13 +9,29 @@ This example demonstrates how to access a private REST API that is not exposed t
99

1010
## Prerequisites
1111

12-
- A private API running in your VPC/virtual network
13-
- Cloudflare Tunnel configured and running (follow the [Get Started guide](/workers-vpc/get-started/) to set up)
12+
- A virtual machine/EC2 instance running in your VPC/virtual network
13+
- A private API or website running in your VPC/virtual network with security rules allowing access to the virtual machine that will be running `cloudflared`
1414
- Workers account with Workers VPC access
1515

16-
## 1. Create the VPC Service
16+
## 1. Set up Cloudflare Tunnel
1717

18-
First, create a service for your internal API:
18+
A Cloudflare Tunnel creates a secure connection from your private network to Cloudflare. This tunnel will allow Workers to securely access your private resources.
19+
20+
1. Navigate to the [Workers VPC dashboard](https://dash.cloudflare.com/?to=/:account/workers/vpc/tunnels) and select the **Tunnels** tab.
21+
22+
2. Select **Create** to create a new tunnel.
23+
24+
3. Enter a name for your tunnel (for example, `private-api-tunnel`) and select **Save tunnel**.
25+
26+
4. Choose your operating system and architecture. The dashboard will provide specific installation instructions for your environment.
27+
28+
5. Follow the provided commands to download and install `cloudflared` on your VM, and execute the service installation command with your unique token.
29+
30+
The dashboard will confirm when your tunnel is successfully connected. Note the tunnel ID for the next step.
31+
32+
## 2. Create the Workers VPC Service
33+
34+
First, create a Workers VPC Service for your internal API:
1935

2036
```bash
2137
npx wrangler vpc service create api-service \
@@ -25,9 +41,18 @@ npx wrangler vpc service create api-service \
2541
--http-port 8080
2642
```
2743

44+
You can also create a VPC Service for a service using its hostname:
45+
46+
```bash
47+
npx wrangler vpc service create api-service \
48+
--type http \
49+
--tunnel-id <YOUR_TUNNEL_ID> \
50+
--hostname internal-hostname.example.com
51+
```
52+
2853
Note the service ID returned for the next step.
2954

30-
## 2. Configure your Worker
55+
## 3. Configure your Worker
3156

3257
Update your `wrangler.toml`:
3358

@@ -41,81 +66,32 @@ compatibility_date = "2024-01-01"
4166
binding = "INTERNAL_API"
4267
service_id = "<YOUR_SERVICE_ID>"
4368

44-
[vars]
45-
API_VERSION = "v2"
46-
4769
````
4870
</WranglerConfig>
4971

50-
## 3. Implement the Worker
72+
## 4. Implement the Worker
5173

5274
In your Workers code, use the VPC Service binding in order to send requests to the service:
5375

5476
```js title="index.js"
5577
export default {
5678
async fetch(request, env, ctx) {
57-
// Parse the incoming request
58-
const url = new URL(request.url);
59-
60-
// Add authentication for internal API
61-
const headers = new Headers(request.headers);
62-
headers.set("X-Internal-Auth", env.INTERNAL_API_KEY);
63-
headers.set("X-Request-ID", crypto.randomUUID());
64-
65-
// Transform the path to internal API format
66-
const internalPath = `/api/${env.API_VERSION}${url.pathname}`;
67-
6879
try {
69-
// Forward request to internal API
70-
const response = await env.INTERNAL_API.fetch(
71-
`http://10.0.1.50:8080${internalPath}${url.search}`,
72-
{
73-
method: request.method,
74-
headers: headers,
75-
body: request.body,
76-
},
77-
);
78-
79-
// Add CORS headers for browser requests
80-
const responseHeaders = new Headers(response.headers);
81-
responseHeaders.set("Access-Control-Allow-Origin", "*");
82-
responseHeaders.set(
83-
"Access-Control-Allow-Methods",
84-
"GET, POST, PUT, DELETE, OPTIONS",
85-
);
86-
87-
// Return the response
88-
return new Response(response.body, {
89-
status: response.status,
90-
statusText: response.statusText,
91-
headers: responseHeaders,
92-
});
80+
// Fetch data from internal API and process it before returning
81+
const response = await env.INTERNAL_API.fetch("http://10.0.1.50:8080/api/data");
82+
83+
// Use the response of the private API to perform more logic in Workers, before returning the final response
84+
return response;
9385
} catch (error) {
94-
// Log error for debugging
95-
console.error("Failed to reach internal API:", error);
96-
97-
// Return user-friendly error
98-
return new Response(
99-
JSON.stringify({
100-
error: "Service temporarily unavailable",
101-
timestamp: new Date().toISOString(),
102-
}),
103-
{
104-
status: 503,
105-
headers: {
106-
"Content-Type": "application/json",
107-
"Retry-After": "30",
108-
},
109-
},
110-
);
86+
return new Response("Service unavailable", { status: 503 });
11187
}
11288
},
11389
};
11490
````
11591

11692
This guide demonstrates how you could create a simple proxy in your Workers. However, you could use VPC Services to fetch APIs directly and manipulate the responses to enable you to build more full-stack and backend functionality on Workers.
11793

118-
## 4. Deploy and test
94+
## 5. Deploy and test
11995

12096
Now, you can deploy and test your Worker that you have created:
12197

@@ -125,14 +101,7 @@ npx wrangler deploy
125101

126102
```bash
127103
# Test GET request
128-
curl https://private-api-gateway.workers.dev/users \
129-
-H "Authorization: Bearer your-token"
130-
131-
# Test POST request
132-
curl -X POST https://private-api-gateway.workers.dev/users \
133-
-H "Authorization: Bearer your-token" \
134-
-H "Content-Type: application/json" \
135-
-d '{"name": "John Doe", "email": "[email protected]"}'
104+
curl https://private-api-gateway.workers.dev
136105
```
137106

138107
## Next steps

‎src/content/docs/workers-vpc/examples/private-s3-bucket.mdx‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Access a private S3 bucket
3+
pcx_content_type: example
4+
---
5+
6+
import { Tabs, TabItem, WranglerConfig } from "~/components";
7+
8+
This example demonstrates how to access a private S3 bucket that is not exposed to the public internet. In this guide, we will configure a Workers VPC Service for an internal S3-compatible storage service, create a Worker that makes requests to that bucket, and deploy the Worker to validate our changes.
9+
10+
## Prerequisites
11+
12+
- A private S3-compatible storage service running in your VPC/virtual network (such as AWS S3 VPC endpoint, MinIO, or similar)
13+
- A virtual machine/EC2 instance running in the same VPC as your S3 VPC endpoint
14+
- Workers account with Workers VPC access
15+
16+
## 1. Set up Cloudflare Tunnel
17+
18+
A Cloudflare Tunnel creates a secure connection from your private network to Cloudflare. This tunnel will allow Workers to securely access your private resources.
19+
20+
1. Navigate to the [Workers VPC dashboard](https://dash.cloudflare.com/?to=/:account/workers/vpc/tunnels) and select the **Tunnels** tab.
21+
22+
2. Select **Create** to create a new tunnel.
23+
24+
3. Enter a name for your tunnel (for example, `s3-tunnel`) and select **Save tunnel**.
25+
26+
4. Choose your operating system and architecture. The dashboard will provide specific installation instructions for your environment.
27+
28+
5. Follow the provided commands to download and install `cloudflared` on your VM, and execute the service installation command with your unique token.
29+
30+
The dashboard will confirm when your tunnel is successfully connected. Note the tunnel ID for the next step.
31+
32+
## 2. Create the Workers VPC Service
33+
34+
First, create a Workers VPC Service for your internal S3 storage:
35+
36+
```bash
37+
npx wrangler vpc service create s3-storage \
38+
--type http \
39+
--tunnel-id <YOUR_TUNNEL_ID> \
40+
--hostname s3.us-west-2.amazonaws.com
41+
```
42+
43+
You can also create a Workers VPC Service using an IP address (for example, if using MinIO):
44+
45+
```bash
46+
npx wrangler vpc service create s3-storage \
47+
--type http \
48+
--tunnel-id <YOUR_TUNNEL_ID> \
49+
--ipv4 10.0.1.60 \
50+
--http-port 9000
51+
```
52+
53+
Note the service ID returned for the next step.
54+
55+
## 3. Configure S3 bucket policy
56+
57+
Configure your S3 bucket to allow anonymous access from your VPC endpoint. This works for unencrypted S3 objects:
58+
59+
```json
60+
{
61+
"Version": "2012-10-17",
62+
"Statement": [
63+
{
64+
"Sid": "AllowAnonymousAccessFromVPCE",
65+
"Effect": "Allow",
66+
"Principal": "*",
67+
"Action": ["s3:GetObject", "s3:ListBucket"],
68+
"Resource": [
69+
"arn:aws:s3:::your-bucket-name",
70+
"arn:aws:s3:::your-bucket-name/*"
71+
],
72+
"Condition": {
73+
"StringEquals": {
74+
"aws:sourceVpce": "vpce-your-endpoint-id"
75+
}
76+
}
77+
}
78+
]
79+
}
80+
```
81+
82+
### Testing S3 access directly
83+
84+
You can test S3 access directly from the VM where your Cloudflare Tunnel is running to verify the bucket policy is working correctly. These commands should work without any AWS credentials:
85+
86+
```bash
87+
# Test listing bucket contents
88+
curl -i https://s3.us-west-2.amazonaws.com/your-bucket-name/
89+
90+
# Test downloading a specific file
91+
curl -i https://your-bucket-name.s3.us-west-2.amazonaws.com/test-file.txt
92+
```
93+
94+
## 4. Configure your Worker
95+
96+
Update your `wrangler.toml`:
97+
98+
<WranglerConfig>
99+
```toml
100+
name = "private-s3-gateway"
101+
main = "src/index.js"
102+
compatibility_date = "2024-01-01"
103+
104+
[[vpc_services]]
105+
binding = "S3_STORAGE"
106+
service_id = "<YOUR_SERVICE_ID>"
107+
108+
````
109+
</WranglerConfig>
110+
111+
## 5. Implement the Worker
112+
113+
In your Workers code, use the Workers VPC Service binding in order to send requests to the service:
114+
115+
```js title="index.js"
116+
export default {
117+
async fetch(request, env, ctx) {
118+
try {
119+
// Fetch a file from the private S3 bucket via VPC endpoint
120+
const response = await env.S3_STORAGE.fetch("https://s3.us-west-2.amazonaws.com/my-bucket/data.json");
121+
122+
// Use the response from S3 to perform more logic in Workers, before returning the final response
123+
return response;
124+
} catch (error) {
125+
return new Response("Storage unavailable", { status: 503 });
126+
}
127+
},
128+
};
129+
````
130+
131+
This guide demonstrates how you could access private object storage from your Workers. You could use Workers VPC Services to fetch files directly and manipulate the responses to enable you to build more full-stack and backend functionality on Workers.
132+
133+
## 6. Deploy and test
134+
135+
Now, you can deploy and test your Worker that you have created:
136+
137+
```bash
138+
npx wrangler deploy
139+
```
140+
141+
```bash
142+
# Test GET request
143+
curl https://private-s3-gateway.workers.dev
144+
```
145+
146+
## Next steps
147+
148+
- Add [authentication and authorization](/workers/examples/auth-with-headers/)
149+
- Implement [rate limiting](/durable-objects/api/)
150+
- Set up [monitoring and alerting](/analytics/analytics-engine/)
151+
- Explore [other examples](/workers-vpc/examples/)

0 commit comments

Comments
 (0)