Documentation Index
Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Circuit breaking is a resilience pattern that helps maintain system reliability by temporarily rejecting requests when error rates and request volumes exceed predefined thresholds. This prevents overloaded services from spiraling into failure and allows them time to recover.
When circuit breaking is enabled:
🚨 Requests are automatically rejected if too many errors occur within a given time window.
⏳ Traffic pauses for a set period to allow the upstream service to recover.
✅ The system automatically re-evaluates health and resumes traffic once conditions improve.
🔍 What are the benefits of circuit breaking?
Modern applications often rely on multiple microservices, APIs, or external dependencies.
If one service becomes slow or fails, it can cause cascading failures across the entire system.
Key Benefits:
- Isolating failing services so they don’t bring down the entire system.
- Reducing unnecessary load on struggling services.
- Ensuring graceful degradation instead of full service failure.
- If a downstream service becomes overloaded, circuit breaking can prevent other services from also failing.
- Prevents long wait times for users by cutting off slow or failing requests.
- Ensures high-priority services remain available even when others are experiencing high failure rates.
Circuit breaking examples
The following examples show how to set up an endpoint that allows only 1 request every 60 seconds and trips the circuit breaker for 2 minutes.
Check out the circuit breaking Traffic Policy action page for more details about how it functions and the parameters it accepts.
AgentEndpoint
CloudEndpoint
Ingress
Gateway API
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
name: example-agent-endpoint
spec:
url: https://example-hostname.ngrok.io
upstream:
url: http://my-service.my-namespace:8080
trafficPolicy:
inline:
on_http_request:
- actions:
- type: circuit-breaker
config:
error_threshold: 0
volume_threshold: 1
window_duration: 60s
tripped_duration: 2m
enforce: true
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
name: example-cloud-endpoint
spec:
url: https://example-hostname.ngrok.io
trafficPolicy:
policy:
on_http_request:
- actions:
- type: circuit-breaker
config:
error_threshold: 0
volume_threshold: 1
window_duration: 60s
tripped_duration: 2m
enforce: true
💡 Ingress resources do not natively support circuit breaking, but they can be extended using a Traffic Policy.1. Create an NgrokTrafficPolicy
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: circuit-breaker
config:
error_threshold: 0
volume_threshold: 1
window_duration: 60s
tripped_duration: 2m
enforce: true
2. Use the NgrokTrafficPolicy on an Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.ngrok.com/traffic-policy: example-tp
name: example-ingress
namespace: default
spec:
ingressClassName: ngrok
rules:
- host: example-hostname.ngrok.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
💡 Gateway API resources do not natively support circuit breaking, but they can be extended using a Traffic Policy.1. Create an NgrokTrafficPolicy
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: circuit-breaker
config:
error_threshold: 0
volume_threshold: 1
window_duration: 60s
tripped_duration: 2m
enforce: true
2. Use the NgrokTrafficPolicy on a Gateway
The following example showcases supplying the NgrokTrafficPolicy on a Gateway resource. All requests to the Gateway will run the Traffic Policy.
If you prefer, NgrokTrafficPolicy can also be used on the route level by using an externalRef filter on an HTTPRoute. See the using Gateway API guide for examples.apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
annotations:
k8s.ngrok.com/traffic-policy: example-tp
spec:
gatewayClassName: ngrok
listeners:
- name: example-hostname
hostname: "example-hostname.ngrok.io"
port: 443
protocol: HTTPS
