Skip to main content

Quickstart: Kubernetes Custom Resources

This quickstart uses the ngrok Kubernetes Operator and ngrok's custom resources (CRs) to make the services you've deployed to Kubernetes available on the public internet.

Use this method if you:

  • Want the easiest path, requiring the least amount of YAML, to create for your resources compared to Ingress or Gateway API resources.
  • Are okay with using Kubernetes-native resources, but not necessarily following Kubernetes standards.
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 and a reserved domain
  • 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. 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. Create your endpoint manifest​

You have two options to expose your Kubernetes service with ngrok's CRDs. The primary two types are CloudEndpoint and AgentEndpoint.

  1. A single AgentEndpoint resource: This option is simplest, but is typically limited to exposing one service on a hostname.
  2. A pair of CloudEndpoint and AgentEndpoint resources: This option allows you to route traffic to any number of Kubernetes services from a single hostname depending on their path, headers, and more using expressions and the forward-internal Traffic Policy action.

When using other types of configuration with the operator such as Ingress and resources, the operator translates all of them into CloudEndpoint and AgentEndpoint resources. Using the CloudEndpoint/AgentEndpoint resources directly gives you maximum control over your ngrok operator configuration. For more information about cloud and agent endpoints, see the endpoint types page.

This manifest exposes a Kubernetes service named tinyllama listening on port 80 on $YOUR_DOMAIN. If you already have a different deployment on your cluster, you'll need to change the backend service name and port.

Loading…

Apply the manifest with kubectl apply -f ngrok-crds.yaml.

The ngrok Kubernetes Operator watches your cluster for AgentEndpoint and CloudEndpoint resources you create, and provisions a new agent endpoint to forward traffic into your Service.

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.

Add a trafficPolicy.inline field followed by the rule itself.

Loading…

Re-apply the manifest with kubectl apply -f gwapi.yaml.

5. Start sending requests​

You can now verify that your Kubernetes service is accessible from the public internet and that your 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:

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.