Sổ tay kỹ thuật

k3s single node – cài đặt, Traefik, local-path, gỡ bỏ

how-to#kubernetes#k3s#linux· cập nhật 2026-11-06

Dùng khi cần một cluster Kubernetes nhẹ trên một máy (lab, edge, VPS) với k3s, có sẵn Traefik ingress, ServiceLB và local-path storage.

Sửa trang này
Mục lục

Tóm tắt: Ghi /etc/rancher/k3s/config.yaml trước, rồi curl -sfL https://get.k3s.io | sh -. k3s là một binary chứa control plane, containerd, Flannel, CoreDNS, Traefik (ingress), ServiceLB (LoadBalancer bằng host port), local-path-provisioner và metrics-server. Kubeconfig ở /etc/rancher/k3s/k3s.yaml. Gỡ bằng /usr/local/bin/k3s-uninstall.sh.

Luồng hoạt động

flowchart LR
  C["Client :80/:443"] --> SLB["ServiceLB (svclb, host port)"]
  SLB --> T["Traefik (kube-system)"]
  T -->|"Ingress rule"| S["Service app"]
  S --> P["Pod"]
  P --> PVC["PVC local-path"]
  PVC --> D["/var/lib/rancher/k3s/storage"]

Cấu hình

Cài đặt

/etc/rancher/k3s/config.yaml
write-kubeconfig-mode: "0640"
tls-san:
  - k3s.example.com              # tên/IP sẽ dùng để gọi API từ máy khác
  - 203.0.113.10
node-name: lab-01
# disable:                       # bỏ comment nếu muốn tự cài ingress / LB khác
#   - traefik
#   - servicelb
sudo mkdir -p /etc/rancher/k3s   # rồi tạo config.yaml như trên
curl -sfL https://get.k3s.io | sh -
 
# Ghim phiên bản / kênh (nên làm cho môi trường cần lặp lại được)
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.31.4+k3s1" sh -
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -
 
sudo systemctl status k3s
sudo k3s kubectl get nodes -o wide
sudo k3s check-config            # kiểm tra kernel/cgroup khi k3s không lên

Tham số trong config.yaml tương ứng flag của k3s server (vd disable: [traefik] ≡ --disable=traefik). Đổi config thì sudo systemctl restart k3s.

Kubeconfig

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config && sudo chown "$USER": ~/.kube/config
chmod 600 ~/.kube/config
kubectl get pods -A
 
# Dùng từ máy khác: đổi server 127.0.0.1 thành tên đã có trong tls-san
sed -i 's#https://127.0.0.1:6443#https://k3s.example.com:6443#' ~/.kube/config

k3s.yaml chứa client cert quyền cluster-admin. Đừng write-kubeconfig-mode: "0644" trên máy nhiều user.

Traefik mặc định

app-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app
  namespace: app
spec:
  ingressClassName: traefik
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: app
                port:
                  number: 80

Traefik được cài bằng HelmChart trong kube-system. Không sửa file trong /var/lib/rancher/k3s/server/manifests/traefik.yaml (k3s ghi đè khi khởi động); tuỳ biến bằng HelmChartConfig:

/var/lib/rancher/k3s/server/manifests/traefik-config.yaml
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    logs:
      access:
        enabled: true

TLS tự động cho Ingress: cài cert-manager như ở ingress-nginx + cert-manager, đổi ingressClassName/class của solver thành traefik.

Storage local-path

pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
  namespace: app
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi

StorageClass local-path là mặc định, tạo thư mục trên node dưới /var/lib/rancher/k3s/storage. Dung lượng 5Gi không được giới hạn thật; dữ liệu gắn với node, không có replication. Binding mode WaitForFirstConsumer: PVC Pending tới khi có Pod dùng nó là bình thường.

Thông tin hữu ích

Mục Giá trị / lệnh
Log journalctl -u k3s -f
Container runtime sudo k3s crictl ps / sudo k3s crictl images
Token để join agent /var/lib/rancher/k3s/server/node-token
Join thêm node agent curl -sfL https://get.k3s.io | K3S_URL=https://k3s.example.com:6443 K3S_TOKEN=<token> sh -
Pod CIDR / Service CIDR mặc định 10.42.0.0/16 / 10.43.0.0/16
Port cần mở TCP 6443 (API), TCP 10250 (kubelet, giữa các node), UDP 8472 (Flannel VXLAN, giữa các node)
Manifest tự apply khi khởi động Thả file YAML vào /var/lib/rancher/k3s/server/manifests/
Snapshot datastore sudo k3s etcd-snapshot save (chỉ khi chạy embedded etcd với cluster-init: true; mặc định single node dùng SQLite tại /var/lib/rancher/k3s/server/db/)

Gỡ bỏ

/usr/local/bin/k3s-killall.sh        # dừng mọi container, xoá network interface, giữ dữ liệu
/usr/local/bin/k3s-uninstall.sh      # gỡ server: xoá binary, service, /etc/rancher/k3s, /var/lib/rancher/k3s
/usr/local/bin/k3s-agent-uninstall.sh   # trên node agent

k3s-uninstall.sh xoá luôn /var/lib/rancher/k3s, bao gồm dữ liệu local-path PVC. Backup trước.

Lỗi thường gặp

Triệu chứng Nguyên nhân Cách xử lý
kubectl báo permission denied đọc /etc/rancher/k3s/k3s.yaml File mode 0600 mặc định Copy sang ~/.kube/config như trên, hoặc chạy sudo k3s kubectl
Từ máy khác báo x509: certificate is valid for 127.0.0.1, ... not k3s.example.com Tên/IP chưa có trong tls-san Thêm vào tls-san, restart k3s (cert được sinh lại)
Service LoadBalancer EXTERNAL-IP <pending> Port 80/443 trên host đã bị nginx/apache chiếm, hoặc đã disable servicelb ss -ltnp | grep -E ':80|:443', kubectl get pods -n kube-system | grep svclb
Pod không gọi được DNS/Service, node khác không thông firewalld/ufw chặn traffic Pod/Service CIDR hoặc VXLAN Cho phép 10.42.0.0/16, 10.43.0.0/16 và UDP 8472, hoặc tắt firewalld theo khuyến nghị của k3s
PVC mãi Pending Chưa có Pod dùng (WaitForFirstConsumer) Tạo Pod/Deployment mount PVC
Sửa traefik.yaml trong thư mục manifests bị mất k3s ghi đè file packaged khi khởi động Dùng HelmChartConfig
k3s không start, log báo cgroup Kernel/cgroup thiếu (Raspberry Pi cần cgroup_memory=1 cgroup_enable=memory) k3s check-config

Tham khảo