Deploying Ngrok Ingress Controller on Kubernetes

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.

Prerequisites

• An Ngrok account with a static domain configured (e.g., example.ngrok-free.app)
• A Kubernetes cluster (3+ nodes)
• kubectl configured
• 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
   

2. Add and update the Helm repo:

   helm repo add ngrok https://ngrok.github.io/kubernetes-ingress-controller
   helm repo update
   

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
   

4. Verify the deployment and pods:

   kubectl get deploy -n ngrok-ingress-controller
   kubectl get pods -n ngrok-ingress-controller
   

Deploy a Sample Application

1. Save the deployment manifest:

   nano game-deployment.yaml
   

   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
   

   kubectl apply -f game-deployment.yaml
   

2. Save the Service manifest:

   nano game-service.yaml
   

   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
   

   kubectl apply -f game-service.yaml
   

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
   

Configure the Ngrok Ingress

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

   nano app-ingress.yaml
   

   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
   

2. Apply it and confirm the host is registered:

   kubectl apply -f app-ingress.yaml
   kubectl get ingress -n ngrok-ingress-controller
   

   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.

• In the Ngrok dashboard, open Edges → Cloud Edge, select the domain, and open Routes.
• Click OAuth → Begin setup.
• Pick GitHub as the Identity Provider, keep Use an ngrok-managed OAuth application enabled.
• Under Authorization, keep Restrict access to users that both authenticate and match a given set of rules.
• In Email Domains, enter the domain to allow (e.g., yourcompany.com), or list specific addresses under Email Addresses.
• Save the changes.
• 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.