Using Ingresses
How the ngrok Operator Uses Ingresses
The ngrok Kubernetes operator consumes Ingress
resources and translates them into the native ngrok CloudEndpoint
and AgentEndpoint
custom resources.
Each hostname from the Ingress
resources you configure will cause the operator to create a CloudEndpoint
for the hostname.
Each unique upstream service you reference using HTTPRoute
resources will cause the operator to create an AgentEndpoint
with an internal
binding so that it is not accessible directly on the internet.
The operator then generates ngrok traffic policy configuration on those CloudEndpoint
to perform all the routing and actions specified in your Gateway API configuration and route to the internal AgentEndpoint
resources that handle forwarding traffic to your upstream services.
When you create/update/delete Gateway API resources, the operator will automatically handle creating/updating/deleting the CloudEndpoint
and AgentEndpoint
resources as needed.
Fan-out vs Multiple
The operator supports using a single ingress for your hostname that includes several rules such as the below example.
Loading…
Or you can create multiple different Ingress
resources that produce the same effect such as the example below.
The operator will translate both examples into the same configuration.
Loading…
Using NgrokTrafficPolicy
with Ingress
To extend the functionality of Ingress
resources, you have the option of combining them with NgrokTrafficPolicy
resources to take advantage of ngrok's traffic policy system.
NgrokTrafficPolicy
can be used with Ingress
resources in three different ways:
- As an annotation
- When supplied via an annotation, the rules from the
NgrokTrafficPolicy
run first when requests are sent to any endpoints created for theIngress
before any rules from traffic policies supplied as backends or the default backend. - If used in this way, the traffic policy may "terminate" the request by sending back a response or by forwarding to another endpoint using the
forward-internal
action, but if done so, then the request will not be further processed by any other rules in theIngress
. - This can allow you to enforce common actions such as header manipulation or authentication for any request matching the ingress regardless of which
Ingress
rule the request may match.
- When supplied via an annotation, the rules from the
- As the backend for a specific rule
NgrokTrafficPolicy
resources can be used in place of aService
for the backend of an Ingress rule.- When used this way, the rules from these traffic policies are executed after any traffic policy rules from an annotation
NgrokTrafficPolicy
(if supplied) and only if the request matches theIngress
rule. Since theNgrokTrafficPolicy
is used in-place of aService
it is expected that theNgrokTrafficPolicy
will "terminate" the request either by sending back the response on its own, or forwarding to another endpoint using theforward-internal
action.
- As the default backend
- You may use an
NgrokTrafficPolicy
as the default backend of yourIngress
. The rules from the traffic policy will only be executed if the request does not match any of your otherIngress
rules. - Since the
NgrokTrafficPolicy
is used in-place of aService
it is expected that theNgrokTrafficPolicy
will "terminate" the request either by sending back the response on its own, or forwarding to another endpoint using theforward-internal
action.
- You may use an
You can use one or multiple of the above options depending on your use-case and preferences.
The following example shows how you can supply an NgrokTrafficPolicy
to an Ingress
using an annotation.
It must be in the same namespace as the Ingress
.
Loading…
The following example shows how you can supply an NgrokTrafficPolicy
to an Ingress
as the backend for a specific rule.
It must be in the same namespace as the Ingress
.
Loading…
The following example shows how you can supply an NgrokTrafficPolicy
to an Ingress
as the default backend.
It must be in the same namespace as the Ingress
.
Loading…
Ingress HTTPS Upstreams
If you have an Ingress that routes to a Service that expects HTTPS instead of HTTP, you can specify this using the k8s.ngrok.com/app-protocols
annotation on your Service
.
For example, the following Service
uses the annotation to let the operator know which ports use HTTPS
Loading…
Ingress Conflicts
In order to support the ability for users to configure multiple Ingress
resources that use the same hostname like in the example above, the operator enforces a requirement that all Ingress
resources that use a given hostname must have the same configuration for the k8s.ngrok.com/pooling-enabled
and k8s.ngrok.com/traffic-policy
annotations.
This means that if you use an ingress such as the following example for foo.ngrok.io
, any other Ingress
using the foo.ngrok.io
hostname must have the same pooling and traffic policy annotations as the one below.
Loading…