Kubernetes ingress to GKE services with ngrok

This guide shows you how to add public ingress to an app running on Google Kubernetes Engine (GKE). You’ll use the ngrok Kubernetes Operator to route public traffic to the app through an encrypted tunnel, then secure it with OAuth. The ngrok Kubernetes Operator is the official open source controller for adding public and secure ingress to your Kubernetes services. It works with a GKE cluster as long as the cluster has outbound access to the ngrok service.

What you’ll need

A GKE cluster. If you don’t have one, Google’s cluster creation guide covers provisioning one.
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>.

Connect kubectl to your GKE cluster

GKE authenticates kubectl through the gcloud CLI and the gke-gcloud-auth-plugin credential helper. Google’s cluster access guide covers installing the plugin and configuring cluster access. Once you’re authenticated, add the cluster to your KUBECONFIG:

gcloud container clusters get-credentials --region <cluster-region> --project <cluster-project> <cluster-name>

Confirm kubectl can reach the cluster before continuing:

kubectl get nodes

Install the ngrok Kubernetes Operator

If you haven’t already, install the operator with Helm. See the Kubernetes ingress quickstart for the steps and how to pass your ngrok credentials.

Install a sample application

Create a manifest file (for example, ngrok-manifest.yaml) with the following contents. This deploys the tinyllama demo LLM application. Replace <NGROK_DOMAIN> in the highlighted section with your reserved domain. On a free account, use a static subdomain; on a paid account, you can use a custom domain or a subdomain of ngrok.app or ngrok.dev.

The first section creates the tinyllama demo app Service and Deployment; the highlighted section configures the ngrok Kubernetes Operator Ingress.

showLineNumbers

apiVersion: v1
kind: Service
metadata:
  name: tinyllama
spec:
  ports:
    - name: http
      port: 80
      targetPort: 8080
  selector:
    app: tinyllama
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tinyllama
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
---
# highlight-start
# ngrok Kubernetes Operator Configuration
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tinyllama-ingress
spec:
  ingressClassName: ngrok
  rules:
    - host: <NGROK_DOMAIN>
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: tinyllama
                port:
                  number: 80
# highlight-end

Apply the manifest file to your cluster:

kubectl apply -f ngrok-manifest.yaml

Troubleshooting: If you get an error when applying the manifest, double-check that you’ve updated the <NGROK_DOMAIN> value and try again.

Open your reserved domain (for example, https://my-awesome-k8s-cluster.ngrok.app) in a browser to confirm the tinyllama app is accessible from the internet.

Add authentication to your app

With the Traffic Policy system and the oauth action, ngrok handles OAuth entirely on its network. You don’t need to add services to your cluster or change any routes, because ngrok authenticates and authorizes requests before they reach your endpoint. To enable the oauth action, create an NgrokTrafficPolicy custom resource and apply it to your Ingress with an annotation. You can also apply the policy to a specific backend or as the default backend for an Ingress. See the doc on using the Operator with Ingresses for details. Edit your existing ngrok-manifest.yaml, leaving the Service and Deployment as they were. Note the new annotations field and the NgrokTrafficPolicy CR.

...
---
# Configuration for ngrok's Kubernetes Operator
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tinyllama-ingress
  namespace: default
  annotations:
    k8s.ngrok.com/traffic-policy: oauth
spec:
  ingressClassName: ngrok
  rules:
    - host: <NGROK_DOMAIN>
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: tinyllama
                port:
                  number: 80
---
# Traffic Policy configuration for OAuth
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
  name: oauth
  namespace: default
spec:
  policy:
    on_http_request:
      - type: oauth
        config:
          provider: google

Re-apply your ngrok-manifest.yaml configuration:

kubectl apply -f ngrok-manifest.yaml

When you open your demo app again, ngrok asks you to log in with Google. To limit access to just yourself or your colleagues, tighten the policy. Use expressions and CEL interpolation to reject OAuth logins that aren’t under example.com. Update the NgrokTrafficPolicy portion of your manifest after changing example.com to your domain.

# Traffic Policy configuration for OAuth
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
  name: oauth
  namespace: default
spec:
  policy:
    on_http_request:
      - type: oauth
        config:
          provider: google
      - expressions:
          - "!actions.ngrok.oauth.identity.email.endsWith('@example.com')"
        actions:
          - type: custom-response
            config:
              body: You are not authorized, ${actions.ngrok.oauth.identity.name}.
              status_code: 400

Check your deployed tinyllama app again. If you log in with an email that isn’t under your domain, ngrok rejects the request.

What’s next?

You’ve used the open source ngrok Kubernetes Operator to add public ingress to an app on GKE without managing complex Kubernetes networking. 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