Kubernetes Operator

Overview

The Kubernetes Ingress Controller within the ngrok Kubernetes Operator allows access to Kubernetes Services using Kubernetes Ingress CRDs. More details on how these are derived is described in the guide to edges in k8s.

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 Kubernetes Operator is easy using Helm.

Add the ngrok Kubernetes Operator repo to Helm:

helm repo add ngrok https://charts.ngrok.com

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

Create an edge with a domain

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

This would modify the headers to add headers for is-ngrok (set to a value of "1") and a country (based on the country code). It would also remove the referrer header.

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

Redirect Traffic

note

Redirects are not yet supported with the ngrok Kubernetes Operator.

Pricing

The ngrok Kubernetes Operator is available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the controller incur a cost. More details can be found on our pricing page.