istio-traffic-management

Name: istio-traffic-management
Author: W. Shobson

IstioService MeshKubernetesTraffic ManagementMicroservicesDevOpsCloud NativeCanary Deployment

⭐ 36.8k📄 MIT🕒 2026-06-16Source ↗

Install this skill

npx skills add wshobson/agents

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

Istio traffic management provides granular control over service-to-service communication within Kubernetes clusters by decoupling traffic routing from application code. By manipulating VirtualServices and DestinationRules, operators manage complex request patterns without modifying container images. The mechanism uses the Envoy proxy sidecar to intercept network traffic, enabling sophisticated strategies like traffic splitting for canary releases, controlled fault injection for reliability testing, and mirrored traffic for production-like debugging. This layer allows fine-tuned adjustment of request flow, timeouts, and retries across the entire service mesh. It operates independently of underlying infrastructure, focusing on L7 application protocols to enforce policy, connectivity, and observability. When implemented correctly, it transforms static service discovery into a programmable fabric capable of handling dynamic load balancing, circuit breaking, and secure cross-namespace communication.

When to Use This Skill

•Executing canary deployments with incremental traffic increments
•Performing chaos engineering by injecting delays and aborts
•Shadowing production traffic to validate new service versions
•Enforcing circuit breakers to prevent cascading service failures

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“Shift 10% of traffic to the new microservice version
“Configure a circuit breaker for my inventory API
“Mirror production traffic to the staging environment
“Inject a 5-second delay to test application resilience
“Route requests based on user authentication headers

Pro Tips

💡Always test your Istio configurations in a staging environment before applying to production, especially for critical routing rules.
💡Utilize `istioctl analyze` to validate your Istio resource YAMLs for common configuration errors and best practices before deployment.
💡Combine VirtualServices and DestinationRules effectively to separate routing logic from policy enforcement, improving clarity and maintainability for complex traffic patterns.

What this skill does

•Weight-based traffic shifting between service versions
•L7 header-based request routing logic
•Outlier detection for automatic circuit breaking
•Automated retry logic with configurable backoff
•Real-world traffic shadowing for side-by-side comparison

When not to use it

✕Managing simple applications without microservices interdependencies
✕Scenarios where low-latency requirements forbid sidecar proxy overhead
✕Environments lacking an existing service mesh installation

Example workflow

Define subsets in a DestinationRule to group pods by version labels
Create a VirtualService to set routing rules and traffic weights
Apply fault injection policies to identify service bottlenecks
Monitor sidecar metrics to confirm traffic distribution
Adjust weights or timeout thresholds based on observed health

Prerequisites

–Running Kubernetes cluster
–Istio control plane installation
–Envoy sidecar injection enabled for target namespaces

Pitfalls & limitations

!Incorrect label selectors in DestinationRules lead to traffic dropping
!Circular dependencies in routing rules can cause request loops
!Misconfigured timeouts may kill valid long-running requests

FAQ

What is the difference between a VirtualService and a DestinationRule?

A VirtualService controls how requests are routed to a service, while a DestinationRule defines the policies applied to traffic once it reaches the specific destination.

Can I use Istio traffic management with services outside the cluster?

Yes, ServiceEntry resources allow you to register external endpoints into the mesh, enabling you to apply traffic policies to them as if they were internal services.

Does traffic mirroring impact the primary response?

No, traffic mirroring is 'fire and forget.' The primary service handles the original request and returns the result, while the mirrored request is sent asynchronously without affecting the client response.

How it compares

Doing this manually requires complex Nginx configurations or application-level logic; Istio handles this via declarative CRDs that standardize behavior across all mesh services.

Source & trust

⭐ 37k stars📄 MIT🕒 Updated 2026-06-16

View original skill on GitHub →

📄 Full skill instructions — original source: wshobson/agents

# Istio Traffic Management

Comprehensive guide to Istio traffic management for production service mesh deployments.

## When to Use This Skill

- Configuring service-to-service routing
- Implementing canary or blue-green deployments
- Setting up circuit breakers and retries
- Load balancing configuration
- Traffic mirroring for testing
- Fault injection for chaos engineering

## Core Concepts

### 1. Traffic Management Resources

| Resource | Purpose | Scope |
| ------------------- | ----------------------------- | ------------- |
| **VirtualService** | Route traffic to destinations | Host-based |
| **DestinationRule** | Define policies after routing | Service-based |
| **Gateway** | Configure ingress/egress | Cluster edge |
| **ServiceEntry** | Add external services | Mesh-wide |

### 2. Traffic Flow

Client → Gateway → VirtualService → DestinationRule → Service
                   (routing)        (policies)        (pods)

## Templates

### Template 1: Basic Routing

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: reviews-route
  namespace: bookinfo
