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. MicroK8s runs on a local workstation, an IoT device, a cloud virtual machine, 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.
An ngrok account.
kubectl installed on your local workstation.
The ngrok Kubernetes Operator installed on your cluster, along with the Gateway API CRDs.
A reserved domain from the ngrok dashboard or API; this guide refers to it as NGROK_DOMAIN.

Confirm your cluster is ready

Check that MicroK8s is running before you deploy anything:

microk8s status --wait-ready

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

Deploy an example app

Create a manifest named tinyllama.yaml with the following YAML. It defines a service and deployment for the tinyllama demo LLM app.

tinyllama.yaml 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 cluster:

kubectl apply -f tinyllama.yaml

Create a GatewayClass

A GatewayClass tells Kubernetes which controller manages your Gateways. This one assigns them to the ngrok Kubernetes Operator.Create a file named gatewayclass.yaml with the following YAML:

gatewayclass.yaml

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

Apply it to your cluster:

kubectl apply -f gatewayclass.yaml

Route traffic to the app

The Gateway listens for requests to NGROK_DOMAIN, and the HTTPRoute sends those requests to the tinyllama service.Create a file named tinyllama-gateway.yaml with the following YAML, replacing NGROK_DOMAIN with your reserved domain:

tinyllama-gateway.yaml 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

Apply the Gateway and HTTPRoute:

kubectl apply -f tinyllama-gateway.yaml

Test your app

Open https://NGROK_DOMAIN in a browser. The ngrok Kubernetes Operator routes the request from ngrok’s network to the tinyllama service, so you can reach the app from any device or 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