Using Rancher Desktop for Local Kubernetes Development

Installing on Debian Systems

Rancher Desktop has an APT repository that you can use to install it on Debian-based systems. Run the commands below to add the repository and its signing key:

$ curl -s https://download.opensuse.org/repositories/isv:/Rancher:/stable/deb/Release.key | gpg --dearmor | sudo dd status=none of=/usr/share/keyrings/isv-rancher-stable-archive-keyring.gpg
$ echo 'deb [signed-by=/usr/share/keyrings/isv-rancher-stable-archive-keyring.gpg] https://download.opensuse.org/repositories/isv:/Rancher:/stable/deb/ ./' | sudo dd status=none of=/etc/apt/sources.list.d/isv-rancher-stable.list
$ sudo apt update

Next install the package with the following command:

$ sudo apt install rancher-desktop

Installing on OpenSUSE

Use the following command sequence to install Rancher Desktop as an .rpm package on OpenSUSE systems:

$ sudo zypper addrepo https://download.opensuse.org/repositories/isv:/Rancher:/stable/rpm/isv:Rancher:stable.repo
$ sudo zypper install rancher-desktop

The .rpm doesn’t work properly with RHEL and Fedora, since they distribute QEMU differently. If you’re using one of these operating systems, run Rancher as an AppImage instead (see below) so it can successfully create a QEMU virtual machine.

Using Rancher’s AppImage

Rancher is also available as an AppImage for all Linux systems. This is a self-contained binary format that executes without dependencies. To run Rancher Desktop in this way, download the AppImage and make it executable:

$ wget https://download.opensuse.org/repositories/isv:/Rancher:/stable/AppImage/rancher-desktop-latest-x86_64.AppImage
$ chmod +x rancher-desktop-latest-x86_64.AppImage

Start Rancher Desktop by running the downloaded binary:

$ ./rancher-desktop-latest-x86_64.AppImage

To remove Rancher Desktop in the future, follow the guidance in the documentation to perform a factory reset and uninstall the app. This will ensure that everything added to your system gets cleaned up properly.

Getting Started

When you first run Rancher Desktop, you’ll need to perform some initial configuration to set up your environment. On the landing page, use the dropdown box to select the Kubernetes version you want to use. It’s best to leave this at the default “stable” release unless you need to match an existing environment.

Next select the runtime to use for containers started outside of Kubernetes. Selecting containerd gives you access to all Rancher’s container management features, including namespaces and nerdctl. Selecting dockerd will use the runtime that’s shipped with Docker, via its regular Unix socket.

If you don’t plan to use the Kubernetes features, you can clear the “Enable Kubernetes” checkbox to proceed without them. You’ll still be able to build and start container images with nerdctl and the selected container runtime.

You’ll be taken to the Rancher Desktop homepage after you click Accept. Rancher will download your chosen Kubernetes release, then create your virtual machine and start up the installation. You can check its progress in the status area in the bottom left. Be patient—this first run might take a while. Your installation will be ready to use when the progress bar disappears.

Exploring the GUI

Rancher’s GUI gives you an overview of your installation and exposes some management controls. The default General tab shows your Rancher version, provides links to related resources and offers a checkbox for opting out of anonymous usage metrics collection.

Switching to the Kubernetes Settings tab lets you manage your Kubernetes cluster. Here you can switch between Kubernetes versions, alter the control plane’s port number, and change the container runtime (containerd or dockerd) used for your containers. Sliders at the bottom of the page modify the hardware resource limits that your Rancher VM can use.

The bottom of the screen includes a Reset Kubernetes button to restore your cluster to a clean slate. This is convenient when you’re experimenting with Rancher or running new workloads that you want to quickly remove. To reset your entire Rancher Desktop installation, head to the Troubleshooting screen and press the Factory Reset button.

The Application Settings screen controls how Rancher Desktop adds its bundled docker, helm, kubectl, and nerdctl commands to your PATH. These utilities are provided in the ~/.rd/bin directory within your home folder. Rancher’s “Automatic” PATH configuration mode modifies your shell profile to include ~/.rd/bin for you.

Switching to manual mode leaves your shell profile file intact. You’ll need to manually add ~/.rd/bin to your path before you can run commands like docker and nerdctl in your shell. This can help avoid conflicts if you’re already using standalone installations of some of these utilities.

The “Allow sudo access” checkbox determines whether Rancher Desktop tries to acquire administrative privileges when it starts. This is required to use features such as access to your host’s Docker socket and bridged networking support. You can turn it off to run Rancher Desktop with fewer system privileges.

Working with Images

Use nerdctl to pull an image to your Rancher installation:

$ nerdctl pull nginx:latest
docker.io/library/nginx:latest:                                                   resolved       |++++++++++++++++++++++++++++++++++++++|
index-sha256:4ed64c2e0857ad21c38b98345ebb5edb01791a0a10b0e9e3d9ddde185cdbd31a:    done           |++++++++++++++++++++++++++++++++++++++|
manifest-sha256:1a763cbd30ef4dbc7f8e3fa2e6670fd726f4bddb0ef58868a243c0cb8b35cde1: done           |++++++++++++++++++++++++++++++++++++++|
config-sha256:f2f70adc5d89aa922836e9cc6801980a12a7ff9012446cc6edf52ef8798a67bd:   done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:be0c016df0be98964bf62fc97d820463c5228ed3ceef321cb4bedc5b86eb7660:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:dca7733b187e4e05ef6a71f40eb02380dde472b7e3da6dcffcafcfded823352b:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:352e5a6cac2644c979e06a33493d883694ad0716bab021561da45e2f4afd84cd:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:9eaf108767c796d28e8400fe30b87d5624b985847173bb20587ae85bc7179e3a:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:ae13dd57832654086618a81dbc128846aa092489260c326ee95429b63c3cf213:    done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:6c0ee9353e13944dca360479cb7eecfa65c6726948c1b85db3f8b57b68631a3b:    done           |++++++++++++++++++++++++++++++++++++++|
elapsed: 8.0 s                                                                    total:  54.1 M (6.8 MiB/s)                                       

