Skip to content

Setting Up k3s on Linux: Quick Tips to User-Friendly Kubernetes

Lightweight K8s distributions have been a game changer for approaching container orchestration in development environments. k3s, Rancher's minimal Kubernetes distribution, stands out for its simplicity and resource efficient packaging. The installation process is remarkably straighforward. However, configuring it for seamless multi-user development requires some additional considerations.

In this post, I'll walk you through deploying k3s on a Fedora Linux VM and configuring it for non-root user access.

Why k3s, and Why Fedora Linux?

k3s strips away many complexities found in full Kubernetes distributions but keeps a great API compatibility. Fedora Linux is mostly for practice in a RHEL-like environment, and it includes a modern package management system (dnf and RPM based) as well as systemd integration. Other Linux distributions should work as well.

Overall, k3s + Fedora Linux is an ideal platform for:

  • local development and homelab environments
  • CI/CD pipeline testing and experimentation
  • Kubernetes learning and experimentation
  • Resource-constrained deployments

The Easy Part: Installation

To install k3s, follow the most simple process true to it's name. A single command handles everything:

sudo curl -sFl https://get.k3s.io | sh -

You can always provide options to the above command for more advanced installations

Out of the box, this script will automatically:

  • Download and install the k3s binary
  • Create the systemd service for cluster management
  • Install kubectl for cluster interaction
  • Generate the kubeconfig file at /etc/rancher/k3s/k3s.yaml
  • Start the k3s systemd service

Next Step: Verify Your Cluster

After installation it's always a good idea to confirm the cluser is running properly:

# Check the k3s systemd service status
systemctl status k3s.service

# Verify cluster and node status
sudo kubectl get nodes
sudo kubectl cluster-info

You'll know it's running properly when you see a "Ready" state for the cluster.

The kubeconfig Challenge

Here is where real-world usage begins, and most tutorials will skip over. The default k3s installation creates several challenges for development workflows:

Root Ownership Issues

The kubeconfig file at /etc/rancher/k3s/k3s.yaml is owned by root with restrictive permissions, which makes it inaccessible to regular user accounts.

Localhost Binding

The generated kubeconfig uses 127.0.0.1 as the API server address, which works for root-level access but creates problems when:

  • Accessing the cluster from external tools
  • Running kubectl from non-root user contexts
  • Integrating with development CI/CD systems

*It's the 2nd one I'm focusing on specifically for this post

The User-Friendly Access Config

We need to make the kubeconfig accessible to regular users and properly configure for network access. This creates the seamless development experience we are after.

Step 1: Create a User-Scoped kubeconfig:

# Create the standard kubectl configuration directory
mkdir -p ~/.kube

# Copy the k3s kubeconfig to your user directory
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config

# Update ownership to your user account
sudo chown $(id -u):$(id -g) ~/.kube/config

Step 2: Update IP Configuration:

# Replacing 127.0.0.1 with your VM's IP address
sed -i 's/127.0.0.1/<your-vm-ip>/' ~/.kube/config

*You can find your VM's IP using ip a

Step 3: Configure Environment Variables:

Set the KUBECONFIG environment variable to point to the new user-specific configuration.

# Set for current session
export KUBECONFIG=~/.kube/config

# Make permanent by adding to your shell profile
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc
source ~/.bashrc

Step 4: Verify User Access:

Run the following as your regular, non-root user:

kubectl get nodes
kubectl cluster-info

Troubleshooting Common Issues

If you encounter permission errors for your user-specified kubeconfig at ~/.kube/config then check file ownership and permissions:

ls -la ~/.kube/config
# Should show your username as owner with read/write permissions

Wrapping Everything Up

The k3s installation is remarkably simple, but creating a development environment requires thoughtful configuration. Make sure to properly setup user-scoped kubeconfig files and network accessibility. That's how you transform a basic k3s installation into a powerful, user-friendly Kubernetes development and experimentation platform.

This approach scales well from solo development work to team environments, providing a solid foundation for k8s experimentation and development without the overhead of full-scale cluster deployments.