Skip to main content

Using ngrok Custom Resources

The following sections offer a brief guide on how using each of ngrok's custom resources work. You can also head to the Custom Resource Definition docs for more detailed information about the structure of each resource and all of their fields.

Using AgentEndpoint​

The AgentEndpoint resource is used to create Agent Endpoints using the operator.

At a high level, Agent Endpoints are endpoints that accept traffic and forward it to an upstream of your choice. They may optionally include traffic policy configuration specified in-line or as a reference to an NgrokTrafficPolicy resource. The lifetime of these endpoints is tied to the lifetime of the "agent" responsible for them, in this scenario, the operator is the "agent", so if the operator is deleted, then the endpoint will be deleted.

The endpoint types page showcases using different protocols with AgentEndpoint and/or CloudEndpoint resources. See the AgentEndpoint Reference for more detailed information about AgentEndpoint structure and fields.

Public AgentEndpoint​

The following example will create a publicly accessible AgentEndpoint that forwards traffic to a Service in the Kubernetes cluster.

Loading…

AgentEndpoint with In-line Traffic Policy​

The following example showcases an AgentEndpoint with in-line traffic policy configuration

Loading…

AgentEndpoint with referenced NgrokTrafficPolicy​

The following example showcases an AgentEndpoint with traffic policy configuration from a referenced NgrokTrafficPolicy resource.

Loading…

AgentEndpoint with client certificates​

If you would like to enforce mutual TLS, you can reference Secret objects that contain client certificates that the operator should use for the AgentEndpoint when connecting to the upstream.

  • The secrets are expected to contain the data in the keys tls.crt and tls.key.
  • The namespace field is optional, and when not supplied, the namespace of the AgentEndpoint will be used.
Loading…

AgentEndpoint Public URL vs. Upstream URL​

With AgentEndpoints, while the public URL of an endpoint may have a scheme such as http://, the upstream.url for that endpoint does not need to also use the same scheme as the public URL. You can create an endpoint with an http:// scheme as the public URL and still use https:// as the scheme for the upstream URL. The following Agent Endpoint accepts cleartext HTTP connections at http://example-http-domain.ngrok.app, and forwards to the kubernetes service https://example-service.default on port 443 over HTTPS.

Loading…

Using CloudEndpoint​

The CloudEndpoint resource is used to create Cloud Endpoints using the operator.

At a high level, Cloud Endpoints are endpoints that live in the ngrok cloud and are always online. They may optionally include traffic policy configuration specified in-line or as a reference to an NgrokTrafficPolicy resource. Since they live in the ngrok cloud, Cloud Endpoints are always accessible, even if the cluster running your ngrok operator goes down.

Unlike Agent Endpoints, Cloud Endpoints do not directly specify a local upstream to forward traffic to since they live in the cloud. Their primary purpose is to run traffic policies which can be used to forward traffic to other endpoints.

A very common pattern is to make a publicly accessible Cloud Endpoint for a hostname that has traffic policy to forward traffic to one of several other Cloud or Agent endpoints depending on the path/headers/etc.

The endpoint types page showcases using different protocols with AgentEndpoint and/or CloudEndpoint resources. See the CloudEndpoint Reference for more detailed information about CloudEndpoint structure and fields.

CloudEndpoint with In-line Traffic Policy​

The following example showcases an CloudEndpoint with in-line traffic policy configuration

Loading…

CloudEndpoint with referenced NgrokTrafficPolicy​

The following example showcases an CloudEndpoint with traffic policy configuration from a referenced NgrokTrafficPolicy resource.

Loading…

CloudEndpoint Routing​

For a more in-depth guide on using CloudEndpoints to forward requests to other endpoints using the forward-internal action, see the request routing guide

Using NgrokTrafficPolicy​

NgrokTrafficPolicy allows you to specify a traffic policy configuration to be used on one or more Ingress, Gateway, CloudEndpoint, or AgentEndpoint resources.

On their own, NgrokTrafficPolicy resources do not do anything unless attached to a CloudEndpoint, Ingress, etc.

The CloudEndpoint and AgentEndpoint custom resources allow you to choose whether you would like to supply traffic policy configuration in-line or as a reference to an NgrokTrafficPolicy resource. This makes it easy to create common NgrokTrafficPolicy resources and re-use them on multiple different resources.

Ingress and Gateway API resources have several methods of accepting NgrokTrafficPolicy resources outlined in the using ingresses and using Gateway API pages.

The following example showcases creating an NgrokTrafficPolicy resource that will return a custom response when the ?debug=true query parameter is sent with the request.

Loading…

See the NgrokTrafficPolicy Reference for more detailed information about NgrokTrafficPolicy structure and fields.

Using Domain, Tunnel, BoundEndpoint, and KubernetesOperator​

Domain, Tunnel, BoundEndpoint, and KubernetesOperator are all custom resources that you should not need to interface with directly very much. They are created by the operator in response to AgentEndpoint, CloudEndpoint, Ingress, and Gateway API resources. They exist primarily to provide feedback to the user about events and resources that are created in response to your configuration and help keep the state of your cluster configuration in-sync with the resources in your ngrok account.

You can use kubectl describe on any of them to check their status and conditions when debugging configuration.

Domains:

  • Domains reserve domains in your ngrok that are used in hostnames across Ingress, etc. resources.
  • Tunnels:
    • Tunnels establish connections to your upstream services to handle forwarding traffic.
    • Tunnel Reference
  • BoundEndpoints:
    • BoundEndpoints project endpoints with a binding type of kubernetes into one or more Kubernetes clusters running the ngrok operator.
    • For more information on endpoint bindings, refer to the bindings page.
    • BoundEndpoint Reference
  • KubernetesOperators:
    • KubernetesOperators are used to synchronize the state of any instances of the ngrok Kubernetes operator with your ngrok account.
    • KubernetesOperator Reference

Using Edges​

Edges are a deprecated custom resource that are not documented as they will be removed soon, so you should not start using Edges or create any new ones now. For those who have installed an early release of the operator and created any HTTPSEdge resources, they can be rewritten as CloudEndpoint and/or AgentEndpoint custom resources. The same is true of the NgrokModuleSet resources that were the precursor to NgrokTrafficPolicy. Edges will be completely removed prior to the 1.0 release of the ngrok Kubernetes operator.