Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through launching Rancher’s management platform, creating a new RKE2 cluster, connecting your cluster’s ingress to ngrok using Rancher’s Chart repository, and deploying a demo application that will then be reachable by public traffic. The ngrok Operator for Kubernetes is the official controller for adding secure public ingress and middleware execution to your Kubernetes applications with ngrok. With ngrok, you can manage and secure traffic to your applications at every stage of the development lifecycle while also benefitting from simpler configurations, security, and edge acceleration. Rancher is an open source multi-cluster orchestration management platform developed by SUSE. DevOps teams use Rancher to make their multi-cluster and -cloud environments more efficient, secure, and resilient, which in turn provides a better developer experience for developers building and deploying cloud native applications. The ngrok Kubernetes Operator and Rancher integrate to overcome Kubernetes complexity and improve collaboration through the creation of an internal developer platform (IDP) or enabling developers to focus on building, not configuring, their applications.

​
What you’ll need

  • One or more Linux hosts that meet Rancher’s requirements for operating as Kubernetes nodes. Your hosts can be local/on-prem virtual machines, cloud-based virtual machines, or bare metal servers.
  • Docker installed locally.
  • An ngrok account.
  • kubectl and Helm 3.0.0+ installed on your local workstation.
  • The ngrok Kubernetes Operator installed on your cluster. While you can install the Operator via Rancher directly, this guide recommends using the official Helm chart.
  • A reserved domain, which you can get in the ngrok dashboard or with the ngrok API.
    • You can choose from an ngrok subdomain or bring your own custom branded domain, like https://api.example.com.
    • This guide refers to this domain as <NGROK_DOMAIN>.

​
Install Rancher via Docker

To follow along with this guide, you need Rancher installed on a local or remote Kubernetes cluster. If you already have an existing cluster running Rancher, you can skip this step and proceed to Install a sample application. In the following steps, you’ll run Rancher, and create the Kubernetes cluster it runs on, within a Docker container. This simple, local-only installation option should be used only for test and demonstration purposes. You can, however, use the Rancher backup Operator to migrate this Docker container-based installation to a production-ready, high-availability Kubernetes cluster. The following steps also assume you have already provisioned one or more Linux hosts that will operate as nodes for the new Kubernetes cluster managed by Rancher.
Another viable option is to launch a single Linux virtual machine on your local workstation or with a cloud provider to host a K3s cluster for installing Rancher with Helm. If you choose that option, you can skip ahead to Install a sample application once you’ve finalized your K3s cluster.
  1. Launch the Rancher server in a detached, privileged Docker container. With this configuration, you’ll access Rancher on localhost using a specific port.
docker run --privileged --restart=unless-stopped -d -p 81:80 -p 444:443 rancher/rancher:latest
  1. Once Docker finishes running, check to ensure your Rancher container is running properly.
docker ps
CONTAINER ID   IMAGE                    COMMAND           CREATED        STATUS             PORTS                                                                      NAMES
d43eceb2e5b2   rancher/rancher:latest   "entrypoint.sh"   About a minute ago   Up About a minute   0.0.0.0:81->80/tcp, :::81->80/tcp, 0.0.0.0:444->443/tcp, :::444->443/tcp   vigilant_clarke
  1. Navigate to https://localhost:444 in your browser, accept the self-signed certificate warning, and use the bootstrap password prompt to initialize Rancher.
Copy the command from your terminal, replacing [DOCKER_NAME] with the name from docker ps. 
docker logs [DOCKER_NAME] 2>&1 | grep "Bootstrap Password:"
  1. Copy the terminal output into the password input and click Log in with Local User, then choose a password to initialize the admin user.
  2. The Server URL field will default to https://localhost:444, but your worker nodes won’t be able to connect to Rancher in this configuration. Find your local IP address (for example, hostname -I on Linux or ipconfig getifaddr en0 on macOS) and replace localhost with it (for example, https://192.168.1.107:444).
When the Rancher dashboard loads, Rancher should have already deployed a single K3s-based cluster named local; click the cluster’s name to explore. Rancher recommends running server management and workloads on separate clusters, which is what you’ll do next.
  1. Create a new RKE2 cluster by clicking Create in your Rancher dashboard home, then Custom to deploy a custom cluster. Give your cluster a name and, under System Services, uncheck NGINX Ingress (you’ll add ngrok-based ingress in the next step).
Click Create to initialize the cluster.
  1. Register your Linux nodes with your RKE2 cluster. Leave Node Role at its defaults and, under Registration Command, click the Insecure checkbox.
