Introducing the ngrok Ingress Controller for Kubernetes

Today, we're excited to announce the ngrok Ingress Controller for Kubernetes (K8s), our open-source controller for adding public and secure ingress traffic to your K8s services. If you’ve used ngrok in the past, you can think of the ingress controller as the ngrok agent built as an idiomatic K8s resource — available as a helm chart, configurable via K8s manifests, scalable for production usage, and leveraging Kubernetes best practices. The ngrok ingress controller is open-source, with docs available on GitHub, and a getting started guide in ngrok docs.

The ngrok Ingress Controller for Kubernetes lets developers define public and secure ingress traffic (north-to-south traffic) to their K8s resources directly from the deployment manifest, without configuring low-level network primitives — like DNS, IPs, NAT, and VPCs — outside of their K8s cluster! This makes it easy to add global traffic with security and scalability into K8s resources regardless of the underlying network infrastructure. 

Check out how easy it is to add ngrok to your K8s configuration:

apiVersion: v1
kind: Service
metadata:
name: game-2048
spec:
ports:
  - name: http
    port: 80
    targetPort: 80
selector:
  app: game-2048
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: game-2048
spec:
replicas: 1
selector:
  matchLabels:
  app: game-2048
template:
  metadata:
  labels:
    app: game-2048
  spec:
  containers:
    - name: backend
      image: alexwhen/docker-2048
      ports:
        - name: http
          containerPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: game-2048-ingress
spec:
  # Ingress on ngrok
  ingressClassName: ngrok
  rules:
    - host: myapp.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
              name: game-2048
              port:
                number: 80
  # Ingress on localhost:80
  # rules:
  #   - host: example.localhost
  #     http:
  #       paths:
  #       - path: /
  #         pathType: Prefix
  #         backend:
  #           service:
  #           name: game-2048
  #           port:
  #             number: 80 

Install the ngrok helm repo and chart, set your ngrok authtoken and key, and apply your manifest:

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

# install the ngrok ingress controller
export NGROK_API_KEY=[YOUR Secret API KEY]
export NGROK_AUTHTOKEN=[YOUR Secret Auth Token]

helm repo add ngrok https://ngrok.github.io/kubernetes-ingress-controller
helm install ngrok-ingress-controller ngrok/kubernetes-ingress-controller \
    --set credentials.apiKey=$NGROK_API_KEY \
    --set credentials.authtoken=$NGROK_AUTHTOKEN

# apply the manifest
kubectl apply -f ngrok-manifest.yaml

