Policies Overview

Policies in Kuma define how data plane proxies behave and how traffic flows through your mesh. They provide a declarative way to configure security, routing, observability, and resilience features.

Policy fundamentals

Before applying specific policies, understand how Kuma policies work:

Introduction to policies - Learn what policies are, how to write them, and how they’re applied to your mesh
Policy selection logic - How Kuma determines which policy applies when multiple policies match

Security and identity

Control authentication, authorization, and traffic encryption:

MeshTLS - Configure TLS for service-to-service communication
Mutual TLS - Enable automatic mutual TLS between services
MeshTrafficPermission - Define which services can communicate with each other
MeshIdentity - Manage service identity and certificate issuance
MeshTrust - Configure trust roots for your mesh

Traffic routing

Shape and control how requests flow between services:

MeshHTTPRoute - Route HTTP/HTTPS traffic with advanced matching and manipulation
MeshTCPRoute - Route TCP traffic to specific backend services
MeshLoadBalancingStrategy - Configure load balancing algorithms (round-robin, least-request, etc.)
MeshPassthrough - Control how traffic to external destinations is handled

Resilience and reliability

Improve service reliability with automatic failure handling:

MeshTimeout - Set request timeout limits to prevent hanging requests
MeshRetry - Configure automatic retries for failed requests
MeshCircuitBreaker - Prevent cascading failures by detecting unhealthy services
MeshHealthCheck - Actively monitor service health and remove unhealthy instances
MeshFaultInjection - Test resilience by injecting delays and failures
MeshRateLimit - Protect services from being overwhelmed by requests

Monitoring and observability

Monitor and understand your mesh behavior:

MeshAccessLog - Configure access logging to files, Syslog, or external systems
MeshMetric - Collect metrics from proxies for Prometheus or OpenTelemetry
MeshTrace - Enable distributed tracing with Zipkin, Jaeger, or OpenTelemetry

Advanced configuration

Fine-tune proxy behavior for specialized use cases:

MeshProxyPatch - Directly modify Envoy proxy configuration
External services - Integrate services outside the mesh
Protocol support - Understand HTTP/2, grpc, and websocket support
Service health probes - Configure Kubernetes and Universal health probes
Locality-aware load balancing - Prefer local endpoints to reduce latency and cross-zone traffic

Legacy policies

These policies are deprecated in favor of the new Mesh* policies:

See the migration guide for moving to new policies.

Next steps

Start with security: Enable Mutual TLS and MeshTrafficPermission for zero-trust security
Add resilience: Configure MeshTimeout, MeshRetry, and MeshCircuitBreaker
Enable observability: Set up MeshMetric and MeshTrace to monitor your services