Skip to content

Setting Up Rancher Development Environment

Jump to bottom
Dan P. edited this page Apr 8, 2026 · 6 revisions

Setting up for Rancher development

Set up GoLand

Set up VSCode

Setting up and running the legacy Python Tests

Gotchas

Next Steps

Learning Resources

Setting up for Rancher development

This page will go over setting up your environment for development work on the current version of rancher. This is primarily built on the premise of setting up in a MacOS environment, but most of it should carry over to linux as well.

Install Dependencies

  • Go

    Rancher is built in Go, which can be downloaded here: https://golang.org/dl/. Alternatively, on MacOS it can be installed with homebrew using the following command: brew install go

    additionally, you should add the gopath bin directory to your path. Add the following to your .bashrc or other shell file

    export PATH=${GOPATH//://bin:}/bin:$PATH

  • Kubernetes

    The local Rancher instance will be hosted in an installation of Kubernetes. Typically this will be done with a local cluster, but you can also launch one in the cloud and simply point your Kubeconfig there. A local cluster can be setup in a variety of ways, but typically we use:

    • k3d
      • The big advantage of k3d, besides the speed of k3s, is that you can create a multi-cluster setup locally. The downside is that you won't have the full K8's feature set, see the k3s repo for more info on that. The readme has install instructions, note that you'll have to point Rancher at the custom kube config since it lives in a non-standard location.
    • Rancher Desktop
      • To install rancher desktop, go to the github releases for the project. Under "Assets", click the architecture for your target system. When installing, select "dockerd (moby)"as the container engine. You can use containerd instead, but you will need to install different/additional tools and will face some limitations.
      • After installing the container engine, run rancher desktop. Click the Rancher Desktop icon in the toolbar and click "Preferences". Go to "Supporting Utilities". At minimum, install docker and kim (if you chose containerd in the previous step, install nerdctl instead of docker). You can install helm/kubectl here as well, but you can also use an existing install or another method (such as homebrew) to provide these tools.
      • Due to Rancher desktop's integration with k3s/traefik, you may experience difficulty with running rancher (and other images) using port 80/443. You can get around this by using a different port on your host (for example sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher becomes docker run -d --restart=unless-stopped -p 8080:80 -p 8443:443 --privileged rancher/rancher, and will allow you to view the rancher UI at https://localhost:8443).

  • IDE

    Most of us at Rancher use GoLand or VSCode, and the rest of this document will be written assuming you are as well, but there are several options

  • ngrok

    ngrok allows you to forward an external url to your local webservers. It is available here: https://ngrok.com. On MacOS it can be installed via homebrew with the command brew install --cask ngrok. ngrok removes some of the difficulty of container networking. If you do not use ngrok, you will need to ensure you set up container port forwarding in order to be able to use kubectl to manange clusters underneath rancher (like the local dev cluster). Make sure to create an account in order to have the full functionality. The ngrok config file is stored by default at ~/.ngrok2/ngrok.yml and can be updated with the below example config to run Rancher and the rancher-webhook at the same time. If not using a paid version of ngrok with domain reservation drop the url field and ngrok will randomly generate one.

endpoints:
  - name: rancher
    url: <requires paid version>
    upstream:
      url: 8080
  - name: webhook
    url: <requires paid version>
    upstream:
      url: 9443

Note

The example config was updated to use endpoints because, the tunnels field is deprecated and was set to be removed by the end of 2025.

You can also create an alias for rapid development with ngrok and rancher defaults: alias ngrok-rancher="ngrok http https://localhost:8443"

Clone repo and set up project structure

To start, you will likely only need to clone the rancher/rancher repository You should create your own fork of rancher/rancher and then clone the repository to your local machine. git clone https://github.com/<my_github>/<rancher_fork_name>.git

  • Setting up remotes

In order to avoid accidentally creating a branch in the rancher/rancher repo please set your remote accordingly with your fork.

origin    git@github.com:AwesomeContributor/rancher.git (fetch)
origin    git@github.com:AwesomeContributor/rancher.git (push)
upstream    https://github.com/rancher/rancher.git (fetch)
upstream    https://github.com/rancher/rancher.git (push)

HTTPS urls allow for unauthencitcated cloning and pulling. Futhermore, you have 2-factor auth set up (right?) and https pushing will fail. To get the most up-to-date version run:

git fetch upstream

Set up GoLand

If you would like to use GoLand there are a few things to do here.

Set go mod or GOPATH

  • If using a version of rancher on go mod, in preferences -> Go -> Go Modules select "Enable Go Modules" and also "Vendoring mode".
  • If not using go mod, the GOPATH for a given project should be one step up from the src folder. Set this in preferences -> Go -> GOPATH -> Project GOPATH.

Disable cgo

In Settings -> Go -> Build Tags -> rancher make sure "Cgo support" is set to "Disabled".

image

This is necessary to avoid a golang 1.22 issue and is aligned to what official builds do.

Set up the build target

Click the Run menu option and select Edit Configurations. Click the + to add a template and select Go Build

  • In files select the main.go file
  • change go tool arguments to -gcflags="-N -l"
  • change program arguments to --add-local=true
  • add environment variables:
    • KUBECONFIG set to {homedirectory}/.kube/config (on MacOS /Users/<username>/.kube/config)
    • CATTLE_DEV_MODE set to 30 (avoids losing cattle election in local dev env)
    • CATTLE_SYSTEM_CHART_DEFAULT_BRANCH set to dev-vX.Y where X is the targeted major and Y is the targeted minor version (eg. dev-v2.8 or dev-v2.9)
    • CATTLE_BOOTSTRAP_PASSWORD set to adminadminadmin (avoids the need to go back to kubectl to get it)
  • If you intend to bring up downstream clusters using the dev environment, set the following environment variables:
    • CATTLE_SYSTEM_AGENT_INSTALL_SCRIPT to https://github.com/rancher/system-agent/releases/download/v0.3.5-rc2/install.sh
    • CATTLE_SYSTEM_AGENT_INSTALLER_IMAGE to rancher/system-agent-installer-.

(Optional) Add k3d to the "Before launch" Section

Click the "Before launch" dropdown and create an external tool. You can create two external tools that run the following in sequence:

  • k3d cluster delete <dedicated-test-cluster-name>
  • k3d cluster create <dedicated-test-cluster-name>
  • these external tools will execute before the rest of your build target starts

Run

Start the build in GoLand. The service will be available at http://localhost:8080. Ignore the scary cert warning (or use ngrok as a way around.

Work with dependent libraries

If you need to patch any of the libraries Rancher directly depends upon (such as lasso, steve, wrangler, remotedialer...) you can:

  • clone the library, checkout the appropriate branch
  • File -> Open... the library directory, choose Attach to add the library to the current project
  • add the following line near the top of go.mod:
replace github.com/rancher/lasso => /path/to/your/clone/of/lasso

This will allow you to have any changes in lasso immediately reflected in builds/test runs/debug sessions in the main rancher module.

Remember that line has to be removed (or git stashed away) rather than included in pull requests!

Set up VSCode

The VSCode setup is painless to get started download VSCode and run code <path_to_rancher_clone>

Download extensions.

To get started, you only need the GO extension, but here is a list of some other extensions you might find useful in the future.

Create LaunchFile

Create a launch.json file to hold your debug configuration. Inside your launch.json file add the following content.

{
    "name": "Run Rancher",
    "type": "go",
    "request": "launch",
    "mode": "debug",
    "program": "main.go",
    "env": {
        // Enter the path of kubeconfig of a running cluster or delete the line to use the default KUBECONFIG.
        "KUBECONFIG": "<KUBE_CONFIG_PATH>",
        "CATTLE_DEV_MODE": "30",
        "CATTLE_SYSTEM_CHART_DEFAULT_BRANCH": "release-v2.7",
        "CATTLE_BOOTSTRAP_PASSWORD": "<admin_password>",
        // If you intend to bring up downstream clusters using the dev environment, set the following environment variables:
        "CATTLE_SYSTEM_AGENT_INSTALL_SCRIPT": "https://github.com/rancher/system-agent/releases/download/v0.3.5-rc2/install.sh",
        "CATTLE_SYSTEM_AGENT_INSTALLER_IMAGE": "rancher/system-agent-installer-"
    },
    "output": "rancher_debug",
    "args": [
        "--trace=false",
        "--add-local=true",
        "--no-cacerts"
    ]
},

Run

And That's it just hit the select the debug tab and run Rancher. Rancher will be available at https://localhost:8443. Ignore the cert warning (or use ngrok as a way around)

(Optional) Add k3d "preLaunchTask"

We can duplicate our launch.json configuration and add a preLaunchTask to one of them, which allows us to have the option of running Rancher on a pre-existing cluster or a fresh cluster while debugging.

First, create a new task.json file if one does not already exist. To do this we can open the quick menu with CMD-SHFT-P || CTRL-SHFT-P type and select Configure Task then select Create tasks.json file from template entry then select Other. Replace the example task with the following task and save the file.

{
    "label": "k3d-reset",
    "type": "shell",
    "command": "KUBECONFIG=${userHome}/vscode-kubeconfig.yaml k3d cluster delete vscode-cluster;KUBECONFIG=${userHome}/vscode-kubeconfig.yaml k3d cluster create vscode-cluster",
    "problemMatcher": [],
    "group": {
        "kind": "build",
        "isDefault": true
    }
},

Open your launch.json CMD-p || CTRL-p and type launch.json. Update the replace the Run Rancher target with the following json. This will give you two debug options Run Rancher, which will run Rancher on a fresh cluster. and Only Run Rancher, which will run Rancher but not reset your cluster.

{
    "name": "Run Rancher",
    "type": "go",
    "request": "launch",
    "mode": "debug",
    "program": "main.go",
    "env": {
        "KUBECONFIG": "${userHome}/vscode-kubeconfig.yaml",
        "CATTLE_DEV_MODE": "30",
        "CATTLE_SYSTEM_CHART_DEFAULT_BRANCH": "release-v2.7",
        "CATTLE_BOOTSTRAP_PASSWORD": "<admin_password>",
    },
    "output": "rancher_debug",
    "args": [
        "--trace=false",
        "--add-local=true",
        "--no-cacerts"
    ],
    "preLaunchTask": "k3d-reset"
},
{
    "name": "Only Run Rancher",
    "type": "go",
    "request": "launch",
    "mode": "debug",
    "program": "main.go",
    "env": {
        "KUBECONFIG": "${userHome}/vscode-kubeconfig.yaml",
        "CATTLE_DEV_MODE": "30",
        "CATTLE_SYSTEM_CHART_DEFAULT_BRANCH": "release-v2.7",
        "CATTLE_BOOTSTRAP_PASSWORD": "<admin_password>",
    },
    "output": "rancher_debug",
    "args": [
        "--trace=false",
        "--add-local=true",
        "--no-cacerts"
    ]
},

Changing to rancher-machine

When you are adding a new cluster, you might not see all of the drivers (for e.g. Digital Ocean). To see all the drivers to create a cluster on different cloud providers, switch to rancher-machine by following instructions on this page. Ensure rancher-machine --version doesn't fail (returns something like rancher-machine version dev, build HEAD).

Changing the password

You have the option here to change the password (from the default of admin). If you are running rancher on AWS or any other external hosting, or it in any way is available to the outside world, you must change this, or you will have an extremely bad and expensive time, with many large unwanted nodes and workloads spun up in short order. Note, however, that the tests expect the default username/password combo of admin/admin, and so if you are running in a way that the instance is not available to the outside world and does not have any production keys, you can simply re-enter the password as admin

Preventing exposure of API Keys and other sensitive information

git-secrets is useful for preventing accidental exposure of sensitive information when committing code. On MacOS run brew install git-secrets Then add hooks to the repo

cd /path/to/my/repo
git secrets --install
git secrets --register-aws

ngrok

If you are running through ngrok, make sure to go to the settings tab and change the server-url field to match your ngrok https forwarding address

Setting up and running the legacy Python Tests

Install Dependencies

  • Install rancher-helm

    • Clone https://github.com/rancher/helm
    • Change to rancher-2.14 branch (this might change in future, check repo)
    • Run GO111MODULE="off" make bootstrap build
    • Rename bin/tiller & bin/helm to bin/rancher-tiller & bin/rancher-helm
    • Copy bin/rancher-tiller & bin/rancher-helm to /usr/local/bin and chmod u+x
    • Alternatively you can run make build-cross and use _dist/darwin-amd64/rancher-tiller

  • Install rancher-machine

  • Install Python 3.7

    On mac it can also be installed via homebrew. See here. Just running brew install python should get you there. If pip or pip3 isn't available after installing via homebrew, try running brew postinstall python.

  • Upgrade pip

    sudo pip3 install --upgrade pip

  • install virtualenv

    sudo pip3 install virtualenv

  • create a virualenv directory

    You can place this wherever you choose, but the rest of the docs and the scripts below will assume it is placed at $HOME/.venv/rancher

    mkdir -p ~/.venv/rancher
virtualenv -p python3 ~/.venv/rancher

  • Activate the virtual environment

    source ~/.venv/rancher/bin/activate

    To deactivate, run deactivate. There is a hook below in the scripts section to handle this for you automatically, assuming you followed the setup outlined in this document

  • Install tox

    Rancher uses tox for running tests

    pip install tox

  • Run the tests

    cd tests/integration/
tox

hints: make sure the password for admin is also admin

Gotchas

panic: creating CRD store customresourcedefinitions.apiextensions.k8s.io is forbidden: User "system:anonymous" cannot list customresourcedefinitions.apiextensions.k8s.io at the cluster scope Check your kubectl context

Firefox can’t establish a connection to the server at wss://$YOUR_NAME_HERE/v3/subscribe?sockId=1. Firefox has a bug with self-signed certificates on Web Sockets as of March 2023.

Next Steps

Provisioning a cluster

After you have a locally running Rancher instance, you can use it to provision a cluster in a cloud provider such as GKE or Digital Ocean. See the following documentation: https://rancher.com/docs/rancher/v2.x/en/cluster-provisioning/

Local setup

Since you are working with a local instance, you need to setup ngrok which will allow non-local resources to access it: ngrok http https://localhost:8443, then view the printed link in your browser as https: https://xyz.ngrok.io/ and make sure you can login. Finally go to settings -> server-url and add that url there.

Linode

Linode follows the same track as other Rancher launched providers such as Digital Ocean, however it needs an updated driver. Click Tools -> Drivers and then Node Drivers. Deactivate (or delete) the existing Linode driver and click Add Node Driver, then input the following:

Click Create, then go back to Global -> Clusters and hit Add Cluster. You should see Linode now. If you have any more problems try deactivating/activating again to get it to register.

Rancher Development Overview

https://github.com/rancher/rancher/wiki/Rancher-2.x-Development-Overview

Learning Resources

The best place to learn about

Rancher 2.x has been built using Kubernetes with heavy use of Custom Resources. The following videos might be helpful to get started with CRDs.

Clone this wiki locally