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 ingress rules to remote clusters.
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 K8s cluster with
kubectl
access with at least one service- If you don't have a cluster yet, see our local cluster guide for some options
kubectl
and Helm 3.0.0 or later installed locally
1. Install the ngrok Kubernetes Operator
Add the ngrok Helm chart
Loading…
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 Helm 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 withhelm 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.
You can also start agent-based Kubernetes Endpoints with:
- Our SDKs
- A second cluster
- Cloud Endpoints with the ngrok dashboard
- Our API
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 Traffic Policy 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:
- Traffic Policy overview
- Traffic Policy concepts
- All our available actions, including a few most relevant to these types of endpoints:
Finally, explore the Traffic Inspector in your dashboard for real-time observability of traffic flowing through your endpoint.