spec:
  hosts:
    - reviews
  http:
    - match:
        - headers:
            end-user:
              exact: jason
      route:
        - destination:
            host: reviews
            subset: v2
    - route:
        - destination:
            host: reviews
            subset: v1
---
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: reviews-destination
  namespace: bookinfo
spec:
  host: reviews
  subsets:
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2
    - name: v3
      labels:
        version: v3

### Template 2: Canary Deployment

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-service-canary
spec:
  hosts:
    - my-service
  http:
    - route:
        - destination:
            host: my-service
            subset: stable
          weight: 90
        - destination:
            host: my-service
            subset: canary
          weight: 10
---
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-service-dr
spec:
  host: my-service
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100
      http:
        h2UpgradePolicy: UPGRADE
        http1MaxPendingRequests: 100
        http2MaxRequests: 1000
  subsets:
    - name: stable
      labels:
        version: stable
    - name: canary
      labels:
        version: canary

### Template 3: Circuit Breaker

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: circuit-breaker
spec:
  host: my-service
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100
      http:
        http1MaxPendingRequests: 100
        http2MaxRequests: 1000
        maxRequestsPerConnection: 10
        maxRetries: 3
    outlierDetection:
      consecutive5xxErrors: 5
      interval: 30s
      baseEjectionTime: 30s
      maxEjectionPercent: 50
      minHealthPercent: 30

### Template 4: Retry and Timeout

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: ratings-retry
spec:
  hosts:
    - ratings
  http:
    - route:
        - destination:
            host: ratings
      timeout: 10s
      retries:
        attempts: 3
        perTryTimeout: 3s
        retryOn: connect-failure,refused-stream,unavailable,cancelled,retriable-4xx,503
        retryRemoteLocalities: true

### Template 5: Traffic Mirroring

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: mirror-traffic
spec:
  hosts:
    - my-service
  http:
    - route:
        - destination:
            host: my-service
            subset: v1
      mirror:
        host: my-service
        subset: v2
      mirrorPercentage:
        value: 100.0

### Template 6: Fault Injection

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: fault-injection
spec:
  hosts:
    - ratings
  http:
    - fault:
        delay:
          percentage:
            value: 10
          fixedDelay: 5s
        abort:
          percentage:
            value: 5
          httpStatus: 503
      route:
        - destination:
            host: ratings

### Template 7: Ingress Gateway

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: my-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
    - port:
        number: 443
        name: https
        protocol: HTTPS
      tls:
        mode: SIMPLE
        credentialName: my-tls-secret
      hosts:
        - "*.example.com"
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-vs
spec:
  hosts:
    - "api.example.com"
  gateways:
    - my-gateway
  http:
    - match:
        - uri:
            prefix: /api/v1
      route:
        - destination:
            host: api-service
            port:
              number: 8080

## Load Balancing Strategies

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: load-balancing
spec:
  host: my-service
  trafficPolicy:
    loadBalancer:
      simple: ROUND_ROBIN # or LEAST_CONN, RANDOM, PASSTHROUGH
---
# Consistent hashing for sticky sessions
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: sticky-sessions
spec:
  host: my-service
  trafficPolicy:
    loadBalancer:
      consistentHash:
        httpHeaderName: x-user-id
        # or: httpCookie, useSourceIp, httpQueryParameterName

## Best Practices

### Do's

- **Start simple** - Add complexity incrementally
- **Use subsets** - Version your services clearly
- **Set timeouts** - Always configure reasonable timeouts
- **Enable retries** - But with backoff and limits
- **Monitor** - Use Kiali and Jaeger for visibility

### Don'ts

- **Don't over-retry** - Can cause cascading failures
- **Don't ignore outlier detection** - Enable circuit breakers
- **Don't mirror to production** - Mirror to test environments
- **Don't skip canary** - Test with small traffic percentage first

## Debugging Commands

# Check VirtualService configuration
istioctl analyze

# View effective routes
istioctl proxy-config routes deploy/my-app -o json

# Check endpoint discovery
istioctl proxy-config endpoints deploy/my-app

# Debug traffic
istioctl proxy-config log deploy/my-app --level debug

## Resources

- [Istio Traffic Management](https://istio.io/latest/docs/concepts/traffic-management/)
- [Virtual Service Reference](https://istio.io/latest/docs/reference/config/networking/virtual-service/)
- [Destination Rule Reference](https://istio.io/latest/docs/reference/config/networking/destination-rule/)

By W. Shobson

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/istio-traffic-management/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/wshobson/agents/istio-traffic-management/SKILL.md
Cursor: ~/.cursor/skills/wshobson/agents/istio-traffic-management/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/wshobson/agents/istio-traffic-management/SKILL.md