Skip to main content

Quickstart: Kubernetes Endpoints

This quickstart uses the ngrok Kubernetes Operator and the ngrok agent to create a Kubernetes-bound Endpoint, which is accessible to other pods in your cluster as a native Service. ngrok then handles all routing to the upstream service, which can be running anywhere, like your development laptop or a cloud-based developer environment.

When you use Kubernetes Endpoints, you can:

  • View changes to your local services immediately by projecting your local development environment into a remote development or staging cluster.
  • Allow services in multiple clusters to communicate over a service mesh that doesn't require firewalls, VPNs, or port forwarding.
  • Securely access your customer's APIs or databases (aka site-to-site connectivity).
  • Allow your Kubernetes-deployed services to call a webhook URL exposed with ngrok to speed up local development or CI jobs.

You also don't need to expose your local services to the public internet or modify the rules to remote clusters.

note

The ngrok Kubernetes Operator is available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the controller incur a cost. Find more details on our pricing page, or, if you're a free user, the free plan limits.

What you'll need​

  • An ngrok account
  • The ngrok CLI installed on your local machine
  • A running cluster with kubectl access with at least one service
  • kubectl and Helm 3.0.0 or later installed locally

1. Install the ngrok Kubernetes Operator​

Add the ngrok Helm chart​

Loading…
note

Whenever you want to update the Operator or install a new version, you must run helm repo update to fetch the latest charts.

Get your ngrok API key and authtoken​

You can get both these from the ngrok dashboard:

The ngrok Kubernetes Operator provisions these as a Kubernetes secret, then uses the authtoken to create tunnels. The Operator uses your API key to manage resources via the ngrok API.

Loading…

Install the Operator​

We recommend installing the Operator into the default ngrok-operator namespace. You can change this depending in the commands blow based on your cluster configuration, but by default, the Operator works with Gateway and routing resources in all namespaces.

You can choose between passing your credentials directly with or creating a Kubernetes Secret resource that you pass to the Helm chart. The simple method only takes one command, but with the secure method, you:

  • Prevent anyone with kubectl access to the cluster from viewing your API key and authtoken with helm get values.
  • Integrate more cleanly with infrastructure as code (IaC) tools and processes.
Loading…

2. Start an Agent Endpoint​

On your local machine, start a new agent endpoint, replacing $PORT with the port your upstream service listens on.

Loading…

The URL of a Kubernetes Endpoint has three parts, which determine how ngrok exposes it inside your cluster: the scheme (http, tcp, or tls), the service name, and the namespace. In this example, ngrok provisions the http://hello-world.default URL into a Kubernetes service named hello-world in the default namespace.

Behind the scenes, your ngrok Kubernetes Operator continuously polls the ngrok API for new endpoints with the kubernetes binding. When it detects your new http://hello-world.default endpoint, it provisions a ClusterIP Kubernetes service that routes directly to that endpoint.

tip

You can also start agent-based Kubernetes Endpoints with:

3. Add Traffic Policy to manipulate requests (optional)​

Kubernetes Endpoints support the entire breadth of Traffic Policy, which lets you filter, manage, and orchestrate traffic as it passes between your local service and your cluster.

Because a Kubernetes Endpoint is only accessible inside of clusters where you've installed the ngrok Kubernetes Operator with your account's credentials, you don't need to add authentication. Instead, you can add a header to your local service's response to demo how it works.

Loading…

Run your Agent Endpoint again with the new file.

Loading…

4. Start making requests​

You can now access your non-Kubernetes service from within your cluster!

You can test it out by running a temporary curl image on your cluster:

Loading…

From within that new pod, curl your endpoint to get a response from your service.

Loading…

The -i flag outputs response headers, which will show any headers you added through your traffic policy.

What's next?​

First, read up on the rest of our Kubernetes Endpoints docs:

Ready to replace Telepresence with ngrok's Kubernetes Endpoints? Read our blog post on the process and why it's easier for both platform engineers and API/app developers.

Kubernetes Endpoints also support Traffic Policy:

Finally, explore the Traffic Inspector in your dashboard for real-time observability of traffic flowing through your endpoint.