K3s remote kubeconfig management plugin for quick multiple k3s cluster configurations. Perfect for managing multiple Kubernetes clusters.

k3s.plugin.sh

#!/bin/bash

# This plugin provides convenient functions to
# fetch and manage kubeconfig files from remote k3s clusters.
# It simplifies the process of connecting to multiple k3s clusters
# by automatically retrieving, modifying, and loading kubeconfig files
# from remote servers.

k3s-save-remote-config() {
    USER=$1 
    HOSTNAME=$2 
    ALIAS=$3
    PORT=${4:-"22"}

    ssh -p $PORT "$USER@$HOSTNAME" \
        'cat /etc/rancher/k3s/k3s.yaml' |\
        sed -E "s/([^-] name|cluster|current-context): default/\1: $ALIAS/" |\
        sed "s/127.0.0.1/$HOSTNAME/" |\
        tee "$HOME/.kube/config.$ALIAS.yaml"

    echo "Kubeconfig saved to $HOME/.kube/config.$ALIAS.yaml"
}

k3s-load-remote-config() {
    USER=$1 
    HOSTNAME=$2 
    ALIAS=$3
    PORT=${4:-"22"}

    k3s-save-remote-config "$USER" "$HOSTNAME" "$ALIAS" "$PORT" >/dev/null 2>&1
    export KUBECONFIG="$HOME/.kube/config.$ALIAS.yaml"

    echo "KUBECONFIG set to $HOME/.kube/config.$ALIAS.yaml"
    echo "Now using context: $ALIAS"
    echo ""

    kubectl config get-contexts
}

K3s Remote Config Plugin

Overview

This plugin provides convenient functions to fetch and manage kubeconfig files from remote k3s clusters. It simplifies the process of connecting to multiple k3s clusters by automatically retrieving, modifying, and loading kubeconfig files from remote servers.

The plugin includes two main functions:

• k3s-save-remote-config - Downloads and saves the kubeconfig from a remote k3s server
• k3s-load-remote-config - Downloads, saves, and immediately loads the kubeconfig for use

Requirements

• SSH access to the remote k3s server
• sed command-line tool (available on Linux and macOS by default)
• kubectl command-line tool (required for k3s-load-remote-config)
• bash or zsh shell
• Proper permissions to read /etc/rancher/k3s/k3s.yaml on the remote server

Note

This script works on both Linux and macOS, as it uses standard Unix utilities.

Installation

1. Download the Script

Download k3s.plugin.sh and save it to a convenient location, such as:

• ~/scripts/k3s.plugin.sh
• ~/.local/bin/k3s.plugin.sh
• Or any directory you prefer

2. Source the Plugin

The script is designed as a shell plugin, so you need to source it into your shell to use the functions.

