💡 Key Concept: URL Maps are the traffic routing engine of GCP load balancers. They define how requests are routed to different backend services based on URL paths, host headers, HTTP methods, and other request attributes. Think of them as the "brain" that decides where each request should go.
🏗️ URL Map Architecture
graph TB
Client[Client Request example.com/api/users] --> FR[Forwarding Rule]
FR --> TP[Target Proxy]
TP --> UM[URL Map Traffic Router]
UM --> DR{Default Rule}
UM --> PR1{Path Rule 1 /api/*}
UM --> PR2{Path Rule 2 /static/*}
UM --> HR{Host Rule api.example.com}
DR --> BS1[Backend Service Web Servers]
PR1 --> BS2[Backend Service API Servers]
PR2 --> BS3[Backend Service CDN/Static]
HR --> BS4[Backend Service API Gateway]
BS1 --> WEB[Web Instances]
BS2 --> API[API Instances]
BS3 --> CDN[Static Content]
BS4 --> GW[Gateway Instances]
classDef urlMapComponent fill:#ea4335,stroke:#333,stroke-width:2px,color:#fff
classDef backendComponent fill:#34a853,stroke:#333,stroke-width:2px,color:#fff
classDef ruleComponent fill:#fbbc04,stroke:#333,stroke-width:2px,color:#333
class UM urlMapComponent
class BS1,BS2,BS3,BS4 backendComponent
class DR,PR1,PR2,HR ruleComponent
🎯 URL Map Components
Component
Purpose
Example
Priority
Default Service
Catches all unmatched requests
Fallback to main website
Lowest (always last)
Host Rules
Route based on hostname/domain
api.example.com → API backend
Highest
Path Matchers
Define routing rules for paths
/api/* → API service
Medium
Path Rules
Specific path routing within matcher
/api/v1/* vs /api/v2/*
Medium
Route Rules
Advanced routing with conditions
Header-based routing
High
🚀 Basic URL Map Creation
Simple URL Map (Default Service Only)
# Create basic URL map with default service
gcloud compute url-maps create basic-url-map \
--default-service=web-backend-service \
--global
# Describe the URL map
gcloud compute url-maps describe basic-url-map --global
📝 Parameters:
--default-service: Backend service that handles all unmatched requests
--global: Creates global URL map (vs --region for regional)
Basic use case: Single application with no path-based routing needed
--hosts: Comma-separated list of hostnames/domains
--path-matcher: References a path matcher for this host
Wildcards: Support subdomain wildcards like *.example.com
Multiple domains: Same path matcher can serve multiple hosts
🔄 Traffic Routing Examples
graph LR
subgraph "Incoming Requests"
R1[example.com/]
R2[example.com/api/users]
R3[api.example.com/v1/data]
R4[example.com/static/logo.png]
R5[admin.example.com/dashboard]
end
subgraph "URL Map Processing"
UM[URL Map Rules]
end
subgraph "Backend Services"
BS1[Web Service Main Website]
BS2[API Service Application API]
BS3[API V1 Service Legacy API]
BS4[Static Service CDN/Assets]
BS5[Admin Service Management Panel]
end
R1 --> UM
R2 --> UM
R3 --> UM
R4 --> UM
R5 --> UM
UM --> BS1
UM --> BS2
UM --> BS3
UM --> BS4
UM --> BS5
style R1 fill:#e1f5fe
style R2 fill:#f3e5f5
style R3 fill:#e8f5e8
style R4 fill:#fff3e0
style R5 fill:#fce4ec
sequenceDiagram
participant Client
participant LB as Load Balancer
participant UM as URL Map
participant HostRule as Host Rules
participant PathMatcher as Path Matcher
participant RouteRule as Route Rules
participant Backend as Backend Service
Client->>LB: Request: api.example.com/v1/users?version=beta
LB->>UM: Route Request
UM->>HostRule: Check Host: api.example.com
HostRule->>PathMatcher: Match Found → api-matcher
PathMatcher->>RouteRule: Check Route Rules (Priority Order)
alt Route Rule Match Found
RouteRule->>Backend: Route to specific backend
Note over RouteRule: Headers, Query Params, etc.
else No Route Rule Match
PathMatcher->>Backend: Use Path Rules
Note over PathMatcher: /v1/* → api-v1-service
end
Backend->>Client: Response
Note over UM: Evaluation Order: 1. Host Rules 2. Route Rules (by priority) 3. Path Rules 4. Default Service
⚠️ Best Practices & Common Pitfalls
✅ Best Practices
Start Simple: Begin with basic path routing, add complexity gradually
Use Host Rules: Separate different applications/APIs by subdomain
Path Specificity: More specific paths should come first in path rules
Default Service: Always have a reliable fallback service
Testing: Use gcloud compute url-maps test-route before production
Documentation: Export URL maps to YAML for version control
⚠️ Common Pitfalls
Order Matters: Route rules are evaluated by priority, path rules by specificity
Wildcard Confusion:/api/* matches /api/ but not /api
Host Header Case: Host matching is case-insensitive
Trailing Slashes:/api/ and /api are different paths
Regex Not Supported: Only simple wildcards (*) are supported in paths
Backend Dependencies: Ensure all referenced backend services exist