Installing k3s on Fedora: a single-node cluster with domestic mirrors

Before installing Kubernetes on Fedora, know this: the repositories ship neither k3s nor kind.

dnf search --available kind k3s

Nothing. So the upstream install script is the only route, which makes a domestic mirror essential.

Installing k3s through the domestic mirror

k3s publishes a China mirror for both the script and the binaries:

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh -o k3s-install.sh
ls -l k3s-install.sh

38251

Run it with the mirror flag:

sudo INSTALL_K3S_MIRROR=cn sh k3s-install.sh

The script reports each step:

[INFO]  Creating uninstall script /usr/local/bin/k3s-uninstall.sh
[INFO]  env: Creating environment file /etc/systemd/system/k3s.service.env
[INFO]  systemd: Creating service file /etc/systemd/system/k3s.service
[INFO]  systemd: Enabling k3s unit
Created symlink '/etc/systemd/system/multi-user.target.wants/k3s.service' → '/etc/systemd/system/k3s.service'.
[INFO]  systemd: Starting k3s

k3s brings its own systemd service, active immediately:

systemctl is-active k3s
k3s --version

active
k3s version v1.36.5+k3s1 (3dd98cc5)

The first kubectl call hits permission denied

error: error loading config file "/etc/rancher/k3s/k3s.yaml": open /etc/rancher/k3s/k3s.yaml: permission denied

The kubeconfig is root-only:

ls -l /etc/rancher/k3s/k3s.yaml

-rw-------. root root

Two ways out.

1. Use sudo (fastest)

sudo kubectl get nodes

NAME        STATUS   ROLES           AGE   VERSION
fd45-repo   Ready    control-plane   76s   v1.36.5+k3s1

2. Copy the kubeconfig into your home (for daily use)

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER ~/.kube/config
kubectl get nodes

Tip

You can also install with --write-kubeconfig-mode 644, but that opens cluster administration to every user. Fine on a throwaway lab box, not on a shared machine.

What runs out of the box

sudo kubectl get pods -A

NAMESPACE     NAME                                      READY   STATUS              RESTARTS   AGE
kube-system   coredns-7cfb7bc9c7-ckx4n                  0/1     ContainerCreating   0          71s
kube-system   helm-install-traefik-crd-b8hss            0/1     ContainerCreating   0          71s
kube-system   helm-install-traefik-hwhd4                0/1     ContainerCreating   0          71s

ContainerCreating right after install is normal — k3s is orchestrating itself, pulling the system components (CoreDNS, Traefik ingress) into containerd.

A minute or two later they turn Running:

watch -n 5 sudo kubectl get pods -A

Component	Role
coredns	in-cluster DNS
traefik	default ingress controller
local-path-provisioner	default StorageClass
metrics-server	backs kubectl top

k3s packs all of that into a single ~70 MB binary, which is why it fits a 4 GB single-node box while kubeadm does not.

Running a workload

sudo kubectl create deployment hello --image=nginx
sudo kubectl expose deployment hello --port=80 --type=NodePort
sudo kubectl get svc hello

NodePort allocates a port in 30000–32767, reachable at the node IP plus that port.

Caution

NodePort ports are not open in firewalld by default. Add them with firewall-cmd --add-port, or only localhost on the node can reach the service.

Uninstalling

k3s drops an uninstaller:

sudo /usr/local/bin/k3s-uninstall.sh

It stops the service, removes the unit, and clears /var/lib/rancher/k3s and the container data. Make sure no workload needs preserving first.

Why not kind

kind needs Docker or Podman to host its “node containers”, which is one extra layer on Fedora. For single-node experiments k3s is simpler:

Option	Dependency	Fits
k3s (this page)	none, ships containerd	single-node labs, edge, light production
kind	Docker/Podman	CI clusters, multi-node topology tests
minikube	a driver (podman/docker/kvm)	full Kubernetes feature validation

Common traps

Symptom	Cause
kubectl cannot read the kubeconfig	file is 0600 root; use sudo or copy to ~/.kube/config
pods stuck in ContainerCreating	still pulling images; wait a minute or two
image pulls slow or failing	containerd has no registry mirror; see domestic mirrors
memory pressure after install	leave at least 2 GB free, 4 GB is comfortable
k3s restart-loops	journalctl -u k3s -n 50, usually port 6443 taken

Related pages

• Podman in practice — container basics
• Containerfile and builds — building your own images
• Domestic mirrors — mirrors and registry acceleration
• firewalld — opening NodePort ranges
• Official: k3s documentation