Quickstart: Kubernetes Gateway API
This quickstart uses the ngrok Kubernetes Operator and Gateway API resources to make the services you've deployed to Kubernetes available on the public internet.
Use this method if you:
- Want precise, Kubernetes-native control over routing behavior.
- Are building on a multi-team platform where the separation of concerns between the roles and personas (infrastructure provider, cluster operator, application developer) matters.
- Want to align with the Kubernetes community's vision for the future of ingress.
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 and a reserved domain
- 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 Gateway API custom resource definitions
You can select either the standard or experimental set of Gateway API CRDs depending on your preference. Either version will work with the ngrok Kubernetes Operator.
Loading…
After installing the Gateway API CRDs, create the following GatewayClass
so that you can mark which Gateway API resources the ngrok Operator should handle:
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. Get your domain
Head over to the Domains section and click + New Domain to grab a new domain.
You can choose between a static domain with an ngrok-branded TLD like .ngrok.app
or .ngrok.io
, or you can bring a custom domain.
We'll refer to this as $YOUR_DOMAIN
from here on out.
3. Deploy a sample service
If you don't already have an app to try out, try out this sample manifest, which installs our TinyLlama image onto your cluster.
Save the YAML below into a file named deployment.yaml
.
If you already have a deployment, you can skip this step, but you'll need to adapt the Operator configuration and test requests.
Loading…
Add the deployment and service to your cluster with kubectl
.
Loading…
4. Define your Gateway
and HTTPSRoute
resources
This manifest exposes the tinyllama
sample service on $YOUR_DOMAIN
.
If you already have a different deployment on your cluster, you'll need to change the backendRefs
name and port.
Loading…
Apply the manifest with kubectl apply -f gwapi.yaml
.
The ngrok Kubernetes Operator watches your cluster for Gateway
and HTTPRoute
resources that reference the ngrok
GatewayClass, and immediately provisions a new agent endpoint.
You can now send a request to $NGROK_DOMAIN
with your browser or curl
.
Your Kubernetes service is now available to anyone on the public internet.
4. Secure your app with Traffic Policy
In cases where you need to restrict access to your API or app, Traffic Policy and the restrict-ips
let you quickly allow only certain addresses to access your endpoint.
First, copy your public IP address via our ip4v.ngrok.com
mini-app.
To add the rule, create a new NgrokTrafficPolicy
resource and add it to your Gateway
resource as an annotation.
This way, the rule runs on all requests matching any of the hostnames from the listeners on your Gateway
.
Be sure to replace $YOUR_PUBLIC_IP
with the value you just copied.
Loading…
Re-apply the manifest with kubectl apply -f gwapi.yaml
.
You can also add Traffic Policy as an ExtensionRef
filter if you want to run certain rules only on a single route.
5. Start sending requests
You can now verify that your Kubernetes service is accessible from the public internet and that your Traffic Policy rules are in place.
If you deployed the tinyllama
service:
-
Chat with the LLM in your browser:
https://$YOUR_DOMAIN
-
Send a completions request to the API:
Loading…
What's next?
Learn more about using ngrok with your Kubernetes deployments:
- Read the guide to using Gateway API with ngrok
- Route requests to many upstream services based on the path, headers, and query parameters
- Explore TLS or TCP routing with Gateway API
- Deploy an API gateway in one or multiple clouds
For more ways to filter and manage traffic:
Finally, explore the Traffic Inspector in your dashboard for real-time observability of traffic flowing through your endpoint.