Skip to main content
This guide walks you through launching a new Kubernetes cluster with Canonical’s open-source MicroK8s and using the ngrok Kubernetes Operator to securely ingress public traffic to an example app with the Kubernetes Gateway API. It covers the ngrok Kubernetes Operator, the Kubernetes Gateway API (a role-oriented mechanism for load-balancing and routing, well suited to organizations with defined roles for cluster vs application management), and Canonical MicroK8s (a low-ops, minimal, production-ready Kubernetes you can use for local development, CI, or IoT).

​
What you’ll need

  • MicroK8s installed locally.
  • 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>.

​
Deploy a Kubernetes cluster with MicroK8s

Start by deploying a new single-node MicroK8s Kubernetes cluster in your chosen environment. That could be your local workstation, an IoT device, a virtual machine in the cloud, or any system running one of the supported Linux flavors.
  • Follow the MicroK8s get-started tutorial to install the binary for your target system. Once MicroK8s is installed, it automatically deploys a single-node Kubernetes cluster.
  • Run microk8s status --wait-ready to check on the state of your MicroK8s cluster. 
    microk8s status --wait-ready

microk8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
...
    If you see microk8s is ready, your new cluster is ready.

​
Install an example app

Now you need a domain and Kubernetes service to ingress traffic to.
  • If you don’t have an ngrok static domain, create one. Navigate to the Domains section of the ngrok dashboard and click Create Domain or New Domain. This static domain, which will look like example.ngrok.app, will be your NGROK_DOMAIN for the remainder of this guide. Creating a subdomain on the ngrok network provides a public route to accept HTTP, HTTPS, and TLS traffic.
  • Create a new Kubernetes manifest (tinyllama.yaml) with the YAML below. This manifest defines the tinyllama demo LLM application from ngrok-samples/tinyllama (service and deployment), then configures the ngrok Kubernetes Operator to connect the tinyllama service to the ngrok edge via your NGROK_DOMAIN.
    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 tinyllama.yaml 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, you now need to configure the new Kubernetes Gateway API to route traffic arriving from outside the cluster 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 to specify how the Gateway should route requests.
  • Create a new file called gatewayclass.yaml on your workstation with the below 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 below YAML, replacing <YOUR_NGROK_DOMAIN>:
    showLineNumbers
    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tinyllama-gateway
  namespace: default
spec:
  gatewayClassName: ngrok
  listeners:
    - name: tinyllama-web
      protocol: HTTPS
      port: 80
      hostname: "<YOUR_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:
    - "<YOUR_NGROK_DOMAIN>"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: tinyllama
          kind: Service
          port: 80
    This YAML uses the Gateway API to first define a Gateway that allows north/south traffic to enter the cluster from external requests, then uses an HTTPRoute to terminate the connection at the pod running the tinyllama service.
  • Access your tinyllama demo app by navigating to your ngrok domain, for example, https://<YOUR_NGROK_DOMAIN>. ngrok’s network and the ngrok Kubernetes Operator route traffic to your app from any device or external network.

​
What’s next?

To track the development of the ngrok Kubernetes Operator and its use of the new Kubernetes Gateway API, check out the GitHub repository and give it a ⭐.