istio · diff
git:20251122.a3c5628 to git:20260709.80a1f3d
61 added, 422 removed. Audit A to A.
---
name: istio
- description: Manage Istio service mesh configurations, traffic management, security policies, and observability. Use when working with Istio, service mesh, traffic routing, virtual services, destination rules, gateways, mTLS, authentication policies, authorization policies, or microservices networking in Kubernetes.
+ description: Istio service mesh: traffic management, gateways, virtual services, destination rules, mTLS, authorization policies, EnvoyFilters, and observability.
---
# Istio Service Mesh Management
- Comprehensive expertise for managing Istio service mesh in Kubernetes environments, including traffic management, security, and observability configurations.
+ Expertise for managing Istio service mesh in Kubernetes: traffic management, security, and observability.
## Core Capabilities
- This skill helps with:
-
- **Traffic Management**: VirtualServices, DestinationRules, Gateways, ServiceEntries
- - **Security**: PeerAuthentication, RequestAuthentication, AuthorizationPolicies, mTLS configuration
- - **Observability**: Telemetry, metrics, tracing, logging configuration
+ - **Security**: PeerAuthentication, RequestAuthentication, AuthorizationPolicies, mTLS
+ - **Observability**: Telemetry, metrics, tracing, logging
- **Networking**: Sidecars, WorkloadEntries, EnvoyFilters
- - **Multi-cluster**: Multi-cluster mesh configuration and troubleshooting
+ - **Multi-cluster**: Multi-cluster mesh setup and troubleshooting
## Prerequisites
- Required tools (I'll check for these):
-
- - `kubectl` - Kubernetes CLI
- - `istioctl` - Istio CLI tool
-
- Optional but recommended:
-
- - `helm` - For Istio installation via Helm charts
+ - `kubectl` - Kubernetes CLI (required)
+ - `istioctl` - Istio CLI (required)
+ - `helm` - For Helm-based installation (optional)
- ## Quick Start Examples
+ Tested with Istio 1.18.x–1.24.x and Kubernetes 1.26.x–1.31.x.
- ### Check Istio Installation
+ ## Quick Start
```bash
- # Verify Istio is installed
- istioctl version
+ # Install / upgrade the control plane
+ istioctl install --set profile=default -y
- # Check control plane status
+ # Verify installation and control plane
+ istioctl version
kubectl -n istio-system get pods
-
- # Verify proxy status
istioctl proxy-status
+
+ # Enable automatic sidecar injection for a namespace
+ kubectl label namespace default istio-injection=enabled
+
+ # Validate configuration
+ istioctl analyze
```
- ### Traffic Management
+ For operational workflows (deploy, canary, circuit breaking) and diagnostics, see [OPERATIONS.md](OPERATIONS.md).
- **Create a VirtualService for canary deployment:**
+ ## Core Concepts (Short Examples)
+ ### VirtualService — routing (e.g. canary by header + weight)
+
```yaml
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
name: my-service
spec:
hosts:
- my-service
http:
- match:
- headers:
canary:
exact: "true"
route:
- - destination:
- host: my-service
- subset: v2
+ - destination: { host: my-service, subset: v2 }
- route:
- - destination:
- host: my-service
- subset: v1
+ - destination: { host: my-service, subset: v1 }
weight: 90
- - destination:
- host: my-service
- subset: v2
+ - destination: { host: my-service, subset: v2 }
weight: 10
```
- **Create corresponding DestinationRule:**
+ ### DestinationRule — subsets and traffic policy
```yaml
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
name: my-service
spec:
host: my-service
trafficPolicy:
connectionPool:
- tcp:
- maxConnections: 100
- http:
- http1MaxPendingRequests: 50
- http2MaxRequests: 100
+ tcp: { maxConnections: 100 }
+ http: { http1MaxPendingRequests: 50, http2MaxRequests: 100 }
outlierDetection:
consecutiveErrors: 5
interval: 30s
baseEjectionTime: 30s
subsets:
- name: v1
- labels:
- version: v1
+ labels: { version: v1 }
- name: v2
- labels:
- version: v2
- ```
-
- ### Security Configuration
-
- **Enable strict mTLS mesh-wide:**
-
- ```yaml
- apiVersion: security.istio.io/v1beta1
- kind: PeerAuthentication
- metadata:
- name: default
- namespace: istio-system
- spec:
- mtls:
- mode: STRICT
- ```
-
- **Create an AuthorizationPolicy:**
-
- ```yaml
- apiVersion: security.istio.io/v1beta1
- kind: AuthorizationPolicy
- metadata:
- name: frontend-policy
- namespace: default
- spec:
- selector:
- matchLabels:
- app: frontend
- action: ALLOW
- rules:
- - from:
- - source:
- principals: ["cluster.local/ns/default/sa/backend"]
- to:
- - operation:
- methods: ["GET", "POST"]
- paths: ["/api/*"]
+ labels: { version: v2 }
```
- ### Gateway Configuration
-
- **Create an Ingress Gateway:**
+ ### Gateway — ingress (HTTP + TLS)
```yaml
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
name: my-gateway
spec:
selector:
istio: ingressgateway
servers:
- - port:
- number: 80
- name: http
- protocol: HTTP
- hosts:
- - "example.com"
- - port:
- number: 443
- name: https
- protocol: HTTPS
- tls:
- mode: SIMPLE
- credentialName: example-credential
- hosts:
- - "example.com"
- ```
-
- ## Common Workflows
-
- ### 1. Deploy a New Service with Istio
-
- ```bash
- # Label namespace for automatic sidecar injection
- kubectl label namespace default istio-injection=enabled
-
- # Deploy your application
- kubectl apply -f deployment.yaml
-
- # Verify sidecar injection
- kubectl get pods -o jsonpath='{.items[*].spec.containers[*].name}'
-
- # Create VirtualService and DestinationRule
- kubectl apply -f virtualservice.yaml
- kubectl apply -f destinationrule.yaml
-
- # Test traffic routing
- kubectl exec -it pod-name -c istio-proxy -- curl http://my-service
- ```
-
- ### 2. Implement Canary Deployment
-
- ```bash
- # Deploy v2 of your service
- kubectl apply -f deployment-v2.yaml
-
- # Create traffic split (90/10)
- kubectl apply -f virtualservice-canary.yaml
-
- # Monitor traffic distribution
- istioctl dashboard prometheus
- # Query: rate(istio_requests_total{destination_service="my-service"}[1m])
-
- # Gradually increase v2 traffic
- # Update VirtualService weights: 70/30, 50/50, 30/70, 0/100
-
- # Finalize deployment
- kubectl delete -f deployment-v1.yaml
- ```
-
- ### 3. Configure Circuit Breaking
-
- ```yaml
- apiVersion: networking.istio.io/v1beta1
- kind: DestinationRule
- metadata:
- name: circuit-breaker
- spec:
- host: my-service
- trafficPolicy:
- connectionPool:
- tcp:
- maxConnections: 100
- http:
- http1MaxPendingRequests: 10
- maxRequestsPerConnection: 2
- outlierDetection:
- consecutiveErrors: 5
- interval: 10s
- baseEjectionTime: 30s
- maxEjectionPercent: 50
- minHealthPercent: 40
- ```
-
- ### 4. Enable Request Timeout and Retries
-
- ```yaml
- apiVersion: networking.istio.io/v1beta1
- kind: VirtualService
- metadata:
- name: timeout-retry
- spec:
- hosts:
- - my-service
- http:
- - route:
- - destination:
- host: my-service
- timeout: 10s
- retries:
- attempts: 3
- perTryTimeout: 2s
- retryOn: 5xx,reset,connect-failure,refused-stream
- ```
-
- ## Troubleshooting Guide
-
- ### Common Issues and Solutions
-
- **Issue: Sidecar not injected**
-
- ```bash
- # Check namespace label
- kubectl get namespace -L istio-injection
-
- # Check pod annotations
- kubectl get pod pod-name -o yaml | grep sidecar.istio.io
-
- # Manual injection (if needed)
- istioctl kube-inject -f deployment.yaml | kubectl apply -f -
- ```
-
- **Issue: Traffic not routing correctly**
-
- ```bash
- # Verify VirtualService configuration
- kubectl get virtualservice my-service -o yaml
-
- # Check destination rule
- kubectl get destinationrule my-service -o yaml
-
- # Analyze proxy configuration
- istioctl proxy-config routes pod-name
-
- # Check logs
- kubectl logs pod-name -c istio-proxy
- ```
-
- **Issue: mTLS connection failures**
-
- ```bash
- # Check PeerAuthentication
- kubectl get peerauthentication -A
-
- # Verify certificates
- istioctl proxy-config secret pod-name
-
- # Test mTLS connectivity
- istioctl experimental authz check pod-name
- ```
-
- **Issue: High latency or timeouts**
-
- ```bash
- # Check circuit breaker status
- istioctl proxy-config cluster pod-name --fqdn my-service
-
- # Analyze metrics
- istioctl dashboard prometheus
-
- # Check for outlier detection
- kubectl logs -n istio-system deploy/istiod | grep outlier
- ```
-
- ## Diagnostic Commands
-
- ### Proxy Status and Configuration
-
- ```bash
- # Get proxy status for all pods
- istioctl proxy-status
-
- # Get specific proxy configuration
- istioctl proxy-config cluster pod-name
- istioctl proxy-config listener pod-name
- istioctl proxy-config route pod-name
- istioctl proxy-config endpoint pod-name
-
- # Get bootstrap configuration
- istioctl proxy-config bootstrap pod-name
-
- # Get secrets configuration
- istioctl proxy-config secret pod-name
- ```
-
- ### Validation and Analysis
-
- ```bash
- # Analyze Istio configuration
- istioctl analyze
-
- # Validate specific resource
- istioctl validate -f virtualservice.yaml
-
- # Describe configuration issues
- istioctl analyze --namespace default
-
- # Experimental features
- istioctl experimental describe pod pod-name
- istioctl experimental wait --for=distribution virtualservice/my-service
- ```
-
- ### Metrics and Observability
-
- ```bash
- # Open Kiali dashboard
- istioctl dashboard kiali
-
- # Open Prometheus dashboard
- istioctl dashboard prometheus
-
- # Open Grafana dashboard
- istioctl dashboard grafana
-
- # Open Jaeger dashboard
- istioctl dashboard jaeger
-
- # View metrics for a service
- kubectl exec -it pod-name -c istio-proxy -- curl localhost:15000/stats/prometheus
+ - port: { number: 80, name: http, protocol: HTTP }
+ hosts: ["example.com"]
+ - port: { number: 443, name: https, protocol: HTTPS }
+ tls: { mode: SIMPLE, credentialName: example-credential }
+ hosts: ["example.com"]
```
- ## Security Best Practices
-
- ### 1. Enable Strict mTLS
-
- Always enable strict mTLS for production environments:
+ ### mTLS — PeerAuthentication (strict, mesh-wide)
```yaml
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
namespace: istio-system
spec:
mtls:
mode: STRICT
```
- ### 2. Implement Fine-grained Authorization
-
- Use AuthorizationPolicies with least privilege principle:
+ ### AuthorizationPolicy — least-privilege allow
```yaml
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
- name: deny-all
- namespace: default
- spec:
- action: DENY
- rules:
- - {}
- ---
- apiVersion: security.istio.io/v1beta1
- kind: AuthorizationPolicy
- metadata:
- name: allow-specific
+ name: frontend-policy
namespace: default
spec:
selector:
matchLabels:
- app: my-app
+ app: frontend
action: ALLOW
rules:
- from:
- source:
- principals: ["cluster.local/ns/default/sa/frontend"]
+ principals: ["cluster.local/ns/default/sa/backend"]
to:
- operation:
- methods: ["GET"]
- ```
-
- ### 3. JWT Authentication
-
- Configure JWT validation for external authentication:
-
- ```yaml
- apiVersion: security.istio.io/v1beta1
- kind: RequestAuthentication
- metadata:
- name: jwt-auth
- namespace: default
- spec:
- selector:
- matchLabels:
- app: my-app
- jwtRules:
- - issuer: "https://auth.example.com"
- jwksUri: "https://auth.example.com/.well-known/jwks.json"
- audiences:
- - "my-app"
- ```
-
- ## Performance Optimization
-
- ### Resource Management
-
- ```yaml
- # Sidecar resource limits
- apiVersion: v1
- kind: Pod
- metadata:
- annotations:
- sidecar.istio.io/proxyCPU: "100m"
- sidecar.istio.io/proxyMemory: "128Mi"
- sidecar.istio.io/proxyCPULimit: "500m"
- sidecar.istio.io/proxyMemoryLimit: "512Mi"
- ```
-
- ### Sidecar Scoping
-
- Reduce sidecar configuration overhead:
-
- ```yaml
- apiVersion: networking.istio.io/v1beta1
- kind: Sidecar
- metadata:
- name: default
- namespace: default
- spec:
- egress:
- - hosts:
- - "./*"
- - "istio-system/*"
+ methods: ["GET", "POST"]
+ paths: ["/api/*"]
```
- ## Advanced Patterns
-
- ### Multi-cluster Configuration
-
- For detailed multi-cluster setup, see [MULTICLUSTER.md](MULTICLUSTER.md).
-
- ### Custom Envoy Filters
-
- For advanced Envoy configuration, see [ENVOYFILTER.md](ENVOYFILTER.md).
-
- ### Telemetry Configuration
-
- For observability setup, see [TELEMETRY.md](TELEMETRY.md).
-
- ## Working with This Skill
-
- When you ask me to:
-
- - Create or modify Istio resources, I'll provide proper YAML configurations
- - Debug issues, I'll guide you through systematic troubleshooting
- - Implement patterns, I'll suggest best practices and gotchas
- - Analyze configurations, I'll use `istioctl analyze` and other diagnostic tools
-
- I always:
-
- 1. Check if required tools are available
- 2. Verify current Istio version for compatibility
- 3. Validate configurations before applying
- 4. Provide rollback steps for risky changes
- 5. Include monitoring and verification steps
+ ## Reference Files
- ## Version Compatibility
+ | File | Read this when… |
+ | --- | --- |
+ | [OPERATIONS.md](OPERATIONS.md) | Deploying/canary rollouts, circuit breaking & retries, troubleshooting sidecar injection / routing / mTLS / latency, or running `istioctl proxy-config`, `analyze`, and dashboard diagnostics. |
+ | [PATTERNS.md](PATTERNS.md) | Production patterns: blue-green, A/B, dark launch, bulkhead, zero-trust mTLS, defense-in-depth authz, JWT/external auth, multi-tenancy, connection-pool and sidecar performance tuning, chaos testing. |
+ | [MULTICLUSTER.md](MULTICLUSTER.md) | Setting up or debugging a multi-cluster mesh: primary-remote/multi-primary models, cross-network gateways, trust-domain federation. |
+ | [ENVOYFILTER.md](ENVOYFILTER.md) | Writing custom EnvoyFilters: header manipulation, rate limiting, Wasm/Lua, ext_authz, custom load balancing. |
+ | [TELEMETRY.md](TELEMETRY.md) | Configuring observability: custom metrics, tracing (Jaeger/Zipkin/OTel), access logging, Prometheus/Grafana/Kiali. |
- This skill is tested with:
+ ## Working Principles
- - Istio 1.18.x - 1.24.x
- - Kubernetes 1.26.x - 1.31.x
+ When creating or debugging Istio resources I:
- For version-specific features, I'll note compatibility requirements.
+ 1. Check required tools and current Istio version for compatibility
+ 2. Validate configurations with `istioctl analyze` before applying
+ 3. Define VirtualService and DestinationRule together, roll out gradually
+ 4. Provide rollback steps for risky changes and verification/monitoring steps
## Additional Resources
- - [Istio Official Documentation](https://istio.io/latest/docs/)
- - [Istio GitHub Repository](https://github.com/istio/istio)
+ - [Istio Documentation](https://istio.io/latest/docs/)
+ - [Istio GitHub](https://github.com/istio/istio)
- [Istio Community](https://istio.io/latest/about/community/)
-
- For more detailed guidance on specific topics:
-
- - Multi-cluster setup: [MULTICLUSTER.md](MULTICLUSTER.md)
- - EnvoyFilter examples: [ENVOYFILTER.md](ENVOYFILTER.md)
- - Telemetry configuration: [TELEMETRY.md](TELEMETRY.md)
- - Common patterns: [PATTERNS.md](PATTERNS.md)