Once you copy-paste the command into your Linux node and execute it, your new cluster will begin bootstrapping the node. When Rancher finishes bootstrapping your nodes, you can navigate to the Cluster Dashboard for your RKE2 cluster, explore deployed resources, and see basic usage metrics.
  1. Set up kubectl to manage your RKE2 cluster. At the top of the Cluster Dashboard, click Copy KubeConfig to Clipboard. Paste the content into your ~/.kube/config file.
  2. Ensure your new RKE2 cluster is active by getting the namespaces for your instance. Your list of namespaces should look like the following: 
    kubectl get namespaces

NAME                          STATUS   AGE
calico-system                 Active   4m
cattle-impersonation-system   Active   29s
cattle-system                 Active   5m
default                       Active   5m4s
kube-node-lease               Active   5m6s
kube-public                   Active   5m6s
kube-system                   Active   5m6s
local                         Active   23s
tigera-operator               Active   4m10s
You have now installed Rancher in a Docker container, created a new Kubernetes cluster for your applications, and connected one or more Linux nodes to Rancher for handling future workloads.

​
Install a sample application

Now that you have the ngrok Kubernetes Operator running and authenticated with your credentials, you’re ready to add a sample application to your cluster. The ngrok Kubernetes Operator will connect this application to ngrok, simplifying how you route external traffic through your Rancher-managed cluster.
  1. Create a ngrok static subdomain for ingress if you don’t have one already. Go to the Domains section of the ngrok dashboard and click Create Domain or New Domain.
This static subdomain will be your <NGROK_DOMAIN> for the remainder of this guide. Creating a subdomain on the ngrok network provides a public route to accept HTTP, HTTPS, and TLS traffic.
  1. Create a new Kubernetes manifest (tinyllama.yaml) with the below contents. This manifest defines the tinyllama demo LLM application service and deployment, then configures the ngrok Kubernetes Operator to connect the tinyllama service to the ngrok network via your <NGROK_DOMAIN>.
showLineNumbers
apiVersion: v1
kind: Service
metadata:
  name: tinyllama
spec:
  ports:
    - name: http
      port: 80
      targetPort: 8080
  selector:
    app: tinyllama
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tinyllama
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tinyllama
  template:
    metadata:
      labels:
        app: tinyllama
    spec:
      containers:
        - name: tinyllama
          image: ghcr.io/ngrok-samples/tinyllama:main
          ports:
            - name: http
              containerPort: 8080
---
# ngrok Kubernetes Operator configuration
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tinyllama-ingress
spec:
  ingressClassName: ngrok
  rules:
    - host: <NGROK_DOMAIN>
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: tinyllama
                port:
                  number: 80
  1. Apply the tinyllama.yaml manifest to your RKE2 cluster.
kubectl apply -f tinyllama.yaml
  1. Access your tinyllama demo app by navigating to your ngrok subdomain (for example, https://one-two-three.ngrok.app). ngrok’s network and your Operator will route traffic to your app from any device or external network as long as your Rancher server and application cluster remain operational.

​
What’s next?

You’ve now used the open source ngrok Kubernetes Operator to add public ingress to your Rancher-managed cluster and sample application without worrying about IPs, network interfaces, or VPC routing. Because ngrok offloads ingress and middleware execution to its global network, you can follow a similar procedure for Rancher-managed clusters in any on-prem or cloud Kubernetes environment, like EKS, GKE, and more. After deploying this proof-of-concept environment, you can take your integration between Rancher and the ngrok Ingress Controller in several directions.

​
Backup and/or migrate to a high-availability Rancher installation

Backups prevent data loss and are the best way to convert your Docker-based Rancher installation into a production-grade environment that uses ngrok for ingress with no additional configuration.
  1. Back up your Rancher installation using a sequence of docker ... commands to create a data container and a backup tarball.
  2. Migrate your installation to a new cluster using the backup tarball as the data source (see Rancher’s migration docs).

​
Clean up

Because you installed Rancher and deployed your application cluster via Docker, you can clean up by stopping the Rancher container and removing its contents from your local workstation, replacing [DOCKER_NAME] with the name of your Rancher container. 
docker stop [DOCKER_NAME] && docker rm [DOCKER_NAME]
You can now clean up your Linux host, either by following the Rancher node cleanup documentation or, in the case of a disposable VM, deleting it entirely.

​
Extend your Rancher and ngrok Kubernetes Operator integration

This combination of cluster management and secure, cloud-based public ingress can become a robust development environment for those onboarding to the cloud native ecosystem or scaling to a multi-cluster production system, all with simpler and more secure ingress from ngrok. Learn more about the ngrok Kubernetes Operator, or contribute, by checking out the GitHub repository and the Kubernetes docs.