1. K3s单节点集群部署概述K3s作为轻量级Kubernetes发行版已经成为开发者本地测试和小型生产环境的首选方案。相比完整K8s动辄数GB的内存消耗K3s仅需512MB即可运行这种瘦身特性使其在边缘计算和资源受限场景中表现尤为突出。我最近在Rocky Linux 9.2系统上完成了最新版K3s的部署验证整个过程仅耗时8分钟比传统K8s集群节省了约75%的配置时间。单节点架构虽然牺牲了高可用性但对于开发测试、CI/CD流水线等场景已经足够。这种部署模式下所有控制平面组件API Server、Controller Manager、Scheduler等与工作节点共享同一台主机通过containerd替代Docker作为默认容器运行时进一步降低了资源开销。值得注意的是K3s v1.26之后版本对ARM架构的支持更加完善这使得在树莓派等设备上搭建微型K8s环境成为可能。2. 环境准备与系统配置2.1 硬件需求与操作系统选择最低配置要求CPUx86_64或ARM64架构双核内存1GB建议2GB以上磁盘20GB可用空间推荐操作系统版本# 查看系统版本示例 cat /etc/os-release我选择Rocky Linux 9.2作为基础系统主要考虑其与RHEL的二进制兼容性以及长期支持周期。关键配置步骤如下关闭Swap空间K8s的硬性要求sudo swapoff -a sudo sed -i / swap / s/^\(.*\)$/#\1/g /etc/fstab设置正确的hostname解析sudo hostnamectl set-hostname k3s-master echo 127.0.0.1 $(hostname) | sudo tee -a /etc/hosts加载内核模块sudo modprobe overlay sudo modprobe br_netfilter2.2 网络与防火墙配置Calico网络插件对内核参数有特定要求需提前配置cat EOF | sudo tee /etc/sysctl.d/k3s.conf net.bridge.bridge-nf-call-ip6tables 1 net.bridge.bridge-nf-call-iptables 1 net.ipv4.ip_forward 1 EOF sudo sysctl --system如果使用Firewalld需放行必要端口sudo firewall-cmd --permanent --add-port6443/tcp # Kubernetes API sudo firewall-cmd --permanent --add-port8472/udp # Flannel VXLAN sudo firewall-cmd --permanent --add-port10250/tcp # Kubelet API sudo firewall-cmd --reload3. K3s核心组件安装3.1 一键安装脚本解析官方提供的安装脚本实际上完成了以下关键操作curl -sfL https://get.k3s.io | sh -该脚本执行流程检测系统架构和发行版安装k3s-selinux策略包仅RHEL系下载k3s二进制和镜像到/var/lib/rancher/k3s生成systemd服务单元文件启动k3s服务并等待就绪高级安装选项示例禁用Traefik并使用外部数据库curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC--disable traefik --datastore-endpoint mysql://username:passwordtcp(hostname:3306)/database sh -3.2 关键组件定制配置通过环境变量可覆盖默认配置export INSTALL_K3S_VERSIONv1.26.4k3s1 export INSTALL_K3S_SKIP_STARTtrue export INSTALL_K3S_SYMLINKforce安装后配置文件位置主配置/etc/rancher/k3s/config.yamlkubeconfig/etc/rancher/k3s/k3s.yaml服务日志journalctl -u k3s -f4. 集群验证与组件管理4.1 基础功能测试获取节点状态kubectl get nodes -o wide验证核心Pod运行状态kubectl get pods -A -o wide测试服务部署示例部署Nginxkubectl create deployment nginx --imagenginx:alpine kubectl expose deployment nginx --port80 --typeNodePort kubectl get svc nginx4.2 插件管理实践K3s内置组件管理命令# 查看已安装组件 kubectl get deployments -n kube-system # 手动安装Metrics Server kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml持久化存储配置示例使用local-path-provisionerapiVersion: v1 kind: PersistentVolumeClaim metadata: name: local-path-pvc spec: accessModes: - ReadWriteOnce storageClassName: local-path resources: requests: storage: 2Gi5. 运维优化与故障排查5.1 性能调优参数启动参数优化示例# /etc/systemd/system/k3s.service.d/override.conf [Service] ExecStartPre-/sbin/sysctl -w vm.max_map_count262144 ExecStart ExecStart/usr/local/bin/k3s server \ --kubelet-argconfig/etc/rancher/k3s/kubelet.config \ --kube-controller-manager-argnode-monitor-grace-period20s \ --kube-apiserver-argdefault-not-ready-toleration-seconds30内存限制配置防止OOMapiVersion: v1 kind: Pod metadata: name: memory-demo spec: containers: - name: memory-demo-ctr image: polinux/stress resources: limits: memory: 200Mi requests: memory: 100Mi5.2 常见问题解决方案问题1coredns持续CrashLoopBackOff# 检查日志 kubectl logs -n kube-system coredns-xxxxxx # 典型解决方案修复网络插件配置 kubectl edit configmap -n kube-system coredns问题2节点NotReady状态# 诊断步骤 journalctl -u k3s -n 100 --no-pager kubectl describe node node-name问题3镜像拉取失败# 配置私有仓库 mkdir -p /etc/rancher/k3s/ cat EOF /etc/rancher/k3s/registries.yaml mirrors: docker.io: endpoint: - https://mirror.ccs.tencentyun.com EOF systemctl restart k3s6. 生产环境进阶配置6.1 高可用方案实现虽然本文聚焦单节点但可通过以下方式扩展# 添加worker节点 K3S_URLhttps://server-ip:6443 K3S_TOKENnode-token sh -s - agent # 查看token位置 cat /var/lib/rancher/k3s/server/node-token多服务器控制平面配置# 第一个节点 curl -sfL https://get.k3s.io | sh -s - server --cluster-init # 后续节点 curl -sfL https://get.k3s.io | sh -s - server --server https://first-node:64436.2 监控与日志方案内置组件集成建议# 安装Prometheus Stack helm repo add prometheus-community https://prometheus-community.github.io/helm-charts helm install kube-prometheus prometheus-community/kube-prometheus-stack -n monitoring日志收集架构graph LR A[Fluent Bit DaemonSet] -- B[Loki] B -- C[Grafana Dashboard]重要提示生产环境务必配置定期etcd备份# 创建备份脚本 cat EOF /usr/local/bin/k3s-backup #!/bin/bash etcdctl --endpointshttps://127.0.0.1:2379 \ --cacert/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt \ --cert/var/lib/rancher/k3s/server/tls/etcd/server-client.crt \ --key/var/lib/rancher/k3s/server/tls/etcd/server-client.key \ snapshot save /backup/etcd-snapshot-$(date %Y%m%d).db EOF chmod x /usr/local/bin/k3s-backup # 设置定时任务 (crontab -l 2/dev/null; echo 0 3 * * * /usr/local/bin/k3s-backup) | crontab - K3s单节点集群部署指南：轻量级Kubernetes实践
1. K3s单节点集群部署概述K3s作为轻量级Kubernetes发行版已经成为开发者本地测试和小型生产环境的首选方案。相比完整K8s动辄数GB的内存消耗K3s仅需512MB即可运行这种瘦身特性使其在边缘计算和资源受限场景中表现尤为突出。我最近在Rocky Linux 9.2系统上完成了最新版K3s的部署验证整个过程仅耗时8分钟比传统K8s集群节省了约75%的配置时间。单节点架构虽然牺牲了高可用性但对于开发测试、CI/CD流水线等场景已经足够。这种部署模式下所有控制平面组件API Server、Controller Manager、Scheduler等与工作节点共享同一台主机通过containerd替代Docker作为默认容器运行时进一步降低了资源开销。值得注意的是K3s v1.26之后版本对ARM架构的支持更加完善这使得在树莓派等设备上搭建微型K8s环境成为可能。2. 环境准备与系统配置2.1 硬件需求与操作系统选择最低配置要求CPUx86_64或ARM64架构双核内存1GB建议2GB以上磁盘20GB可用空间推荐操作系统版本# 查看系统版本示例 cat /etc/os-release我选择Rocky Linux 9.2作为基础系统主要考虑其与RHEL的二进制兼容性以及长期支持周期。关键配置步骤如下关闭Swap空间K8s的硬性要求sudo swapoff -a sudo sed -i / swap / s/^\(.*\)$/#\1/g /etc/fstab设置正确的hostname解析sudo hostnamectl set-hostname k3s-master echo 127.0.0.1 $(hostname) | sudo tee -a /etc/hosts加载内核模块sudo modprobe overlay sudo modprobe br_netfilter2.2 网络与防火墙配置Calico网络插件对内核参数有特定要求需提前配置cat EOF | sudo tee /etc/sysctl.d/k3s.conf net.bridge.bridge-nf-call-ip6tables 1 net.bridge.bridge-nf-call-iptables 1 net.ipv4.ip_forward 1 EOF sudo sysctl --system如果使用Firewalld需放行必要端口sudo firewall-cmd --permanent --add-port6443/tcp # Kubernetes API sudo firewall-cmd --permanent --add-port8472/udp # Flannel VXLAN sudo firewall-cmd --permanent --add-port10250/tcp # Kubelet API sudo firewall-cmd --reload3. K3s核心组件安装3.1 一键安装脚本解析官方提供的安装脚本实际上完成了以下关键操作curl -sfL https://get.k3s.io | sh -该脚本执行流程检测系统架构和发行版安装k3s-selinux策略包仅RHEL系下载k3s二进制和镜像到/var/lib/rancher/k3s生成systemd服务单元文件启动k3s服务并等待就绪高级安装选项示例禁用Traefik并使用外部数据库curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC--disable traefik --datastore-endpoint mysql://username:passwordtcp(hostname:3306)/database sh -3.2 关键组件定制配置通过环境变量可覆盖默认配置export INSTALL_K3S_VERSIONv1.26.4k3s1 export INSTALL_K3S_SKIP_STARTtrue export INSTALL_K3S_SYMLINKforce安装后配置文件位置主配置/etc/rancher/k3s/config.yamlkubeconfig/etc/rancher/k3s/k3s.yaml服务日志journalctl -u k3s -f4. 集群验证与组件管理4.1 基础功能测试获取节点状态kubectl get nodes -o wide验证核心Pod运行状态kubectl get pods -A -o wide测试服务部署示例部署Nginxkubectl create deployment nginx --imagenginx:alpine kubectl expose deployment nginx --port80 --typeNodePort kubectl get svc nginx4.2 插件管理实践K3s内置组件管理命令# 查看已安装组件 kubectl get deployments -n kube-system # 手动安装Metrics Server kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml持久化存储配置示例使用local-path-provisionerapiVersion: v1 kind: PersistentVolumeClaim metadata: name: local-path-pvc spec: accessModes: - ReadWriteOnce storageClassName: local-path resources: requests: storage: 2Gi5. 运维优化与故障排查5.1 性能调优参数启动参数优化示例# /etc/systemd/system/k3s.service.d/override.conf [Service] ExecStartPre-/sbin/sysctl -w vm.max_map_count262144 ExecStart ExecStart/usr/local/bin/k3s server \ --kubelet-argconfig/etc/rancher/k3s/kubelet.config \ --kube-controller-manager-argnode-monitor-grace-period20s \ --kube-apiserver-argdefault-not-ready-toleration-seconds30内存限制配置防止OOMapiVersion: v1 kind: Pod metadata: name: memory-demo spec: containers: - name: memory-demo-ctr image: polinux/stress resources: limits: memory: 200Mi requests: memory: 100Mi5.2 常见问题解决方案问题1coredns持续CrashLoopBackOff# 检查日志 kubectl logs -n kube-system coredns-xxxxxx # 典型解决方案修复网络插件配置 kubectl edit configmap -n kube-system coredns问题2节点NotReady状态# 诊断步骤 journalctl -u k3s -n 100 --no-pager kubectl describe node node-name问题3镜像拉取失败# 配置私有仓库 mkdir -p /etc/rancher/k3s/ cat EOF /etc/rancher/k3s/registries.yaml mirrors: docker.io: endpoint: - https://mirror.ccs.tencentyun.com EOF systemctl restart k3s6. 生产环境进阶配置6.1 高可用方案实现虽然本文聚焦单节点但可通过以下方式扩展# 添加worker节点 K3S_URLhttps://server-ip:6443 K3S_TOKENnode-token sh -s - agent # 查看token位置 cat /var/lib/rancher/k3s/server/node-token多服务器控制平面配置# 第一个节点 curl -sfL https://get.k3s.io | sh -s - server --cluster-init # 后续节点 curl -sfL https://get.k3s.io | sh -s - server --server https://first-node:64436.2 监控与日志方案内置组件集成建议# 安装Prometheus Stack helm repo add prometheus-community https://prometheus-community.github.io/helm-charts helm install kube-prometheus prometheus-community/kube-prometheus-stack -n monitoring日志收集架构graph LR A[Fluent Bit DaemonSet] -- B[Loki] B -- C[Grafana Dashboard]重要提示生产环境务必配置定期etcd备份# 创建备份脚本 cat EOF /usr/local/bin/k3s-backup #!/bin/bash etcdctl --endpointshttps://127.0.0.1:2379 \ --cacert/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt \ --cert/var/lib/rancher/k3s/server/tls/etcd/server-client.crt \ --key/var/lib/rancher/k3s/server/tls/etcd/server-client.key \ snapshot save /backup/etcd-snapshot-$(date %Y%m%d).db EOF chmod x /usr/local/bin/k3s-backup # 设置定时任务 (crontab -l 2/dev/null; echo 0 3 * * * /usr/local/bin/k3s-backup) | crontab -