View the downloaded image with the nerdctl images command:

$ nerdctl images
REPOSITORY    TAG       IMAGE ID        CREATED               PLATFORM       SIZE         BLOB SIZE
nginx         latest    4ed64c2e0857    About a minute ago    linux/amd64    149.1 MiB    54.1 MiB

When you’ve selected the containerd runtime, you can use namespaces to separate resources by their purpose or function. This mechanism has a similar role to Kubernetes namespaces. Using nerdctl works with the default namespace when you don’t specify another. Use the -n command to target a specific namespace:

# No images in this namespace yet
$ nerdctl -n demo-namespace images
REPOSITORY    TAG    IMAGE ID    CREATED    PLATFORM    SIZE    BLOB SIZE

# Pull an image into a namespace
$ nerdctl -n demo-namespace pull nginx:latest

# Now the image exists in the namespace
$ nerdctl -n demo-namespace images
nginx         latest    4ed64c2e0857    About a minute ago    linux/amd64    149.1 MiB    54.1 MiB

You can also view your images in the GUI. Head to the Images tab in the left sidebar, then select the correct namespace from the dropdown menu. To pull a new image, click the blue + icon in the top right, then paste your image’s registry URL into the text field.

Starting Containers in Your Cluster

You can start a container instance with nerdctl:

$ nerdctl run -d -p 8176:80 nginx:latest
66d5a724732dd42a5daeb2d0349413e4ef14c899d03bbfdab51fccf645251d56

The container will be added to the default namespace as no -n flag was included.

You can check that the container is running using nerdctl ps:

$ nerdctl ps
CONTAINER ID    IMAGE                             COMMAND                   CREATED           STATUS    PORTS                   NAMES
ec408d49bd92    docker.io/library/nginx:latest    "/docker-entrypoint.…"    32 seconds ago    Up        0.0.0.0:8176->80/tcp    nginx-ec408

Since a port has been bound to the container, you can also visit localhost:8176 in your web browser to see the default NGINX landing page.

You can stop the container by passing its ID to the nerdctl stop command:

$ nerdctl stop 66d5a7
66d5a724732dd42a5daeb2d0349413e4ef14c899d03bbfdab51fccf645251d56

Using kubectl

Now run a container with Kubernetes. Create a basic manifest for your Kubernetes pod:

apiVersion: v1
kind: Pod
metadata:
  name: rancher-pod
spec:
  containers:
    - name: nginx
      image: nginx:latest
      ports:
        - containerPort: 80
          hostPort: 8176

Use the kubectl provided by Rancher Desktop to add this pod to your Kubernetes cluster:

$ kubectl apply -f pod.yml
pod/rancher-pod created

Check that the pod has been created successfully with the get pods command:

$ kubectl get pods
NAME          READY   STATUS    RESTARTS   AGE
rancher-pod   1/1     Running   0          49s

Visiting localhost:8176 should show the NGINX landing page again. The container should be running inside Rancher’s Kubernetes cluster. Once your application is working in your Rancher-powered development cluster, you can take the same Kubernetes manifests and apply them to your production environment.

Remove your Kubernetes pod with the delete command:

$ kubectl delete pod/rancher-pod
pod "rancher-pod" deleted

Scanning Images for Security Issues

Development isn’t complete until you’ve taken care of security. Rancher Desktop integrates a Trivy-powered image-scanning solution you can use to find vulnerabilities within your local environment before moving to production. This can be found on the Images page of the GUI.

Click the three dots icon to the right of any image in the list and select Scan from the menu that appears. The scan may take a few moments to complete. You’ll see vulnerability details shown as a list, ordered by severity with clear colorization. Selecting any of the rows shows detailed information about the threat.

You can use this tool to check the safety of your images after you build them. The graphical presentation can be easier to digest than terminal-based reports.

Conclusion

As this tutorial demonstrated, Rancher Desktop streamlines provisioning new development environments that can build and run containers. The open source container management solution uses containerd, dockerd and a K3s-based Kubernetes cluster to easily spin up Kubernetes for your local environment.

Rancher Desktop is part of SUSE’s broader Rancher-branded container platform. The Rancher management system unifies multi-cluster Kubernetes environments to simplify day-to-day operations such as monitoring, logging, and access control. SUSE is also known for its Linux Enterprise Server distribution, an operating system designed for cloud-agnostic deployments.

For more on what SUSE offers, check its documentation. You can find content specific to Rancher and Rancher Desktop on their respective documentation sites.

Next Steps

There are several next steps you can take:

• Star Rancher Desktop on GitHub to show that you like it. This lets us know that you want to see development continue.
• Install the v1.3.0 release.
• Provide feedback in the issue queue.