Kubernetes ingress to apps/APIs on clusters managed by Canonical MicroK8s

This guide shows you how to add public ingress to an app running on a Canonical MicroK8s cluster. You’ll use the ngrok Kubernetes Operator with the Kubernetes Gateway API to route public traffic to the app through an encrypted tunnel.

What you’ll need

A MicroK8s cluster reachable with kubectl. If you don’t have one, Canonical’s MicroK8s get-started guide covers installing it.
An ngrok account.
kubectl and Helm 3.0.0+ installed on your local workstation.
The ngrok Kubernetes Operator installed on your cluster.
A reserved domain from the ngrok dashboard or API; this guide refers to it as NGROK_DOMAIN.

Set up your MicroK8s cluster

This guide assumes a single-node MicroK8s cluster reachable with kubectl. MicroK8s runs on your local workstation, an IoT device, a virtual machine in the cloud, or any system running one of the supported Linux flavors. If you don’t have a cluster yet, follow Canonical’s MicroK8s get-started guide to install the binary for your target system. MicroK8s deploys a single-node Kubernetes cluster automatically. Confirm your cluster is ready before continuing:

microk8s status --wait-ready

If you see microk8s is running, your cluster is ready.

Install an example app

Deploy the demo app you’ll expose through ngrok. Create a new Kubernetes manifest (tinyllama.yaml) with the YAML below. This manifest defines the tinyllama demo LLM application from ngrok-samples/tinyllama as a service and deployment.

showLineNumbers

apiVersion: v1
kind: Service
metadata:
  name: tinyllama
  namespace: default
spec:
  ports:
    - name: http
      port: 80
      targetPort: 8080
  selector:
    app: tinyllama
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tinyllama
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tinyllama
  template:
    metadata:
      labels:
        app: tinyllama
    spec:
      containers:
        - name: tinyllama
          image: ghcr.io/ngrok-samples/tinyllama:main
          ports:
            - name: http
              containerPort: 8080

Apply the manifest to your MicroK8s cluster:

kubectl apply -f tinyllama.yaml

Configure the ngrok Kubernetes Operator

With your example app running alongside the ngrok Kubernetes Operator, configure the Kubernetes Gateway API to route traffic arriving on NGROK_DOMAIN to the tinyllama service. First you’ll create a GatewayClass, which represents a class of cluster-level Gateways. Then you’ll configure the Gateway with a listener and an HTTPRoute that specifies how the Gateway routes requests.

Create a new file called gatewayclass.yaml on your workstation with the following YAML:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: ngrok
spec:
  controllerName: ngrok.com/gateway-controller

Install the GatewayClass:
kubectl apply -f gatewayclass.yaml

Create a new file named tinyllama-gateway.yaml on your workstation with the following YAML, replacing NGROK_DOMAIN with the domain you reserved:

showLineNumbers

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tinyllama-gateway
  namespace: default
spec:
  gatewayClassName: ngrok
  listeners:
    - name: tinyllama-web
      protocol: HTTP
      port: 80
      hostname: "NGROK_DOMAIN"
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tinyllama-route
  namespace: default
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: tinyllama-gateway
      namespace: default
  hostnames:
    - "NGROK_DOMAIN"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: tinyllama
          kind: Service
          port: 80

The Gateway allows north/south traffic to enter the cluster from external requests, and the HTTPRoute terminates the connection at the pod running the tinyllama service.

Apply the Gateway and HTTPRoute:

kubectl apply -f tinyllama-gateway.yaml

Access your tinyllama demo app by navigating to your ngrok domain, for example, https://NGROK_DOMAIN. ngrok’s network and the ngrok Kubernetes Operator route traffic to your app from any device or external network.

What’s next?

You’ve used the open source ngrok Kubernetes Operator to add public ingress to an app on MicroK8s with the Kubernetes Gateway API. Because ngrok handles ingress and middleware execution, you can follow the same process for your production apps. To go further, explore the Kubernetes docs for how the Operator works and how to integrate ngrok with an existing production cluster, or try bindings and endpoint pooling.

General Guides

CLI Credentials

Dashboard SSO

Databases

Endpoints SSO

Event Destinations

Frameworks

JWT Validation