The Rancher CLI is your direct line to managing Kubernetes clusters without touching a web browser.
Let’s get a cluster up and running and see it in action. First, you’ll need to install the rancher binary. On macOS, this is as simple as:
brew install rancher/tap/rancher
Once installed, you need to connect it to your Rancher server. This involves an API URL and a token. You can get these from the Rancher UI under your user settings.
rancher login https://your-rancher-domain.com --token <your-token> --insecure-skip-tls-verify
The --insecure-skip-tls-verify is for quick setups; in production, you’d want to configure proper TLS.
Now, let’s create a cluster. Rancher can provision clusters on various cloud providers or manage existing ones. For this quickstart, we’ll create a downstream cluster using RKE (Rancher Kubernetes Engine) on a single node.
rancher cluster create my-rke-cluster \
--rke-cluster-template \
--rke-cluster-template-version v1.27.10+rke2r1 \
--kubernetes-version 1.27.10 \
--rke-config '{"nodes": [{"address": "192.168.1.100", "user": "rancher", "role": ["controlplane", "etcd", "worker"]}]}' \
--cloud-credential <your-cloud-credential-id>
This command tells Rancher to create a new RKE cluster named my-rke-cluster. It specifies the Kubernetes version and configures a single node at 192.168.1.100 to act as controlplane, etcd, and worker. The --cloud-credential points to a pre-configured cloud credential within Rancher. If you’re not using a cloud provider and just managing an existing node, you’d omit the cloud credential and provide the node details directly.
After running this, Rancher starts provisioning the cluster. You can check its status:
rancher cluster list
You’ll see your cluster in a Provisioning state, then Waiting, and finally Active.
Once active, you can get its kubeconfig to interact with it directly using kubectl.
rancher cluster kubeconfig my-rke-cluster > ~/.kube/config
This command overwrites your default kubeconfig with the one for my-rke-cluster. Be careful if you manage multiple clusters! A safer approach is to append it:
rancher cluster kubeconfig my-rke-cluster >> ~/.kube/config
Then, you’d use kubectl config use-context <cluster-context-name> to switch.
Now you can deploy applications. Let’s deploy a simple Nginx pod:
kubectl run nginx --image=nginx
kubectl get pods
You’ll see your Nginx pod running. The Rancher CLI isn’t just for cluster creation; it’s your gateway to managing all Rancher resources: projects, namespaces, workloads, storage, and more. You can list projects:
rancher project list
And then select a project to operate within:
rancher context switch project <project-id>
This sets the default project for subsequent rancher commands.
The true power of the CLI emerges when you automate tasks. Imagine a CI/CD pipeline that needs to deploy an application. You can use the rancher CLI to create namespaces, deployments, and services, all scripted. For example, to deploy a YAML file:
rancher kubectl apply -f my-app.yaml
This rancher kubectl command is a proxy to your cluster’s kubectl through Rancher’s API, ensuring consistency and auditability.
One subtle but powerful aspect of the Rancher CLI is its ability to manage cluster templates and node templates. These are reusable definitions for creating new clusters or node pools. When you create a cluster using --rke-cluster-template, you’re leveraging these pre-defined configurations, ensuring that your clusters are provisioned with standardized settings. This is crucial for maintaining consistency across your infrastructure, especially in larger organizations. You can inspect these templates:
rancher cluster-template list
rancher cluster-template-version list <template-id>
This allows you to understand the exact parameters that define your cluster’s infrastructure, from Kubernetes versions and CNIs to specific RKE configuration options.
The next step in mastering Rancher from the terminal is to explore its continuous delivery capabilities, allowing you to manage application deployments and GitOps workflows directly from the CLI.