Skip to main content

Kubernetes Operator

Overview​

The ngrok Kubernetes Operator is the best way to use ngrok if your applications run in Kubernetes environments. It supports both Ingress CRDs as well as the new Gateway API.

The ngrok Kubernetes Operator is deployed to a cluster and allows developers to self-service public endpoints to their apps and services using a shared ngrok account.

The operator watches for Kubernetes objects and creates the corresponding ngrok endpoints and configurations.

More details on how these are derived can be found here.

Other ngrok features such as TCP Edges can be configured via CRDs.

If you are looking to install the controller for the first time, see our deployment-guide. If it's already installed and you are looking to configure ingress for an app or service, see our user-guide.

Install​

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

Example Usage​

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

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

Modify Headers​

kind: NgrokModuleSet
apiVersion: ingress.k8s.ngrok.com/v1alpha1
metadata:
  name: ngrok-module-set
modules:
  headers:
    request:
      add:
        is-ngrok: "1"
        country: "${.ngrok.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

Redirect Traffic​

note

Redirects are not yet supported with the Kubernetes Ingress Controller.

Pricing​

The ngrok Kubernetes Ingress Controller is available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the controller incur a cost.