Skip to main content

Deployment Guide

This guide is meant as the starting point for configuring, deploying, and operating the controller component itself. It focuses on configurations and settings for the whole controller, and thus its corresponding ingress class, rather than individual ingress resources and their annotations.

Prerequisites​

  • A K8s cluster with kubectl access - We recommend using a recent version of K8s and will specify and test past versions as a part of this GitHub issue
  • helm - 3.0.0 or later.

Installation​

It is recommended to use helm to install the operator. Alternatively, the container is available on Docker Hub at ngrok/ingress-controller and can be run directly with hand crafted manifests.

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

For a more robust infrastructure as code way of passing your credentials, see the credentials page.

Alternate options​

For a quick install, you can also use the combined manifests directly from the repo and begin changing resources:

kubectl apply -n ngrok-ingress-controller -f https://raw.githubusercontent.com/ngrok/kubernetes-ingress-controller/main/manifest-bundle.yaml

Credentials​

In order to use the ngrok Kubernetes Operator, you will need an ngrok account. Once you have an account, you will need to log into the ngrok dashboard to gather the necessary credentials.

You will need two things from the dashboard:

  • Your auth token, which can be found here
  • An API key, which can be generaterd here

These credentials will be created as a Kubernetes secret, which the controller will have access to. The auth token is used to create tunnels, and the API key is used to manage edges and other resources via the ngrok API.

Setup​

While the quickstart guide shows you can pass the credential values directly via helm values, we do not recommend this for production scenarios. Instead, we recommend creating a Kubernetes secret and passing the secret name to the helm chart. This allows for easier infrastructure as code in a more secure manner.

Creating the Secret​

To create the secret, follow these steps:

  • Make sure the secret is in the same namespace as the ingress controller
  • Use a well-formed name that can be passed to the helm chart
  • Add two keys to the secret: API_KEY and AUTHTOKEN

Here is an example secret manifest:

apiVersion: v1
kind: Secret
metadata:
  name: ngrok-ingress-controller-credentials
  namespace: ngrok-ingress-controller
data:
  API_KEY: "YOUR-API-KEY-BASE64"
  AUTHTOKEN: "YOUR-AUTHTOKEN-BASE64"

Common Helm K8s Overrides​

This section provides some common use cases and recommendations when using this helm chart in a production setting. The Helm chart offers a variety of overrides that are useful for many different use cases in Kubernetes. Below is a list of common recipes that you may find helpful. If your use case is not achievable with the existing set of values, please log an issue detailing your use case and the values you would like to see added. For a full list of values, see here.

Deployment Scaling​

By default, the replica count is set to 1 via replicaCount . We recommend overriding this to 2 or more to ensure high availability during roll-outs and failures, and to spread out the load.

Image Configuration​

The default image tag is latest, which is not recommended for production deployments. Instead, you should set the image.tag value to a specific version of the controller. You can find available versions in the releases section. Additionally, you may choose to mirror the image to a private registry and set the image.repository value to the private registry, along with any required pull secrets.

Applying Labels and Annotations​

You may want to add specific labels or annotations to your resources, to help them be discovered and interact with other services like log scrapers or service meshes. You can set the commonLabels and commonAnnotations values for all resources created by the helm chart. Additionally, you can set annotations just on the pods themselves by setting the podAnnotations value.

Adding Extra Volumes and Environment Variables​

The helm chart also allows you to add extra volumes and environment variables to the operator, which is useful for mounting secrets or configmaps that contain credentials or other configuration values. This can be done by setting the extraVolumes and extraEnv values.

ngrok Region​

ngrok runs globally distributed tunnel servers around the world to enable fast, low latency traffic to your applications. See ngrok's points of presence for more information on ngrok's regions.

Similar to the agent, if you do not explicitly pick a region via helm when installing the operator, the operator will attempt to pick the region with the least latency, which is usually the one geographically closest to your machine.

See the helm value region to configure a specific region for the controller to use.

Metrics​

This operator exposes prometheus metrics on the /metrics endpoint. The metrics are exposed on the :8080 port and can be scraped by prometheus or other services using typical means.

This project is built using kube-builder, so out of the box it exposes the metrics listed here