Using ngrok with Kubernetes

Introduction

The ngrok Ingress Controller for Kubernetes is our official open-source controller for adding public and secure ingress traffic to your k8s services. You can think of the ngrok Ingress Controller as ngrok packaged as an idiomatic k8s controller — deployed via a simple helm chart, configurable via standard k8s Ingress object (using the kind: Ingress construct), and compatible with k8s best practices.

In this tutorial, you will install the ngrok Ingress Controller and run a sample 2048 app with public access and security provided by ngrok.

This tutorial requires:

1. A local environment with Kubernetes installed and configured. For this tutorial, we will use k3d, kubectl, and helm, but you can also use minikube if you'd like.
2. A free ngrok account.

Get started with the ngrok Ingress Controller for Kubernetes

Step 1: Get your ngrok authtoken and API key

tip

The ngrok Ingress Controller requires:

• An ngrok authtoken to launch connections between ngrok's points of presence and your k8s cluster. You can find your authtoken in the ngrok dashboard under "Your Authtoken".
• An ngrok API key to create and configure the ngrok edges for your services. You can generate an API key in the ngrok Dashboard under "API".

To started with the ngrok Ingress Controller for Kubernetes:

1. Access the ngrok Dashboard
2. Click Your Authtoken. Copy the Authtoken to a text editor.
3. Click API and follow the instructions to create a new API key. Copy the API key to a text editor.
4. Click Cloud Edge > Domains and register or claim a domain. Save this value, you will need it later. This is the URL you will use to access your service from anywhere.

Step 2: Setup your Kubernetes cluster and install the ngrok Ingress Controller

1. In your terminal, create a k8s cluster:

   k3d cluster create ngrok

2. Using helm, add the ngrok repo:

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

3. Set your environment variables with your ngrok credentials. Replace [AUTHTOKEN] and [API_KEY] with your Authtoken and API key from above.

   export NGROK_AUTHTOKEN=[AUTHTOKEN]
   export NGROK_API_KEY=[API_KEY]

4. Install the ngrok Ingress Controller in your cluster, replacing [AUTHTOKEN] and [API_KEY] with your Authtoken and API key from above:

   Note: For this tutorial, we're creating and using the namespace ngrok-ingress-controller.

   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

5. Create a manifest file (for example ngrok-manifest.yaml) with the following contents. You will need to replace the NGROK_DOMAIN on line 45 with the domain you registered in Step 1.

Notes:

• Lines 1-34: Create the 2048 app service and deployment
• Lines 35-54 (highlighted): Create the ngrok Ingress Controller. Line 45 determines the ingress URL for public requests.

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
---
# ngrok Ingress Controller Configuration
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: game-2048-ingress
  namespace: ngrok-ingress-controller
spec:
  ingressClassName: ngrok
  rules:
    - host: NGROK_DOMAIN
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: game-2048
                port:
                  number: 80

1. Apply the manifest file to your k8s cluster.

   kubectl apply -f ngrok-manifest.yaml

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

2. To confirm the manifest is successfully applied, go to the ngrok Dashboard and click Edge Configurations. You should see a new Edge Configuration for your cluster with the name matching your URL (1) — for example: my-awesome-k8s-cluster.ngrok.app. Also note that your some of your cluster configurations are presented int the dashboard as annotations (2).

   

3. Access your ingress URL using the subdomain you chose in the manifest file above (i.e. https://my-awesome-k8s-cluster.ngrok.app) to confirm the 2048 app is accessible from the internet. If you forgot what url you chose, you can always run kubectl get ingresses --namespace=ngrok-ingress-controller to see what it is.

   

Step 3: Add edge security to your app

The ngrok Ingress Controller for Kubernetes provides custom resource definitions (CRDs) for additional edge features available in ngrok. In this example, we're expanding the Ingress Controller with Google OAuth to allow access only from users with the email domains @acme.com or @ngrok.com and to apply a circuit breaker to your app at 80% (requires a paid account). These features are enforced at the ngrok edge, ensuring only authorized users can access your app.

As before, you will need to update line 46 of this manifest with your NGROK_DOMAIN in the Ingress object.

Notes:

This example is very similar to the previous version, with the following changes:

• Lines 41-42: Associates your Ingress Controller with the configuration oauth-and-circuit-breaking via annotation
• Lines 57-75: Sets the edge configuration as a custom CRD (NgrokModuleSet).
• Lines 64-69: Sets the circuit breaker module over 50% threshold.
• Lines 70-74: Sets the OAuth module to allow access only for users with the email domains @acme.com or @ngrok.com.

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
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: game-2048-ingress
  namespace: ngrok-ingress-controller
  annotations:
    k8s.ngrok.com/modules: oauth-and-circuit-breaking
spec:
  ingressClassName: ngrok
  rules:
    - host: NGROK_DOMAIN
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: game-2048
                port:
                  number: 80
---
# Module configurations for Circuit Breaking and OAuth
kind: NgrokModuleSet
apiVersion: ingress.k8s.ngrok.com/v1alpha1
metadata:
  name: oauth-and-circuit-breaking
  namespace: ngrok-ingress-controller
modules:
  circuitBreaker:
    trippedDuration: 10s
    rollingWindow: 10s
    numBuckets: 10
    volumeThreshold: 20
    errorThresholdPercentage: "0.50"
  oauth:
    google:
      emailDomains:
        - acme.com
        - ngrok.com
---

1. Save your file and reapply the manifest file:

   kubectl apply -f ngrok-manifest.yaml

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

2. To confirm the circuit breaking configuration is successfully applied:

   1. Go to ngrok Dashboard > Edge Configurations.

   2. Click the edge configuration that matches your URL.

   3. On the left hand side, click Circuit Breaker.

   4. Notice how the circuit breaker configuration matches your manifest file.

      

   5. Click OAuth and confirm how the oauth configuration matches your manifest file.

      

3. Access your App and confirm that you got the expect authentication behavior: