Migrate from ingress-nginx to the ngrok Operator without downtime

In November 2025, the Kubernetes SIG Network and the Security Response Committee (SRC) announced the retirement of ingress-nginx. It received best-effort support until March 2026, at which point all maintenance stopped. The repository is now read-only and that’s that.

We provide our own Kubernetes Operator at ngrok and have written in the past about what differentiates the ngrok Operator from others. In this post I’ll show you how to migrate from ingress-nginx to the ngrok operator.

Check which NGINX controller you run

Two different projects run NGINX as a Kubernetes Ingress controller, and only one of them is retired. ingress-nginx (kubernetes/ingress-nginx) is the community controller that Kubernetes retired. The NGINX Ingress Controller (nginx/kubernetes-ingress) is a separate product that F5 still maintains.

Check the controller behind your ingress classes:

1$ kubectl get ingressclass2NAME    CONTROLLER             PARAMETERS   AGE3nginx   k8s.io/ingress-nginx   <none>       37m

If the CONTROLLER column says k8s.io/ingress-nginx, you run the retired controller and the rest of this post is for you. If it says nginx.org/ingress-controller, you run F5’s controller, which still gets security fixes. The migration steps below still work if you want to move to ngrok, but you aren’t racing an end-of-life date.

Prerequisites

I’m going to assume you have a cluster with ingress-nginx running in it. For example, here it is in the cluster I’m using for this post.

1$ kubectl -n ingress-nginx get pods2NAME                                       READY   STATUS      RESTARTS   AGE3ingress-nginx-admission-create-dt6q4       0/1     Completed   0          37m4ingress-nginx-admission-patch-6j2q2        0/1     Completed   1          37m5ingress-nginx-controller-9cc49f96f-vcjq2   1/1     Running     0          37m

And to demonstrate that things are working correctly, I’ve created a small deployment using the testcontainers/helloworld image:

1apiVersion: apps/v12kind: Deployment3metadata:⋯4  name: helloworld5  labels:⋯6    app: helloworld7spec:⋯8  replicas: 19  selector:⋯10    matchLabels:⋯11      app: helloworld12  template:⋯13    metadata:⋯14      labels:⋯15        app: helloworld16    spec:⋯17      containers:⋯18        - name: helloworld⋯19          image: testcontainers/helloworld:1.3.0-linux20          ports:⋯21            - containerPort: 808022          readinessProbe:⋯23            httpGet:⋯24              path: /ping25              port: 808026            initialDelaySeconds: 527            periodSeconds: 528          livenessProbe:⋯29            httpGet:⋯30              path: /ping31              port: 808032            initialDelaySeconds: 1033            periodSeconds: 1034---35apiVersion: v136kind: Service37metadata:⋯38  name: helloworld39  labels:⋯40    app: helloworld41spec:⋯42  selector:⋯43    app: helloworld44  ports:⋯45    - name: http⋯46      port: 8047      targetPort: 808048      protocol: TCP49  type: ClusterIP50---51apiVersion: networking.k8s.io/v152kind: Ingress53metadata:⋯54  name: helloworld55spec:⋯56  ingressClassName: nginx57  rules:⋯58    - host: test.samwho.dev⋯59      http:⋯60        paths:⋯61          - path: /⋯62            pathType: Prefix63            backend:⋯64              service:⋯65                name: helloworld66                port:⋯67                  number: 80

If I request http://test.samwho.dev/ping using httpie, I see a PONG response:

1$ http test.samwho.dev/ping2HTTP/1.1 200 OK3Connection: keep-alive4Content-Length: 45Content-Type: text/plain; charset=utf-86Date: Fri, 14 Nov 2025 14:28:51 GMT78PONG

Sign up for ngrok

To use the ngrok Operator, sign up for an account at ngrok.com. Once you have an account, make note of your authtoken and you need to create an API key. You’ll find your authtoken in the Your Authtoken part of the dashboard. For your API key, go to the API Keys part of the dashboard and click + New API Key then follow the steps.

Install the ngrok Operator

The recommended way to install the ngrok Operator is through Helm. Substitute <YOUR_API_KEY> and <YOUR_AUTH_TOKEN> with your API key and authtoken from the previous step.

1$ helm repo add ngrok https://charts.ngrok.com2$ helm repo update3$ helm install ngrok-operator ngrok/ngrok-operator \4    --namespace ngrok-operator \5    --create-namespace \6    --set credentials.apiKey=<YOUR_API_KEY> \7    --set credentials.authtoken=<YOUR_AUTH_TOKEN>

Values you pass with --set stay in the Helm release, so anyone who can run helm get values on it can read your API key and authtoken. To keep them out of Helm, put them in a Kubernetes Secret first and give the chart the Secret’s name instead. read -s prompts for each value, so neither one lands in your shell history:

1$ read -rs NGROK_API_KEY && read -rs NGROK_AUTHTOKEN2$ kubectl create namespace ngrok-operator3$ kubectl -n ngrok-operator create secret generic ngrok-operator-credentials \4    --from-literal=API_KEY="$NGROK_API_KEY" \5    --from-literal=AUTHTOKEN="$NGROK_AUTHTOKEN"6$ unset NGROK_API_KEY NGROK_AUTHTOKEN7$ helm install ngrok-operator ngrok/ngrok-operator \8    --namespace ngrok-operator \9    --set credentials.secret.name=ngrok-operator-credentials

If all goes well you should see a message that ends like this:

1=== 🎉 Installation Complete 🎉 =========================================================2🎉 Thanks for installing the ngrok-operator!34➡️ Check out the next-steps docs: https://ngrok.com/docs/k8s/installation/install/5📣 Questions or feedback? Open an issue at https://github.com/ngrok/ngrok-operator/issues

And the pods should settle into the Running status:

1$ kubectl -n ngrok-operator get pods2NAME                                     READY   STATUS    RESTARTS   AGE3ngrok-operator-agent-5cbb74c95-t4bhv     1/1     Running   0          29m4ngrok-operator-manager-b6c749988-8qq97   1/1     Running   0          4m38s

Register a domain in ngrok

Before you create an ngrok Ingress resource, you need to register the domain you want to use in ngrok. Head over to the Domains section of the dashboard and register the domain you want to use by clicking the +New Domain button.

Note: You must already own the domain you want to use. ngrok is not a domain registrar, the registration process in ngrok is so that we know how to route traffic to you, it is not the same as buying a domain with a registrar.

Without a certificate (involves downtime)

The easiest way to migrate is to register a domain and get ngrok to automatically provision a certificate for you. However, doing this will result in a short period of downtime. In my testing, this lasted about 5 minutes. This is because ngrok uses Let’s Encrypt to provision certificates, and it needs your DNS name to point at ngrok to pass the ACME HTTP01 challenge. While the certificate is being provisioned, your domain will be considered insecure and most clients/browsers will refuse to connect to it.

The next section will cover how to avoid this downtime, but the remainder of this section will focus on creating a domain with an ngrok-managed certificate.

Fill in the domain creation form with your desired domain name, and leave everything else default. Here’s what it looked like for me:

When you’ve created the domain, you’ll be prompted to set the domain’s DNS record to be a CNAME pointing at ngrok. I recommend holding off from doing this right now, because when you do it you’ll break the domain for users until you’ve created your new Ingress resource. You’ll make the DNS switch as the last step of this migration process.

With a certificate (no downtime)

To avoid any downtime, you need to create a domain in ngrok with a certificate. After migrating, you’ll be able to switch to a certificate managed by ngrok without incurring any downtime. This step is just required to avoid downtime during the migration.

To demonstrate, I’ve configured my cluster to use cert-manager and I’ve issued a certificate for test.samwho.dev with Let’s Encrypt. My helloworld Ingress resource now looks like this:

1apiVersion: networking.k8s.io/v12kind: Ingress3metadata:⋯4  name: helloworld5  annotations:⋯6    cert-manager.io/cluster-issuer: letsencrypt-prod7spec:⋯8  ingressClassName: nginx9  rules:⋯10    - host: test.samwho.dev⋯11      http:⋯12        paths:⋯13          - path: /⋯14            pathType: Prefix15            backend:⋯16              service:⋯17                name: helloworld18                port:⋯19                  number: 8020  tls:⋯21    - hosts:⋯22        - test.samwho.dev23      secretName: letsencrypt-prod

I can verify it’s set up correctly by looking at the TLS section of the Ingress resource:

1$ kubectl get ingress helloworld -o jsonpath='{.spec.tls}'2[{"hosts":["test.samwho.dev"],"secretName":"letsencrypt-prod"}]

ngrok asks for 2 pieces of information when setting up a domain with your own certificate: the certificate itself, and the certificate private key. I can grab both of these from the secret that cert-manager created for my Ingress, which is called letsencrypt-prod as seen above. You should treat these as sensitive information and handle them securely.

1$ kubectl get secrets letsencrypt-prod -o jsonpath='{.data.tls\.crt}' | base64 -d2$ kubectl get secrets letsencrypt-prod -o jsonpath='{.data.tls\.key}' | base64 -d

If you’re using a different certificate manager, the way that you get this information may vary. You will know if you have the right values because the certificate looks like this:

1-----BEGIN CERTIFICATE-----2<loads of gibberish>3-----END CERTIFICATE-----

And the private key looks like this:

1-----BEGIN PRIVATE KEY-----2<loads of gibberish>3-----END PRIVATE KEY-----

With these in hand, navigate to the TLS certificates section of the ngrok dashboard and click +Create TLS Certificate. You’ll see a dialog that looks like this:

Put your certificate and private key in the appropriate boxes. In the description field, I recommend putting the domain name that the certificate applies to. In my case test.samwho.dev. Click save when you’re done.

Now to register the domain. Head over to the Domains section of the ngrok dashboard and click +Create Domain. Click on the certificate dropdown and select “Upload Certificate”. You should see your certificate:

Click save, and you’ll be shown instructions for setting up the CNAME record for your domain. Don’t do this just yet. You need to set up the ngrok Ingress resource first, which we’ll do next.

Create an ngrok Ingress

Rather than updating the existing Ingress resource, you’ll create a new one next to it that uses the ngrok ingress class. Here’s the Ingress resource I used in my cluster:

1apiVersion: networking.k8s.io/v12kind: Ingress3metadata:⋯4  name: helloworld-ngrok5spec:⋯6  ingressClassName: ngrok7  rules:⋯8    - host: test.samwho.dev⋯9      http:⋯10        paths:⋯11          - path: /⋯12            pathType: Prefix13            backend:⋯14              service:⋯15                name: helloworld16                port:⋯17                  number: 80

Save this as ngrok-ingress.yaml and apply it:

1$ kubectl apply -f ngrok-ingress.yaml

When the ngrok Operator picks up this Ingress, it will assign it an ngrok-cname.com address like so:

1$ kubectl get ingress2NAME               CLASS   HOSTS             ADDRESS                                               PORTS   AGE3helloworld         nginx   test.samwho.dev   192.168.49.2                                          80      41m4helloworld-ngrok   ngrok   test.samwho.dev   2awrvpxvfbuzgneam.5nqklokassiaw4xte.ngrok-cname.com   80      20m

That 2awrvpxvfbuzgneam.5nqklokassiaw4xte.ngrok-cname.com address is my ngrok-cname.com address, yours will be a different, unique value. You’ll use it later to update your DNS record.

Troubleshooting

If you don’t see an ngrok-cname.com address, for example your “Address” field is empty, there are a few debugging steps you can follow to figure out the problem.

Your first port of call should be the Operator logs.

1$ kubectl -n ngrok-operator get pods2NAME                                      READY   STATUS    RESTARTS   AGE3ngrok-operator-agent-5cbb74c95-6fhnm      1/1     Running   0          2d17h4ngrok-operator-manager-74b889db7c-8fbbw   1/1     Running   0          2d17h

1$ kubectl -n ngrok-operator logs ngrok-operator-manager-74b889db7c-8fbbw --all-containers -f2$ kubectl -n ngrok-operator logs ngrok-operator-agent-5cbb74c95-6fhnm --all-containers -f

These logs can be quite noisy, and you’re likely to see errors like “the object has been modified” but these are a normal part of the reconciliation model. If the logs don’t yield anything useful, we also put debugging information into the ngrok Operator’s resources. For example, “agent endpoints” are the connections the Operator makes to ngrok, that ngrok later uses to send traffic to your application. If these have failed to create, you can check their status:

1$ kubectl get agentendpoints2NAME                          URL                       UPSTREAM URL                   BINDINGS   READY   AGE3c3fe2-helloworld-default-80   https://test.samwho.dev   http://helloworld.default:80              True    28m

Then getting more detail about a specific endpoint:

1$ kubectl get agentendpoint c3fe2-helloworld-default-80 -o yaml

If something has gone wrong creating the endpoint, there will be an error message about it in this output. For example, early on in this post I had accidentally installed the ngrok operator with an authtoken from my work account and an API key from my personal account. The error message I found in my agentendpoint was:

1Failed to create endpoint: This domain is reserved for another account. Failed to create an endpoint with the domain 'test.samwho.dev' for the account 'Sam Rose'. If you have reserved this name, make sure that you are using an authtoken credential for the appropriate account. Reserve a name on your dashboard: https://dashboard.ngrok.com/domains/new ERR_NGROK_320

This gave me the clue I needed to realise that I had used the wrong API key. If you’re deeply stuck and can’t figure out what’s wrong, you’re welcome to file an issue and we’ll try to help you out.

Move your nginx annotations to Traffic Policy

The helloworld example has no nginx.ingress.kubernetes.io/* annotations, but your Ingress resources probably do. The ngrok Operator ignores them, so anything they configure, such as rewrites, redirects, rate limits, basic auth, or IP allowlists, stops happening when traffic moves to ngrok. Move each one before you switch DNS.

List every nginx annotation in your cluster:

1$ kubectl get ingress -A -o json | jq -r '.items[] | .metadata as $m2    | ($m.annotations // {}) | to_entries[]3    | select(.key | startswith("nginx.ingress.kubernetes.io/"))4    | "\($m.namespace)/\($m.name)\t\(.key)=\(.value)"'

Most of them map to a Traffic Policy action. For example, if your nginx Ingress allows only your office network with nginx.ingress.kubernetes.io/whitelist-source-range: "203.0.113.0/24", create an NgrokTrafficPolicy that does the same with the restrict-ips action:

1apiVersion: ngrok.k8s.ngrok.com/v1alpha12kind: NgrokTrafficPolicy3metadata:⋯4  name: office-only5spec:⋯6  policy:⋯7    on_http_request:⋯8      - name: OfficeOnly⋯9        actions:⋯10          - type: restrict-ips⋯11            config:⋯12              enforce: true13              allow:⋯14                - 203.0.113.0/24

Then attach it to your ngrok Ingress with the ngrok.com/traffic-policy annotation:

1apiVersion: networking.k8s.io/v12kind: Ingress3metadata:⋯4  name: helloworld-ngrok5  annotations:⋯6    ngrok.com/traffic-policy: office-only7spec:⋯8  ingressClassName: ngrok9  # ...rules unchanged

The ingress-nginx migration guide in the ngrok docs maps the common nginx annotations to their ngrok equivalents. It also covers the ones that don’t translate one-to-one: limit-rps needs a per-minute rate limit, backend-protocol: "HTTPS" moves to an annotation on the Service, and settings that tune NGINX itself, like buffer sizes and timeouts, have no direct equivalent.

Switch DNS

Now is the time to change your DNS over to point at ngrok. Every DNS registrar will have a different way to do this, but the end result should be that your domain is a CNAME record that points to your <gibberish>.ngrok-cname.com address. To find it, run:

1$ kubectl get ingress2NAME               CLASS   HOSTS             ADDRESS                                               PORTS     AGE3helloworld         nginx   test.samwho.dev   192.168.49.2                                          80, 443   2d20h4helloworld-ngrok   ngrok   test.samwho.dev   2awrvpxvfbuzgneam.5nqklokassiaw4xte.ngrok-cname.com   80        3h41m

Here, 2awrvpxvfbuzgneam.5nqklokassiaw4xte.ngrok-cname.com is the address I should use when setting up my CNAME. Yours will be different, but will end with .ngrok-cname.com.

For folks who have opted to have ngrok automatically manage their certificates, the moment you change over to the ngrok CNAME your clients will start seeing that your domain is insecure. This will persist until ngrok provisions a certificate for the domain, which usually takes a few minutes. You can check the status of this process by clicking on the domain in your dashboard:

When your domain looks like the above, with a certificate ID near the bottom, the downtime should stop.

For those who created a TLS certificate and attached it to the domain, clients will seamlessly transition without noticing any change.

When all has settled you will be able to send a request and get a response as expected:

1$ http https://test.samwho.dev/ping2HTTP/1.1 200 OK3Content-Length: 44Content-Type: text/plain; charset=utf-85Date: Fri, 14 Nov 2025 17:56:36 GMT67PONG

You can verify that this is going through ngrok by checking Traffic Inspector in your dashboard:

Your traffic is flowing through ngrok. 🎉 Once your old DNS record’s TTL has passed and no more requests reach ingress-nginx, you can clean up the old nginx Ingress resources.

Switch over to ngrok managed certificates

If you set up your own certificate during domain creation, you can now change to having ngrok manage your certificates for you. Head to the Domains page and switch to “Automated TLS certificates” like so:

ngrok will provision a certificate in the background, making sure to keep using your supplied certificate until the new one is ready. This ensures a seamless transition without downtime, and the job of making sure the certificate is valid and renewed is taken care of by ngrok.

Use the Gateway API instead of Ingress

This post keeps your Ingress resources so the migration changes as little as possible. The Kubernetes maintainers recommend the Gateway API as the long-term replacement for Ingress, and the ngrok Operator supports it too.

The Operator turns on Gateway API support when it finds the Gateway API CRDs in your cluster. If you install the CRDs after the Operator, restart the Operator so it picks them up. Then create a GatewayClass that points at ngrok:

1apiVersion: gateway.networking.k8s.io/v12kind: GatewayClass3metadata:⋯4  name: ngrok5spec:⋯6  controllerName: ngrok.com/gateway-controller

To convert your existing Ingress resources, run ingress2gateway with --providers=ingress-nginx. It translates some nginx annotations, like rewrite-target, into Gateway API filters. Make three changes to its output before you apply it:

• Set gatewayClassName to ngrok. ingress2gateway names the class after your old ingress class.
• Change each listener to protocol: HTTPS and port: 443. ingress2gateway writes HTTP listeners on port 80, which serve only http:// URLs. The Operator can’t switch an existing listener from HTTP to HTTPS, so delete and recreate a Gateway you already applied.
• Replace each RegularExpression path match with a PathPrefix or Exact match. ingress2gateway writes them for Ingress resources that use rewrite-target or use-regex. The Operator compares a regular expression as a literal prefix, so those routes return 404.

The Gateway API guide in the ngrok docs covers listeners, routes, and attaching Traffic Policy.

Your migration checklist

To move a cluster off ingress-nginx:

1. Run kubectl get ingressclass and confirm the controller is k8s.io/ingress-nginx.
2. Install the ngrok Operator and register your domain. Upload your current certificate if a few minutes of TLS errors isn’t acceptable.
3. Create an ngrok Ingress next to each nginx Ingress, and move its nginx annotations to Traffic Policy.
4. Point your domain’s CNAME record at its ngrok-cname.com address.
5. Switch the domain to ngrok-managed certificates.
6. After your old DNS record’s TTL passes and no traffic reaches ingress-nginx, delete the old nginx Ingress resources and uninstall ingress-nginx.

After the move, the Operator only makes outbound connections to ngrok, so your cluster doesn’t need a public load balancer or open inbound ports. Every request shows up in Traffic Inspector, and Traffic Policy runs at ngrok’s edge, so a request it blocks never reaches your cluster.

If public traffic can’t pass through a third-party edge, ngrok isn’t the right fit. Pick one of the maintained controllers in the Kubernetes docs instead.

If you have any questions about what you’ve read, or you’ve tried to migrate and you’re stuck, please visit our support page or email us at support@ngrok.com.