Skip to main content

Ingress to Kubernetes apps on clusters managed by Canonical MicroK8s

TL;DR

To use the ngrok Kubernetes Operator, which now supports the Kubernetes Gateway API spec, with Canonical MicroK8s:

  1. Deploy a Kubernetes cluster with MicroK8s
  2. Deploy the ngrok Kubernetes Operator
  3. Install an example app
  4. Configure the ngrok Operator

Using this guide, you'll launch a new Kubernetes cluster with Canonical's open-source MicroK8s and use the ngrok Kubernetes Operator to securely ingress public traffic to an example app using the new Kubernetes Gateway API.

Along the way, you'll learn enough to leverage MicroK8s in your next Kubernetes deployment—local development, embedded in a CI environment, and production workloads—with simple and secure traffic ingress.

Here is what you'll be building with:

  • The ngrok Kubernetes Operator: ngrok's official controller for adding secure public ingress and middleware execution to your Kubernetes apps with ngrok's Cloud Edge. With ngrok, you can manage and secure app traffic at every stage of the development lifecycle while benefiting from simpler configurations, security, and edge acceleration.
  • The Kubernetes Gateway API: This new API, which made generally available in October 2023, is a role-oriented mechanism for provisioning load-balancing infrastructure and routing traffic. The Gateway API does not replace "traditional" Ingress Controllers—both are available for production usage, but the Gateway API may be better suited for large organizations with defined roles for managing Kubernetes services, cluster operators vs. application developers.
  • Canonical MicroK8s: An open-source system for low-ops, minimal, production-ready Kubernetes. MicroK8s' single-node configuration, small size, and customizeable footprint lets you use it for local development, in minimal environments like GitHub's CI/CD, or using Kubernetes on IoT hardware.
This how-to guide requires:
  1. An ngrok account at any tier.
  2. MicroK8s installed locally.
  3. kubectl installed locally.
  4. Helm 3.0.0+ installed locally.

Step 1: 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 42 supported flavors of Linux.

  1. Follow the get started tutorial for MicroK8s to install the binary for your target system.

    Once Microk8s is installed, it automatically deploys a single-node Kubernetes cluster.

  2. 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 to go!

Step 2: Deploy the ngrok Kubernetes Operator​

Now that you have a Kubernetes cluster deployed using MicroK8s, you can install the ngrok Kubernetes Operator for secure ingress.

  1. Add the Helm repository:

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

  2. Install the latest Gateway API CRDs to your cluster:

    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml

  3. Set up the AUTHTOKEN and API_KEY exports, which allows Helm to install the Ingress Controller using your ngrok credentials. Find your AUTHTOKEN under Your Authtoken in the ngrok dashboard.

    To create a new API key, navigate to the API section of the ngrok dashboard, click the New API Key button, change the description or owner, and click the Add API Key button. Copy the API key token shown in the modal window before closing it, as the ngrok dashboard will not show you the token again.

    export NGROK_AUTHTOKEN=[YOUR-AUTHTOKEN]
    export NGROK_API_KEY=[YOUR-API-KEY]

  4. Install the ngrok Ingress Controller with Helm under a new ngrok-ingress-controller namespace, with the useExperimentalGatewayApi=true option.

    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 \
      --set useExperimentalGatewayApi=true

  5. Verify you have installed the ngrok Kubernetes Operator successfully via a single running pod.

    kubectl get pods --namespace ngrok-ingress-controller

    NAME                                                              READY   STATUS    RESTARTS   AGE
    ngrok-ingress-controller-kubernetes-ingress-controller-man2fg5p   1/1     Running   0          2m23s

Step 3: Install an example app​

Now you need a domain and Kubernetes service to ingress traffic to!

  1. 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.

  2. Create a new Kubernetes manifest (2048.yaml) with the YAML below. This manifest defines the 2048 application service and deployment, then configures the ngrok Kubernetes Operator to connect the game-2048 service to the ngrok edge via your NGROK_DOMAIN.

    apiVersion: v1
    kind: Service
    metadata:
      name: game-2048
      namespace: ngrok-ingress-controller
    spec:
      ports:
        - name: http
          port: 80
          targetPort: 80
      selector:
        app: game-2048
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: game-2048
      namespace: ngrok-ingress-controller
    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

  3. Apply the 2048.yaml manifest to your MicroK8s cluster.

    kubectl apply -f 2048.yaml

Step 4: 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 game-2048 service.

You'll first create a GatewayClass, which represents a class of cluster-level Gateways. You'll then configure the Gateway with a listener, and an HTTPRoute to specify how the Gateway should route requests.

  1. 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

  2. Install the GatewayClass:

    kubectl apply -f gatewayclass.yaml

  3. Create a new file named 2048-gateway.yaml on your workstation with the below YAML:

    tip

    Make sure you edit L10 and L37 to replace the NGROK_DOMAIN variable with the domain you created before.

    apiVersion: gateway.networking.k8s.io/v1
    kind: Gateway
    metadata:
      name: 2048-gateway
      namespace: ngrok-ingress-controller
    spec:
      gatewayClassName: ngrok
      listeners:
        - name: 2048-web
          hostname: "NGROK_DOMAIN"
          port: 80
          protocol: HTTPS
          tls:
            mode: Terminate
            certificateRefs:
              - name: ngrokcert #ngrok will generate the cert so this cert does not be defined and will be ignored if defined
          allowedRoutes:
            kinds:
              - kind: HTTPRoute
            namespaces:
              from: Selector
              selector:
                matchLabels:
                  expose-apps: "true"
    ---
    apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: 2048-route
      namespace: ngrok-ingress-controller
    spec:
      parentRefs:
        - kind: Gateway
          name: 2048-gateway
          namespace: ngrok-ingress-controller
      hostnames:
        - "NGROK_DOMAIN"
      rules:
        - matches:
            - path:
                type: PathPrefix
                value: /
          backendRefs:
            - name: game-2048
              kind: Service
              port: 80
    tip

    Note: If you get an error when applying the manifest, double check that you've updated the NGROK_DOMAIN value and try again.

    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 game-2048 service.

  4. Access your 2048 demo app by navigating to your ngrok domain, e.g. https://NGROK_DOMAIN. ngrok's Cloud Edge and the ngrok Kubernetes Operator routes traffic to your app from any device or external network.

What's next?​

Because the ngrok Kubernetes Operator's use of the Gateway API is still experimental, not all the same features are available compared to the traditional Ingress CRD method. However, the Kubernetes API is the new standard API for routing traffic, you'll benefit from starting from a more recent foundation in favor of a later migration.

Certain modifications, like changing headers and redirecting traffic based on paths, are currently supported.

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 ⭐.