Browsers are brutally strict about CORS, and Istio adds one more layer where things can go wrong. I’ve seen teams burn hours debugging a “backend bug” that was really just Envoy rejecting a preflight, or a VirtualService that looked right but matched the wrong route.
If you run APIs behind Istio, CORS usually fails in a few predictable ways. The good news: once you know where Istio evaluates CORS and how route matching works, most fixes are straightforward.
How Istio handles CORS
In Istio, CORS is typically configured on a VirtualService using corsPolicy. Envoy then evaluates browser requests at the proxy layer before your app ever sees them.
That means:
- preflight
OPTIONSrequests may be answered by Envoy - actual
GET/POSTrequests may be blocked by the browser even if your backend returned200 - app-level CORS headers can conflict with mesh-level headers
A basic Istio CORS policy looks like this:
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
name: api
spec:
hosts:
- api.example.com
gateways:
- istio-system/public-gateway
http:
- match:
- uri:
prefix: /v1/
corsPolicy:
allowOrigins:
- exact: https://app.example.com
allowMethods:
- GET
- POST
- OPTIONS
allowHeaders:
- Authorization
- Content-Type
exposeHeaders:
- ETag
- Link
- X-RateLimit-Remaining
allowCredentials: true
maxAge: 24h
route:
- destination:
host: api.default.svc.cluster.local
port:
number: 8080
Looks simple. The mistakes usually come from assumptions.
Mistake 1: Allowing * with credentials
This is the classic one. Somebody sets:
allowOrigins:
- exact: "*"
allowCredentials: true
That’s not valid browser behavior for credentialed CORS. If the frontend sends cookies or an Authorization header and expects credentialed cross-origin access, Access-Control-Allow-Origin: * won’t work.
Browsers require a specific origin when credentials are allowed.
Fix
List explicit origins:
corsPolicy:
allowOrigins:
- exact: https://app.example.com
- exact: https://admin.example.com
allowCredentials: true
If you truly have a public API with no credentials, wildcard can be fine:
corsPolicy:
allowOrigins:
- exact: "*"
allowMethods: ["GET", "OPTIONS"]
allowCredentials: false
That’s how many public APIs behave. For example, api.github.com returns:
access-control-allow-origin: *
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset, Warning
That works because it’s designed like a public API, not a cookie-based browser app.
Mistake 2: Forgetting that preflight needs its own allowed headers
A request can fail before your real API call is even sent. If the browser wants to send:
AuthorizationContent-Type: application/json- custom headers like
X-Tenant-Id
it first sends a preflight with Access-Control-Request-Headers.
If Istio’s allowHeaders doesn’t include them, the browser blocks the request.
Broken config
corsPolicy:
allowOrigins:
- exact: https://app.example.com
allowMethods: ["GET", "POST", "OPTIONS"]
allowHeaders:
- Content-Type
Then your frontend sends:
fetch("https://api.example.com/v1/data", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer token",
"X-Tenant-Id": "acme"
},
body: JSON.stringify({ ok: true })
})
Preflight fails because Authorization and X-Tenant-Id weren’t allowed.
Fix
Be explicit:
corsPolicy:
allowOrigins:
- exact: https://app.example.com
allowMethods:
- GET
- POST
- PUT
- DELETE
- OPTIONS
allowHeaders:
- Authorization
- Content-Type
- X-Tenant-Id
If your frontend team keeps adding headers, this is usually where breakage shows up first.
Mistake 3: Not exposing headers the frontend actually needs
A lot of teams think “the response is there, so the browser can read all headers.” Not true.
JavaScript can only read a small set of safelisted response headers unless you expose more with Access-Control-Expose-Headers.
This matters for pagination, rate limiting, retries, and caching. Real APIs expose useful metadata here. GitHub exposes things like ETag, Link, Retry-After, and rate limit headers for exactly this reason.
Broken behavior
Your API returns:
Link: </v1/items?page=2>; rel="next"
ETag: "abc123"
X-RateLimit-Remaining: 42
But your frontend sees null when calling:
response.headers.get("Link")
Fix
Expose what the browser app needs:
corsPolicy:
exposeHeaders:
- ETag
- Link
- Location
- Retry-After
- X-RateLimit-Limit
- X-RateLimit-Remaining
Don’t expose random internal headers just because you can. Keep it intentional.
Mistake 4: Defining CORS on the wrong route
Istio route matching is where I see the most confusion. You may have multiple http blocks, and only one of them has the corsPolicy. If the request matches a different route first, your CORS policy never applies.
Example of accidental mismatch
http:
- match:
- uri:
prefix: /api/
route:
- destination:
host: api.default.svc.cluster.local
- match:
- uri:
prefix: /api/public/
corsPolicy:
allowOrigins:
- exact: https://app.example.com
allowMethods: ["GET", "OPTIONS"]
route:
- destination:
host: api.default.svc.cluster.local
Looks harmless, but /api/public/users matches /api/ first. The second route is never used.
Fix
Put more specific matches first:
http:
- match:
- uri:
prefix: /api/public/
corsPolicy:
allowOrigins:
- exact: https://app.example.com
allowMethods: ["GET", "OPTIONS"]
route:
- destination:
host: api.default.svc.cluster.local
- match:
- uri:
prefix: /api/
route:
- destination:
host: api.default.svc.cluster.local
When CORS “randomly” works on one endpoint but not another, route order is one of the first things I check.
Mistake 5: Mixing app-level and Istio-level CORS headers
This gets messy fast. Your backend framework adds:
Access-Control-Allow-Origin: https://app.example.com
Then Envoy adds:
Access-Control-Allow-Origin: *
Now you have conflicting behavior, duplicate headers, or a browser rejecting the response.
Fix
Pick one layer to own CORS.
For most mesh setups, I prefer Istio owning edge CORS for consistency. Then disable framework CORS middleware in the app if possible.
If you need app-level CORS because rules differ heavily by endpoint or tenant, keep Istio out of it for those routes. Just don’t split responsibility across both unless you enjoy weird bugs.
Mistake 6: Forgetting OPTIONS at the gateway or auth layer
Even if corsPolicy is correct, preflight may still fail because something else blocks OPTIONS:
- an
AuthorizationPolicy - external auth
- JWT enforcement
- app code that returns
405 Method Not Allowed
Preflight requests usually don’t include the same auth context as the actual request. If your security layer demands auth on OPTIONS, browsers never get past preflight.
Fix
Allow unauthenticated OPTIONS where appropriate.
A simple pattern is to carve out OPTIONS in your auth policy logic so Envoy can answer preflights cleanly.
Also verify the gateway route actually matches OPTIONS. If route conditions are too strict, preflight won’t hit the CORS-enabled route.
Mistake 7: Using regex or origin matching too loosely
People often try to allow “all subdomains” and get sloppy with regex. That can accidentally trust origins you didn’t mean to trust.
Risky example
allowOrigins:
- regex: https://.*example.com
That can match more than you think.
Fix
Prefer exact origins where possible:
allowOrigins:
- exact: https://app.example.com
- exact: https://admin.example.com
If you really need regex, keep it tight and review it like security-sensitive input.
Mistake 8: Debugging with curl only
curl is useful, but it doesn’t enforce browser CORS rules. I’ve seen people say “CORS is fine” because curl got a 200, while the browser was still blocking access.
Better way to test
Check preflight explicitly:
curl -i -X OPTIONS "https://api.example.com/v1/data" \
-H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: authorization,content-type,x-tenant-id"
You want to see headers like:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Headers: Authorization,Content-Type,X-Tenant-Id
Then test in the browser devtools network tab. The browser is the real CORS client, not curl.
Mistake 9: Ignoring cache behavior with maxAge
If you omit maxAge, browsers may send more preflights than necessary. If you set it too aggressively during active development, the browser may cache broken policy and make you think your fix didn’t work.
Fix
Use a sane value in production:
maxAge: 24h
During debugging, lower it or clear browser cache. Otherwise you’ll end up chasing ghosts.
A practical baseline config
If you want a boring, reliable starting point for a browser SPA talking to an Istio-backed API:
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
name: api
spec:
hosts:
- api.example.com
gateways:
- istio-system/public-gateway
http:
- match:
- uri:
prefix: /v1/
corsPolicy:
allowOrigins:
- exact: https://app.example.com
allowMethods:
- GET
- POST
- PUT
- DELETE
- OPTIONS
allowHeaders:
- Authorization
- Content-Type
- If-None-Match
exposeHeaders:
- ETag
- Link
- Location
- Retry-After
- X-RateLimit-Limit
- X-RateLimit-Remaining
allowCredentials: true
maxAge: 24h
route:
- destination:
host: api.default.svc.cluster.local
port:
number: 8080
That covers most real frontend needs without opening the door too wide.
If you’re also tightening other browser-facing headers at the gateway, CORS is only one piece of the story. For broader header hardening, see https://csp-guide.com.
For Istio-specific field behavior, the canonical reference is the official docs: https://istio.io/latest/docs/reference/config/networking/virtual-service/.
CORS in Istio isn’t hard once you stop treating it like magic. Be explicit about origins, methods, headers, and route matching. Most breakage comes from vague config, not from Envoy doing something mysterious.