Skip to main content

Istio Issues

Istio is a service mesh.

The purpose of a service mesh is to manage and control how services communicate with each other, without changing the services themselves. A service mesh can:

  • Secure traffic between services
  • Allow or block requests based on policy
  • Route traffic based on rules
  • Observe and control traffic as it flows through the cluster

This guide is intended to help you:

  • Understand where Istio sits in the request path
  • Decide whether Istio is even involved
  • Distinguish between cluster-wide and service-specific issues
  • Collect the right information before escalating
  • Try safe, basic corrective actions when appropriate

This guide is intentionally conservative. If Istio is healthy at a system level, the issue is usually not Istio itself, but how Istio is configured for a specific service.

How Istio Problems Typically Appear​

When Istio is involved, issues usually fall into one of two categories:

  1. Cluster-wide issues, where multiple services or namespaces are affected
  2. Service-specific issues, where a single service, route, or policy is misconfigured
Rule of Thumb

If all pods in istio-system are healthy, Istio is generally working at a global level.

Deep Dive Topics​

  • Architecture - How Istio Ambient Mode works
  • Diagnostics - Global checks, istioctl analyze, service-specific troubleshooting
  • Gateway Issues - Gateway API resources, HTTPRoutes, traffic routing

Escalate Immediately If​

  • istiod or ztunnel will not go healthy after a rolling restart
  • Gateways or HTTPRoutes are Rejected
  • Traffic is failing cluster-wide