Cloudflare Vpc Services

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

Cloudflare VPC Services Skill

What This Skill Does

• Diagnose dns_error and connectivity issues with VPC services
• Create VPC service configurations (IP-based and hostname-based)
• Configure wrangler.jsonc bindings for VPC services
• Write Worker code with service binding fetch() patterns
• Troubleshoot tunnel and routing problems

Auto-Trigger Keywords

Primary Keywords

• vpc service
• cloudflared tunnel
• service binding
• private api access
• workers vpc

Secondary Keywords

• tunnel configuration
• wrangler vpc_services
• internal api
• cross-cloud connectivity
• QUIC protocol

Error Pattern Keywords

• dns_error
• "requests leaving vpc"
• "connection timeout vpc"
• "port ignored"
• "tunnel not connecting"

Known Issues Prevention

When to Use

Use for:

• Setting up new VPC service connections
• Debugging dns_error or timeout issues
• Configuring wrangler for VPC bindings
• Writing Worker code that accesses private APIs
• Troubleshooting tunnel connectivity

Don't use for:

• General Cloudflare Workers development (use cloudflare-workers-expert)
• Public API integrations
• Cloudflare Access/Zero Trust setup (different use case)

Quick Usage

// Worker code with VPC service binding
export default {
  async fetch(request, env) {
    const response = await env.PRIVATE_API.fetch(
      "https://internal-api.vpc.local/users"
    );
    return response;
  }
};

Token Efficiency

File Structure

cloudflare-vpc-services/
├── SKILL.md           # Main instructions and patterns
├── README.md          # This file (discovery/metadata)
├── templates/
│   ├── wrangler-vpc.jsonc         # Ready-to-use wrangler config
│   ├── vpc-service-ip.json        # IP-based service payload
│   └── vpc-service-hostname.json  # Hostname-based service payload
├── scripts/
│   └── list-vpc-services.sh       # List services via API
└── references/
    └── api-patterns.md            # Comprehensive fetch() examples

Dependencies

Related Skills

• cloudflare-workers-expert - General Workers development
• cloudflare-workflows-expert - Durable execution workflows

VPC Service API Patterns

Comprehensive fetch() patterns for Workers VPC service bindings.

Service Binding API

const response = await env.VPC_SERVICE_BINDING.fetch(resource, options);

Parameters

• resource (string | URL | Request): Absolute URL with protocol, host, path
• options (optional RequestInit): Standard fetch options

Important Routing Behavior

The VPC Service configuration determines actual connectivity—not the fetch() URL:

• Host in fetch() → HTTP "Host" header and SNI value only
• Port in fetch() → IGNORED (uses configured service port)
• Actual connection → Service's configured hostname/IP and port

Basic Patterns

GET Request

export default {
  async fetch(request, env) {
    const response = await env.VPC_SERVICE.fetch(
      "https://internal-api.company.local/users"
    );
    const users = await response.json();
    return new Response(JSON.stringify(users), {
      headers: { "Content-Type": "application/json" }
    });
  }
};

POST with JSON Body

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

PUT/PATCH Updates

const response = await env.VPC_SERVICE.fetch(
  `https://internal-api.company.local/users/${userId}`,
  {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ status: "active" })
  }
);

DELETE Request

const response = await env.VPC_SERVICE.fetch(
  `https://internal-api.company.local/users/${userId}`,
  { method: "DELETE" }
);

Advanced Patterns

HTTPS with IP Address

// When service is configured with IP, use any hostname in URL
// The Host header will be set from the URL
const response = await env.VPC_SERVICE.fetch("https://10.0.1.50/api/data");

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}${url.search}`
      );
    } else if (url.pathname.startsWith('/api/orders')) {
      return env.ORDER_SERVICE.fetch(
        `https://orders-api.internal${url.pathname}${url.search}`
      );
    }

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

Request Forwarding with Headers

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

    // Forward the request with original headers
    const response = await env.VPC_SERVICE.fetch(
      `https://internal-api.local${url.pathname}`,
      {
        method: request.method,
        headers: request.headers,
        body: request.body
      }
    );

    return response;
  }
};

Error Handling

export default {
  async fetch(request, env) {
    try {
      const response = await env.VPC_SERVICE.fetch(
        "https://internal-api.local/data"
      );

      if (!response.ok) {
        return new Response(`Internal API error: ${response.status}`, {
          status: 502
        });
      }

      return response;
    } catch (error) {
      // Handle tunnel/connectivity errors
      return new Response(`VPC connection failed: ${error.message}`, {
        status: 503
      });
    }
  }
};

Timeout with AbortController

export default {
  async fetch(request, env) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 5000);

    try {
      const response = await env.VPC_SERVICE.fetch(
        "https://internal-api.local/slow-endpoint",
        { signal: controller.signal }
      );
      clearTimeout(timeoutId);
      return response;
    } catch (error) {
      if (error.name === 'AbortError') {
        return new Response('Request timeout', { status: 504 });
      }
      throw error;
    }
  }
};

Multiple Services

export default {
  async fetch(request, env) {
    // Call multiple internal services
    const [users, orders] = await Promise.all([
      env.USER_SERVICE.fetch("https://user-api.internal/users"),
      env.ORDER_SERVICE.fetch("https://orders-api.internal/orders")
    ]);

    const userData = await users.json();
    const orderData = await orders.json();

    return new Response(JSON.stringify({
      users: userData,
      orders: orderData
    }), {
      headers: { "Content-Type": "application/json" }
    });
  }
};

TypeScript Types

interface Env {
  VPC_SERVICE: Fetcher;
  USER_SERVICE: Fetcher;
  ORDER_SERVICE: Fetcher;
  API_TOKEN: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.VPC_SERVICE.fetch(
      "https://internal-api.local/data"
    );
    return response;
  }
};

References

Deep-dive documentation and patterns for Cloudflare VPC Services.

Contents

api-patterns.md

Comprehensive fetch() patterns for VPC service bindings including:

• Basic CRUD operations
• Advanced patterns (API gateway, request forwarding)
• Error handling
• TypeScript types
• Multiple service coordination

Official Documentation

• Workers VPC Documentation
• Workers VPC LLM Reference

Scripts

Utility scripts for working with Cloudflare VPC Services.

Prerequisites

• wrangler installed: npm install -g wrangler
• logged in: npx wrangler login

list-vpc-services.sh

Lists all VPC services in your Cloudflare account using wrangler vpc service list.

chmod +x list-vpc-services.sh
./list-vpc-services.sh

tail-worker.sh

Tail logs from a deployed Worker to debug VPC connections.

./tail-worker.sh my-worker
./tail-worker.sh my-worker --errors-only

Useful for debugging dns_error, timeouts, and routing issues.

set-api-token.sh

Set a secret for authenticating with private services.

./set-api-token.sh my-worker API_TOKEN
./set-api-token.sh my-worker PRIVATE_API_KEY

The secret will be available as env.API_TOKEN in your Worker code.