cloudflare-vpc-services（Cloudflare VPC 服务）

Cloudflare VPC Services

Enable Workers to securely access private APIs and services through encrypted tunnels without public internet exposure.

⚠️ BEFORE YOU START

This skill prevents 5 common errors and saves ~60% tokens.

Known Issues This Skill Prevents

1. dns_error from outdated cloudflared version or wrong protocol
2. Requests leaving VPC due to using public hostnames instead of internal
3. Port mismatch - fetch() port is ignored, service config port is used
4. Missing absolute URLs in fetch() calls
5. Incorrect tunnel ID or service binding configuration

Quick Start

Step 1: Verify Tunnel Requirements

# Check cloudflared version on remote infrastructure (K8s, EC2, etc.)
# Must be 2025.7.0 or later
cloudflared --version

# Verify QUIC protocol is configured (not http2)
# Check tunnel config or Cloudflare dashboard

Why this matters: Workers VPC requires cloudflared 2025.7.0+ with QUIC protocol. Older versions or http2 protocol cause dns_error.

Step 2: Create VPC Service

# Use Cloudflare API or dashboard to create VPC service
# See templates/vpc-service-ip.json or templates/vpc-service-hostname.json

Why this matters: The VPC service defines the actual target (IP/hostname) that the tunnel routes to. The fetch() URL only sets Host header and SNI.

Step 3: Configure Wrangler Binding

// wrangler.jsonc
{
  "vpc_services": [
    {
      "binding": "PRIVATE_API",
      "service_id": "<YOUR_SERVICE_ID>",
      "remote": true
    }
  ]
}

Why this matters: The binding name becomes the environment variable used in Worker code: env.PRIVATE_API.fetch().

Critical Rules

✅ Always Do

• ✅ Use absolute URLs with protocol, host, and path in fetch()
• ✅ Use internal VPC hostnames, not public endpoints
• ✅ Ensure cloudflared is 2025.7.0+ with QUIC protocol
• ✅ Allow UDP port 7844 outbound for QUIC connections

❌ Never Do

• ❌ Use port numbers in fetch() URL (they're ignored)
• ❌ Use public hostnames for services inside VPC
• ❌ Assume http2 protocol works (only QUIC is supported)
• ❌ Use relative URLs in fetch()

Common Mistakes

❌ Wrong:

// Port is ignored, relative URL fails
const response = await env.VPC_SERVICE.fetch("/api/users:8080");

✅ Correct:

// Absolute URL, port configured in VPC service
const response = await env.VPC_SERVICE.fetch("https://internal-api.company.local/api/users");

Why: The VPC service configuration determines actual routing. The fetch() URL only populates the Host header and SNI value.

Known Issues Prevention

Configuration Reference

wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-01-01",
  "vpc_services": [
    {
      "binding": "PRIVATE_API",
      "service_id": "daf43e8c-a81a-4242-9912-4a2ebe4fdd79",
      "remote": true
    },
    {
      "binding": "PRIVATE_DATABASE",
      "service_id": "453b6067-1327-420d-89b3-2b6ad16e6551",
      "remote": true
    }
  ]
}

Key settings:

• binding: Environment variable name for accessing the service
• service_id: UUID from VPC service creation
• remote: Must be true for VPC services

Common Patterns

Basic GET Request

export default {
  async fetch(request, env) {
    const response = await env.PRIVATE_API.fetch(
      "https://internal-api.company.local/users"
    );
    return response;
  }
};

POST with Authentication

const response = await env.PRIVATE_API.fetch(
  "https://internal-api.company.local/users",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${env.API_TOKEN}`
    },
    body: JSON.stringify({ name: "John", email: "john@example.com" })
  }
);

API Gateway with Path Routing

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    if (url.pathname.startsWith('/api/users')) {
      return env.USER_SERVICE.fetch(
        `https://user-api.internal${url.pathname}`
      );
    } else if (url.pathname.startsWith('/api/orders')) {
      return env.ORDER_SERVICE.fetch(
        `https://orders-api.internal${url.pathname}`
      );
    }

    return new Response('Not Found', { status: 404 });
  }
};

Bundled Resources

Templates

Located in templates/:

• wrangler-vpc.jsonc - Ready-to-use wrangler config with VPC bindings
• vpc-service-ip.json - IP-based VPC service API payload
• vpc-service-hostname.json - Hostname-based VPC service API payload

Copy these templates as starting points for your implementation.

Scripts

Located in scripts/:

• list-vpc-services.sh - List VPC services via Cloudflare API
• tail-worker.sh - Debug VPC connections with live logs
• set-api-token.sh - Set secrets for private API auth

References

Located in references/:

• api-patterns.md - Comprehensive fetch() patterns and examples

Dependencies

Required

Optional

Official Documentation

• Workers VPC Documentation
• Cloudflare Tunnel Setup

Troubleshooting

dns_error when calling VPC service

Symptoms: Worker returns dns_error when calling env.VPC_SERVICE.fetch()

Solution:

1. Update cloudflared to 2025.7.0+ on remote infrastructure
2. Configure QUIC protocol (not http2)
3. Allow UDP port 7844 outbound

Requests going to public internet

Symptoms: Logs show requests hitting public endpoints instead of internal

Solution:

// Use internal hostname
const response = await env.VPC_SERVICE.fetch(
  "https://internal-api.vpc.local/endpoint"  // Internal
  // NOT "https://api.company.com/endpoint"   // Public
);

Connection timeout

Symptoms: Requests hang and eventually timeout

Solution:

1. Verify tunnel is running: check cloudflared logs
2. Verify tunnel_id matches in VPC service config
3. Check network connectivity from tunnel to target

Setup Checklist

Before using this skill, verify:

• cloudflared 2025.7.0+ deployed on remote infrastructure
• QUIC protocol configured (not http2)
• UDP port 7844 outbound allowed
• VPC service created with correct tunnel_id
• wrangler.jsonc has vpc_services binding
• Using internal hostnames (not public endpoints)
• Using absolute URLs in fetch() calls