For permanent availability (add to your shell's RC file):

For Zsh users (~/.zshrc):

source ~/scripts/k3s.plugin.sh

For Bash users (~/.bashrc or ~/.bash_profile):

source ~/scripts/k3s.plugin.sh

For one-time use (current session only):

source /path/to/k3s.plugin.sh

After sourcing, reload your shell configuration:

source ~/.zshrc  # for zsh
# or
source ~/.bashrc  # for bash

Usage

k3s-save-remote-config

Fetches the kubeconfig from a remote k3s server and saves it locally without changing your current context.

Syntax:

k3s-save-remote-config <USER> <HOSTNAME> <ALIAS> [PORT]

Parameters:

• USER - SSH username for the remote server
• HOSTNAME - Hostname or IP address of the remote k3s server
• ALIAS - Friendly name for the cluster (used in kubeconfig)
• PORT - SSH port (optional, defaults to 22)

Examples:

# Basic usage with default SSH port (22)
k3s-save-remote-config root 192.168.1.100 production

# Using a custom SSH port
k3s-save-remote-config admin k3s.example.com staging 2222

# Using a non-root user
k3s-save-remote-config ubuntu 10.0.0.50 dev-cluster

The kubeconfig will be saved to ~/.kube/config.<ALIAS>.yaml

k3s-load-remote-config

Fetches the kubeconfig from a remote k3s server, saves it locally, and immediately sets it as the active kubeconfig.

Syntax:

k3s-load-remote-config <USER> <HOSTNAME> <ALIAS> [PORT]

Parameters:

• Same as k3s-save-remote-config

Examples:

# Connect to production cluster
k3s-load-remote-config root 192.168.1.100 production

# Connect to staging with custom port
k3s-load-remote-config admin k3s.example.com staging 2222

After running this command, your KUBECONFIG environment variable will be set to the downloaded config, and you can immediately use kubectl commands.

How It Works

k3s-save-remote-config

1. Connects to the remote server via SSH
2. Reads the k3s kubeconfig file from /etc/rancher/k3s/k3s.yaml
3. Modifies the config to:
   • Replace the default cluster name with your specified alias
   • Replace 127.0.0.1 with the actual remote hostname
   • Update the context name to match the alias
4. Saves the modified config to ~/.kube/config.<ALIAS>.yaml

k3s-load-remote-config

1. Performs all steps from k3s-save-remote-config
2. Exports KUBECONFIG environment variable to point to the new config
3. Displays the available contexts using kubectl config get-contexts

Managing Multiple Clusters

You can save multiple cluster configurations and switch between them:

# Save configs from multiple clusters
k3s-save-remote-config root 192.168.1.100 production
k3s-save-remote-config root 192.168.1.101 staging
k3s-save-remote-config root 192.168.1.102 development

# Switch between clusters
export KUBECONFIG=~/.kube/config.production.yaml
# or
k3s-load-remote-config root 192.168.1.100 production

# Merge multiple configs (optional)
export KUBECONFIG=~/.kube/config.production.yaml:~/.kube/config.staging.yaml
kubectl config view --flatten > ~/.kube/config

Troubleshooting

Error: "Permission denied (publickey)"

• Ensure you have SSH access to the remote server
• Check that your SSH key is properly configured
• Verify the username is correct

Error: "cat: /etc/rancher/k3s/k3s.yaml: Permission denied"

• The user needs read access to /etc/rancher/k3s/k3s.yaml
• Try using root user or a user with appropriate sudo permissions
• Some k3s installations may require: ssh user@host 'sudo cat /etc/rancher/k3s/k3s.yaml'

Error: "command not found: kubectl"

• Install kubectl: Kubernetes documentation
• On Linux: Use your package manager (apt, yum, etc.)
• On macOS: brew install kubectl

Error: "ssh: connect to host port : Connection refused"

• Verify the hostname/IP address is correct
• Check that the SSH port is correct (default: 22)
• Ensure the remote server is running and accessible

KUBECONFIG not persisting across sessions

• The export KUBECONFIG only affects the current shell session
• To make it permanent, add it to your ~/.zshrc or ~/.bashrc
• Alternatively, merge the config into your default ~/.kube/config

Security Considerations

• The downloaded kubeconfig files contain sensitive credentials
• Ensure proper file permissions: chmod 600 ~/.kube/config.*.yaml
• Never commit kubeconfig files to version control
• Consider using SSH key-based authentication instead of passwords
• Regularly rotate credentials and update kubeconfig files

Additional Tips

Set up SSH config for easier access:

Add to ~/.ssh/config:

Host prod-k3s
    HostName 192.168.1.100
    User root
    Port 22
    IdentityFile ~/.ssh/id_rsa

Then use:

k3s-load-remote-config root prod-k3s production

Create aliases for frequent clusters:

Add to your shell RC file:

alias load-k3s-prod='k3s-load-remote-config root 192.168.1.100 production'
alias load-k3s-staging='k3s-load-remote-config root 192.168.1.101 staging'
alias load-k3s-dev='k3s-load-remote-config root 192.168.1.102 development'