K3s is a lightweight Kubernetes distribution that’s easy to install and manage, but accessing it remotely with kubectl can be a bit tricky if you’re not familiar with how it handles its configuration.
Let’s say you’ve got K3s running on a server, and you want to manage it from your laptop. You’ve probably got a kubeconfig file on the K3s server, but how do you get that onto your local machine and make it work?
Here’s what a typical kubeconfig file for K3s looks like. This one is for a single-node setup, but the principles extend to multi-node clusters.
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURnekNDQWxR...
server: https://192.168.1.100:6443
name: default
contexts:
- context:
cluster: default
user: default
name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
user:
client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tC...
client-key-data: LS0tLS1CRUdJTiBSU0sgUFJJVkFURSBLRVktLS0tLQpNSUlFb2dJQk...
The server field points to the Kubernetes API endpoint. In this example, it’s https://192.168.1.100:6443. The certificate-authority-data, client-certificate-data, and client-key-data are base64 encoded TLS certificates and keys used for authentication and secure communication.
The magic of K3s’s configuration is that it bundles everything you need into a single file, typically located at /etc/rancher/k3s/k3s.yaml on the server.
Here’s the most surprising thing: K3s’s k3s.yaml is already a fully functional kubeconfig file. You don’t need to generate new certificates or create complex configurations from scratch. You just need to get this file to your local machine and tell kubectl where to find it.
Let’s see this in action. Imagine you’re on your laptop, and you want to check the status of pods on your K3s server.
First, you need to copy the k3s.yaml file from your K3s server to your local machine. You can use scp for this:
scp user@k3s-server-ip:/etc/rancher/k3s/k3s.yaml ./k3s-remote.yaml
Replace user with your SSH username on the K3s server and k3s-server-ip with the IP address or hostname of your K3s server. This command copies the file to your current directory as k3s-remote.yaml.
Now, you have the kubeconfig file locally. To use it with kubectl, you have two primary options.
Option 1: Temporarily set the KUBECONFIG environment variable.
This is great for quick, one-off commands or when you’re working with multiple clusters and want to switch easily without modifying your default configuration.
export KUBECONFIG=./k3s-remote.yaml
kubectl get nodes
The export KUBECONFIG=./k3s-remote.yaml command tells kubectl (and other Kubernetes tools) to use the specified file for configuration. When you run kubectl get nodes, it will use the credentials and API server address from k3s-remote.yaml.
Option 2: Merge the remote config with your local kubeconfig (if you have one).
If you already have a ~/.kube/config file from other Kubernetes clusters, you can merge the K3s configuration into it. This allows you to switch between clusters using kubectl config use-context.
First, you need to modify the server address in your copied k3s-remote.yaml if your K3s server is not directly accessible via its internal IP from your local machine. Often, the k3s.yaml file contains the server’s private IP. You’ll need to change this to the server’s public IP or a hostname that resolves to it.
Open k3s-remote.yaml in a text editor. Find the server: line under clusters:. It might look like this:
server: https://192.168.1.100:6443
Change 192.168.1.100 to the IP address or hostname that your laptop can actually reach. For example:
server: https://your-k3s-server-public-ip:6443
Once that’s updated, use KUBECONFIG to merge:
export KUBECONFIG=~/.kube/config:./k3s-remote.yaml
kubectl config view --flatten > ~/.kube/config.tmp
mv ~/.kube/config.tmp ~/.kube/config
kubectl config get-contexts
kubectl config use-context default # Or whatever context name is in k3s-remote.yaml
kubectl get pods -A
The export KUBECONFIG=~/.kube/config:./k3s-remote.yaml command tells kubectl to look for configuration in both files. The kubectl config view --flatten > ~/.kube/config.tmp command merges them into a single file, overwriting your default ~/.kube/config. Then, you can list contexts and switch to the K3s context.
What if the server IP is wrong?
If you run kubectl get nodes and get an error like connection refused or dial tcp <server-ip>:6443: connect: no route to host, the most likely culprit is that the server IP address in your kubeconfig file is incorrect or unreachable from your current network. Double-check the IP address and ensure your laptop can reach the K3s server on port 6443. You might need to adjust firewall rules or use a public IP/hostname.
What if certificate validation fails?
You might see errors like x509: certificate signed by unknown authority or certificate is not valid for requested server name. This usually means the server address in your kubeconfig doesn’t match the hostname or IP the certificate was issued for, or your local machine doesn’t trust the Certificate Authority (CA) that signed the K3s server’s certificate.
For K3s’s default self-signed certificates, you might need to update the server field to match the IP your laptop uses to connect. If you’re using a custom CA, ensure your local machine trusts it.
What if authentication fails?
Errors like Unauthorized or Forbidden indicate that the client certificate/key in your kubeconfig is not valid or doesn’t have the necessary permissions. K3s’s default k3s.yaml uses a client certificate that grants administrator privileges. If you’ve generated a new kubeconfig or are using a different user, ensure the associated certificates are correct and have the right roles.
The K3s server’s API is secured by default. The k3s.yaml file contains the necessary credentials for the default admin user. If you’ve generated a new kubeconfig or are trying to use a different user, you’ll need to ensure the client-certificate-data and client-key-data are correctly associated with a user that has permissions.
The one thing most people don’t realize is that the certificate-authority-data in k3s.yaml can be used to verify the server’s identity. If you’re encountering certificate errors, it’s often because the server address in the kubeconfig doesn’t match the hostname or IP in the server’s certificate, or your client machine doesn’t trust the CA that signed it. For simple setups, changing the server address to the IP your client uses is usually sufficient.
Once you’ve successfully configured your kubeconfig, the next step is often managing the K3s cluster itself, which might involve deploying applications using Helm or understanding how to scale your K3s deployment.