Kubernetes ingress to services hosted on EKS

This guide explains how to run the ngrok Kubernetes Operator on AWS EKS to add secure ingress to your services. The ngrok Kubernetes Operator is the official open-source controller for adding public and secure ingress traffic to your Kubernetes services. It works with an AWS EKS cluster as long as the cluster has outbound access to the ngrok service.

What you’ll need

An AWS EKS cluster reachable with kubectl. If you don’t have one, follow AWS’s Get started with Amazon EKS guide.
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. On a free account, this must be a static subdomain, which you can claim from the banner in your dashboard. Paid accounts can use a custom domain or a subdomain of ngrok.app or ngrok.dev.

Connect `kubectl` to your EKS cluster

Amazon EKS authenticates kubectl through the aws CLI. Confirm your kubectl context points at the cluster before continuing:

kubectl config current-context

If it doesn’t, follow AWS’s guide to connect kubectl to an EKS cluster, which walks through installing the aws CLI and running aws eks update-kubeconfig.

Install a sample application and Kubernetes ingress

Create a manifest file (for example ngrok-manifest.yaml) with the contents below. This deploys the tinyllama demo LLM application from ngrok-samples/tinyllama and an Ingress that tells the ngrok Kubernetes Operator to route traffic on your reserved domain to it. Replace NGROK_DOMAIN with the domain you reserved. This is the URL you’ll use to access your service from anywhere.

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
---
# Configuration for ngrok's Kubernetes Operator
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tinyllama-ingress
  namespace: default
spec:
  ingressClassName: ngrok
  rules:
    - host: NGROK_DOMAIN
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: tinyllama
                port:
                  number: 80

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://NGROK_DOMAIN) in a browser to confirm the tinyllama app is accessible from the internet.

Add security to your app

With the Traffic Policy system and the oauth action, ngrok manages OAuth protection entirely at ngrok. ngrok’s network authenticates and authorizes all requests before allowing ingress to your endpoint, so you don’t need to add any services to your cluster or alter any routes. To enable the oauth action, create a new NgrokTrafficPolicy custom resource and apply it to your entire 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. Edit your ngrok-manifest.yaml file with the following, 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.

General Guides

CLI Credentials

Dashboard SSO

Databases

Endpoints SSO

Event Destinations

Frameworks

JWT Validation