DEV Community

Cover image for Deploying Ngrok Ingress Controller on Kubernetes
Vultr profile image Sanskriti Harmukh
Sanskriti Harmukh for Vultr

Posted on with Aashish Chaurasiya • Originally published at docs.vultr.com

Deploying Ngrok Ingress Controller on Kubernetes

#devops #kubernetes #networking #security

Ngrok is a distributed reverse proxy that exposes applications to the internet via a masked external domain, without touching internal networking. The Ngrok Ingress Controller brings that model to Kubernetes as an Ingress-as-a-service: it connects your cluster to a static Ngrok domain and offloads traffic management, load balancing, TLS, and authentication to the Ngrok edge instead of the cluster. This guide installs the controller via Helm, deploys a sample app, exposes it through an Ingress resource on a static Ngrok domain, and secures it with GitHub OAuth. By the end, you'll have a cluster app reachable on the internet with no LoadBalancer service involved.

Prerequisite: An Ngrok account with a static domain configured (e.g. example.ngrok-free.app), a Kubernetes cluster (3+ nodes), kubectl configured, and Helm installed (sudo snap install helm --classic).

Install the Ngrok Ingress Controller

1. Generate an Ngrok API key and an AuthToken from your Ngrok dashboard, then export them:

$ export NGROK_AUTHTOKEN=YOUR_AUTHTOKEN
$ export NGROK_API_KEY=YOUR_API_KEY
Enter fullscreen mode Exit fullscreen mode

2. Add and update the Helm repo:

$ helm repo add ngrok https://ngrok.github.io/kubernetes-ingress-controller
$ helm repo update
Enter fullscreen mode Exit fullscreen mode

3. Install the controller:

$ helm install ngrok-ingress-controller ngrok/kubernetes-ingress-controller \
    --namespace ngrok-ingress-controller \
    --create-namespace \
    --set credentials.apiKey=$NGROK_API_KEY \
    --set credentials.authtoken=$NGROK_AUTHTOKEN
Enter fullscreen mode Exit fullscreen mode

4. Verify the deployment and pods:

$ kubectl get deploy -n ngrok-ingress-controller
$ kubectl get pods -n ngrok-ingress-controller
Enter fullscreen mode Exit fullscreen mode

Deploy a Sample Application

1. Save the deployment manifest:

$ nano game-deployment.yaml
Enter fullscreen mode Exit fullscreen mode 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-snake-game
  namespace: ngrok-ingress-controller
spec:
  replicas: 2
  selector:
    matchLabels:
      app: example-snake-game
  template:
    metadata:
      labels:
        app: example-snake-game
    spec:
      containers:
        - name: game-container
          image: thoschu/de.schulte360.web.snake
          ports:
            - name: http
              containerPort: 8080
Enter fullscreen mode Exit fullscreen mode 
$ kubectl apply -f game-deployment.yaml
Enter fullscreen mode Exit fullscreen mode

2. Save the Service manifest:

$ nano game-service.yaml
Enter fullscreen mode Exit fullscreen mode 
apiVersion: v1
kind: Service
metadata:
  name: example-game-service
  namespace: ngrok-ingress-controller
spec:
  ports:
    - name: http
      port: 8080
      targetPort: 8080
  selector:
    app: example-snake-game
Enter fullscreen mode Exit fullscreen mode 
$ kubectl apply -f game-service.yaml
Enter fullscreen mode Exit fullscreen mode

3. Confirm everything is running:

$ kubectl get deploy -n ngrok-ingress-controller
$ kubectl get pods -n ngrok-ingress-controller
$ kubectl get service -n ngrok-ingress-controller
Enter fullscreen mode Exit fullscreen mode

Configure the Ngrok Ingress

1. Save the Ingress manifest (replace example.ngrok-free.app with your domain):

$ nano app-ingress.yaml
Enter fullscreen mode Exit fullscreen mode 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-game-ingress
  namespace: ngrok-ingress-controller
spec:
  ingressClassName: ngrok
  rules:
    - host: example.ngrok-free.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-game-service
                port:
                  number: 8080
Enter fullscreen mode Exit fullscreen mode

2. Apply it and confirm the host is registered:

$ kubectl apply -f app-ingress.yaml
$ kubectl get ingress -n ngrok-ingress-controller
Enter fullscreen mode Exit fullscreen mode

The HOSTS column shows your Ngrok domain.

3. Check the edge in the Ngrok dashboard:

  • Edges → Cloud Edge — find the edge created by kubernetes-ingress-controller.
  • Click GLOBAL to see the backend Kubernetes endpoint mapping (k8s.ngrok.com/service=..., k8s.ngrok.com/port=8080).

4. Open the domain in a browser — the snake game loads through the Ngrok edge, no LoadBalancer service involved.

Secure the App with GitHub OAuth

Ngrok's edge supports OAuth, OpenID Connect, SAML, mutual TLS, and IP restrictions — all enforced before traffic reaches your cluster.

  1. In the Ngrok dashboard, open Edges → Cloud Edge, select the domain, and open Routes.
  2. Click OAuth → Begin setup.
  3. Pick GitHub as the Identity Provider, keep Use an ngrok-managed OAuth application enabled.
  4. Under Authorization, keep Restrict access to users that both authenticate and match a given set of rules.
  5. In Email Domains, enter the domain to allow (e.g. yourcompany.com), or list specific addresses under Email Addresses.
  6. Save the changes.
  7. Reload the app's domain — a GitHub sign-in page appears. Authorize the app; if your account matches the allowed domain/email, you land on the app.

Next Steps

The Ngrok Ingress Controller is routing traffic to your cluster with GitHub-gated access. From here you can:

  • Swap GitHub for Google, GitLab, Microsoft, SAML, or mutual TLS depending on your auth requirements
  • Route multiple services through the same domain using additional Ingress paths
  • Upgrade your Ngrok plan to use a custom domain instead of *.ngrok-free.app

For the full guide with additional tips, visit the original article on Vultr Docs.

Top comments (0)