Quick Rancher Deployment

The following Docker command launches a Rancher server instance with certificate mounting. If you lack custom certificates, remove the volume mount options—Rancher will automatically generate self-signed certificates.

docker run -d --name rancher-server --privileged --restart=unless-stopped \
    -p 10080:80 -p 10443:443 \
    -v /opt/certs/rancher.example.com.crt:/etc/rancher/ssl/cert.pem \
    -v /opt/certs/rancher.example.com.key:/etc/rancher/ssl/key.pem \
    -v /opt/certs/ca-chain.pem:/etc/rancher/ssl/cacerts.pem \
    rancher/rancher:v2.7.5

Accessing the Rancher Interface

Once the container starts, access the web UI at https://<server-ip>:10443. The initial boot process takes approximately 30 seconds. Ensure your firewall rules permit traffic on port 10443 before attempting to connect.

Obtaining the Bootstrap Password

After reaching the login page, retrieve the default bootstrap password from the container logs:

docker logs rancher-server 2>&1 | grep "Bootstrap Password:"

Use these credentials to authenticate. Upon first login, Rancher prompts you to set a new admin password.

Creating a New Kubernetes Cluster

After authentication, navigate to the cluster management dashboard and initiate a new cluster deployment. On the cluster configuration screen, enable the option to trust insecure certificates when using self-signed certificates for communication.

Rancher generates a registration command specific to your cluster configuration. Copy this command and execute it on each target node where you want to install Kubernetes. For a typical 4-core, 8GB RAM node, the complete installation process finishes within five minutes.

Monitoring Installation Progress

During cluster provisioning, observe the installation logs for real-time status updates. Temporary error messages may appear—this is normal behavier as the system adjusts configurations. Avoid manual intervention unless logs remain static for extended periods exceeding one minute.

docker logs -f rancher-server

Once all nodes transition to Active status, your Kubernetes cluster is fully operational and ready for workload deployment.

Troubleshooting: Nodes Stuck in Update State

If nodes remain in Update status after executing the registration command, a stale configuration conflict typically causes the issue. Follow these remediation steps:

1. Remove the affected nodes from the Rancher interface
2. Delete the cluster configuration from Rancher's cluster management
3. Execute the cleanup script on each target node

For K3s-based clusters, locate and run the uninstallation scripts:

/usr/local/bin/k3s-uninstall.sh
/usr/local/bin/rancher-system-agent-uninstall.sh

For RKE2 deployments, locate the equivalent uninstallation script using the same pattern:

# Find the RKE2 uninstall script
find /usr/local/bin -name "*rke2*uninstall*" -type f

Uninstallation Scripts Reference

These scripts are automatically generated during cluster registration. Save them locally for disaster recovery scenarios.

K3s Uninstall Script

#!/bin/bash
set -x
[ $(id -u) -eq 0 ] || exec sudo "$0" "$@"

/usr/local/bin/k3s-killall.sh

if command -v systemctl &>/dev/null; then
    systemctl disable k3s
    systemctl reset-failed k3s
    systemctl daemon-reload
fi

if command -v rc-update &>/dev/null; then
    rc-update delete k3s default
fi

rm -f /etc/systemd/system/k3s.service
rm -f /etc/systemd/system/k3s.service.env

cleanup_handler() {
    rm -f /usr/local/bin/k3s-uninstall.sh
}
trap cleanup_handler EXIT

if (ls /etc/systemd/system/k3s*.service 2>/dev/null || ls /etc/init.d/k3s* 2>/dev/null); then
    set +x; echo 'Additional k3s services detected, skipping complete uninstall'; set -x
    exit
fi

for executable in kubectl crictl ctr; do
    if [ -L "/usr/local/bin/$executable" ]; then
        rm -f "/usr/local/bin/$executable"
    fi
done

rm -rf /etc/rancher/k3s
rm -rf /run/k3s
rm -rf /var/lib/rancher/k3s
rm -rf /var/lib/kubelet
rm -f /usr/local/bin/k3s
rm -f /usr/local/bin/k3s-killall.sh

if command -v yum &>/dev/null; then
    yum remove -y k3s-selinux
    rm -f /etc/yum.repos.d/rancher-k3s-common*.repo
elif command -v rpm-ostree &>/dev/null; then
    rpm-ostree uninstall k3s-selinux
    rm -f /etc/yum.repos.d/rancher-k3s-common*.repo
elif command -v zypper &>/dev/null; then
    removal_cmd="zypper remove -y k3s-selinux"
    if [ "${TRANSACTIONAL_UPDATE:-false}" != "true" ] && [ -x /usr/sbin/transactional-update ]; then
        removal_cmd="transactional-update --no-selfupdate -d run $removal_cmd"
    fi
    $removal_cmd
    rm -f /etc/zypp/repos.d/rancher-k3s-common*.repo
fi

Rancher System Agent Uninstall Script

#!/bin/bash

if [ ! $(id -u) -eq 0 ]; then
    echo "[ERROR] This script requires root privileges." >&2
    exit 1
fi

# Configuration defaults
export CATTLE_AGENT_CONFIG_DIR="${CATTLE_AGENT_CONFIG_DIR:-/etc/rancher/agent}"
export CATTLE_AGENT_VAR_DIR="${CATTLE_AGENT_VAR_DIR:-/var/lib/rancher/agent}"
export CATTLE_AGENT_BIN_PREFIX="${CATTLE_AGENT_BIN_PREFIX:-/usr/local}"

log_warn() {
    echo "[WARN]" "$@" >&2
}

verify_mountpoint() {
    mountpoint -q "${CATTLE_AGENT_BIN_PREFIX}"
}

verify_readonly() {
    touch "${CATTLE_AGENT_BIN_PREFIX}"/.rsa-writable-test && rm -rf "${CATTLE_AGENT_BIN_PREFIX}"/.rsa-writable-test
    test $? -ne 0
}

adjust_prefix() {
    if [ -z "${ORIGINAL_PREFIX:-}" ]; then
        ORIGINAL_PREFIX="${CATTLE_AGENT_BIN_PREFIX}"
        if verify_mountpoint || verify_readonly; then
            export CATTLE_AGENT_BIN_PREFIX="/opt/rancher-system-agent"
            log_warn "/usr/local is read-only or a mount point; using ${CATTLE_AGENT_BIN_PREFIX}"
        fi
    fi
}

stop_services() {
    if command -v systemctl &>/dev/null; then
        systemctl stop rancher-system-agent 2>/dev/null || true
    fi
}

disable_services() {
    if command -v systemctl &>/dev/null; then
        systemctl disable rancher-system-agent 2>/dev/null || true
        systemctl reset-failed rancher-system-agent 2>/dev/null || true
        systemctl daemon-reload
    fi
}

remove_agent_script() {
    rm -f "${CATTLE_AGENT_BIN_PREFIX}/bin/rancher-system-agent-uninstall.sh"
}

cleanup_files() {
    rm -f /etc/systemd/system/rancher-system-agent.service
    rm -f /etc/systemd/system/rancher-system-agent.env
    rm -rf "${CATTLE_AGENT_VAR_DIR}"
    rm -rf "${CATTLE_AGENT_CONFIG_DIR}"
    rm -f "${CATTLE_AGENT_BIN_PREFIX}/bin/rancher-system-agent"
}

adjust_prefix
stop_services
trap remove_agent_script EXIT
disable_services
cleanup_files