The service is assigned the URL pre-defined in the configuration (<code>https://myapp.ngrok.app</code>) and is ready to receive internet requests! No DNS, NAT, Public IPs, or configuration or network provisioning is required.

How the ngrok ingress controller works

The K8s cluster in our example gets inbound internet access without Public IP, VPCs, NATs, or DNS, how is that possible? When you launch your cluster, the ngrok ingress controller initiates a secure and persistent outbound TLS connection to ngrok’s ingress-as-a-service platform and transmits the configuration from your manifest — i.e. domain, authentication, webhook verification, and IP restrictions. The ngrok service sets up your configuration across all of our global points of presence, giving you north-to-south traffic in seconds, and returns a URL for your cluster.

After your ingress is up and running, ngrok receives HTTP requests at the closest region to the requester and enforces the middleware policies defined by your application. Unauthorized requests are blocked at the edge and only valid requests reach your cluster via the persistent TLS connection:

Why we built the ngrok ingress controller

Network should be a high-level abstraction

Provisioning public and secure ingress (north-to-south traffic) for K8s clusters is a frustrating exercise of wrangling a slew of disparate low-level networking primitives. While Service Mesh solutions handle traffic inside cluster (east-to-west) well, developers must provision and manage a number of technologies to get traffic outside of the cluster right. That includes different layers of the network stack like DNS, Public IPs, TLS certificates, network-level CIDR policies, IP and subnet routing, load balancing, VPNs and NATs. In short, outside of the cluster, developers are still being forced to work with the assembly language of networking.

We built the ngrok ingress controller to let developers declare these network primitives from inside the cluster, at a high layer of abstraction, and without sacrificing on service security and resiliency. As an example, here’s how the ngrok ingress controller allows developers to specify OAuth authentication, IP restrictions, and circuit breaking with just a few extra lines, removing the burden of integrating other systems manually:

---
    kind: Ingress
    metadata:
     name: example
     annotations:
       k8s.ngrok.com/modules: "configs"
    spec:
     ingressClassName: ngrok
     rules:
     - host: my-app.ngrok.io
       http:
         paths:
         - path: /
           pathType: Prefix
           backend:
             service:
               name: service
               port:
                 number: 8080
    ---
    kind: NgrokModuleSet
    apiVersion: ingress.k8s.ngrok.com/v1alpha1
    metadata:
     name: configs
    modules:
     compression:
       enabled: true
     ipRestriction:
       policies: ips-to-blocklist
     circuitBreaker:
       trippedDuration: 10s
       rollingWindow: 10s
       numBuckets: 10
       volumeThreshold: 20
       errorThresholdPercentage: "0.50"
     oauth:
       google:
         emailDomains:
         - my-domain.com
    ---
    kind: IPPolicy
    apiVersion: ingress.k8s.ngrok.com/v1alpha1
    metadata:
     name: ips-to-blocklist
    spec:
     description: "Trusted IPs"
     rules:
     - action: "allow"
       cidr: 1.2.3.4/32
       description: "My Home IP"
    apiVersion: networking.k8s.io/v1

A complete list of supported modules and configurations can be found in the ngrok ingress controller reference.

North-to-south traffic should be environment-independent

Traditionally, north-to-south traffic is tightly coupled to the environment where your app is deployed. For example, the same K8s cluster deployed to your own datacenter, an EC2 instance, or a GKE environment requires wildly different configurations of DNS, NAT, VPC, and Public IPs policies to operate. Running your app in those three different environments means you need to provision and manage north-to-south ingress in three different ways.

ngrok-rs decouples your cluster north-to-south configuration from the environment where it runs.

When your cluster uses the ngrok ingress controller, you can run it anywhere and it will receive public and secure traffic the same way. From an ingress standpoint, your cluster becomes portable: it does not matter whether it runs directly on bare metal, layered on top of VMs, using k3s, AWS EKS, or Azure, or on k3d in your laptop.

North-to-south traffic shouldn’t require sidecars

Developers often distribute the ngrok agent alongside their own k8s clusters to create ingress for their IoT devices, SaaS offerings, and CI/CD pipelines. It can be challenging to bundle the ngrok agent as a sidecar to the cluster, with configurations living outside the deployment manifest. The ngrok ingress controller eliminates the agent, simplifying distribution and management as well as enabling developers to easily deliver private label experiences.

How we designed the ngrok ingress controller

We designed the ngrok Ingress Controller with the goal of integrating seamlessly into the Kubernetes ecosystem and best practices:

• Idiomatic API with configuration using the existing K8s Ingress spec (<code>kind: Ingress</code>)
• Leverages ngrok-go to embed ngrok directly into the controller with less process overhead and without a statically defined configuration file‍
• Supports multiple connections and policies per ingress from the same controller — you can define multiple ingress hosts and routes with specific configurations, availability, and security policies
• Integrates with the K8s ecosystem, so you can connect ngrok to the K8s services you already use, such as secret management, Open Policy Agent (OPA), and observability.

We validated the ngrok ingress controller design by collecting feedback from the community and fellow infrastructure engineers on our design and ergonomics.

Get started

To get started, try our getting started with the ngrok ingress controller guide. For additional information,  visit the ngrok ingress controller docs and check the open sourced ngrok ingress controller repo on GitHub.

‍