Skip to main content

Quickstart: Kubernetes Operator

This quickstart will use the ngrok Kubernetes Operator to put an application running on a Kubernetes Cluster on the internet and add some basic policies.

What is the ngrok Kubernetes Operator?​

The ngrok Kubernetes Operator is the best way to use ngrok if your applications run as services in a Kubernetes cluster. Key benefits of the operator include:

  • Easy Installation: The Operator can be easily installed on a cluster via Helm and is compatible with the latest versions of Kubernetes.
  • Broad Support: The Operator supports both Ingress CRDs and the new Gateway API using the same installation.
  • Developer Self-Service: Once deployed, the Operator enables developers to self-service public endpoints for their apps and services using a shared ngrok account.
  • Resource Management: The Operator manages the creation of ngrok resources, allowing developers to focus on traffic and routing patterns.
  • Advanced Configuration: The Operator supports the configuration of resources like custom domains, modules, and policies.
  • Cloud Benefits: The Operator supports all the cloud benefits of ngrok, including our global points of presence, GSLB, and traffic inspector.

Step 1: Install Kubernetes Operator​

Installing the ngrok Operator is easy using Helm.

Add the ngrok Kubernetes Operator repo to Helm:

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

Install the ngrok Kubernetes Operator:

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

helm install ngrok-ingress-controller ngrok/kubernetes-ingress-controller \
  --namespace $NAMESPACE \
  --create-namespace \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN

Step 2: Connect Your Service To An Edge​

This would create an Edge on with the Domain example.ngrok.app that routes traffic to the Kubernetes service example-service running on port 80.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    k8s.ngrok.com/modules: ngrok-module-set
spec:
  ingressClassName: ngrok
  rules:
    - host: example.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Step 3: Route Traffic Based On A Path​

This would create an Edge on with the Domain example.ngrok.app that routes traffic from example.ngrok.app/foo to the Kubernetes service example-service running on port 80.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    k8s.ngrok.com/modules: ngrok-module-set
spec:
  ingressClassName: ngrok
  rules:
    - host: example.ngrok.app
      http:
        paths:
          - path: /foo
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Step 4: Modify Headers For Incoming Requests​

kind: NgrokModuleSet
apiVersion: ingress.k8s.ngrok.com/v1alpha1
metadata:
  name: ngrok-module-set
modules:
  headers:
    request:
      add:
        is-ngrok: "1"
        country: "${conn.geo.country_code}"
      remove: ["referrer"]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    k8s.ngrok.com/modules: ngrok-module-set
spec:
  ingressClassName: ngrok
  rules:
    - host: your-domain.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Step 5: Redirect Traffic​

note

Redirects are not yet supported with the Kubernetes Ingress Controller.

Next Steps​