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.
There are scenarios where you may want to issue static responses directly from the API Gateway rather than forwarding requests to an upstream service.
This allows you to handle specific request patterns efficiently without consuming backend resources.
By defining custom response rules, you can:
🛠 Return predefined error messages, such as a common 404 Not Found page.
⚡ Reduce backend load by handling certain requests at the gateway level.
🚀 Improve response times for static responses, such as maintenance messages.
🔍 What are the benefits of static responses?
Instead of routing every request to your upstream services, certain requests can be handled at the gateway layer, improving efficiency and reducing unnecessary backend calls.
Key Benefits:
- Reduce Backend Load: Offload simple responses without hitting your backend.
- Improve Performance: Serve common responses instantly at the edge.
- Standardize Error Handling: Return the same response across multiple applications.
- Enhance Availability: Provide a fallback response if your backend is unavailable.
- Handle Maintenance Windows Gracefully: Display a scheduled maintenance message without modifying backend applications.
Static response examples
The following examples create an endpoint that returns a custom HTML maintenance page back for all requests to your endpoint.
Check out the custom response 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: custom-response
config:
status_code: 503
body: <html><body><h1>Service Unavailable</h1><p>Our servers are currently
down for maintenance. Please check back later.</p></body></html>
headers:
content-type: text/html
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: custom-response
config:
status_code: 503
body: <html><body><h1>Service Unavailable</h1><p>Our servers are currently
down for maintenance. Please check back later.</p></body></html>
headers:
content-type: text/html
💡 Ingress resources do not natively support serving custom responses, 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: custom-response
config:
status_code: 503
body: <html><body><h1>Service Unavailable</h1><p>Our servers are currently
down for maintenance. Please check back later.</p></body></html>
headers:
content-type: text/html
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 serving custom responses, 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: custom-response
config:
status_code: 503
body: <html><body><h1>Service Unavailable</h1><p>Our servers are currently
down for maintenance. Please check back later.</p></body></html>
headers:
content-type: text/html
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
