MicroK8s故障排查手册：常见问题定位与解决方案
项目地址: https://gitcode.com/gh_mirrors/mic/microk8s 概述
MicroK8s作为轻量级Kubernetes发行版，在简化部署的同时也面临各类运行时问题。本文基于项目内置工具和社区经验，系统化梳理故障排查流程，覆盖服务状态诊断、证书管理、网络配置等核心场景，提供可直接操作的解决方案。
诊断工具与前置检查
系统状态快照
执行内置检查工具生成系统状态报告：
microk8s inspect
报告生成路径：/var/snap/microk8s/current/inspection-report-<timestamp>.tar.gz，包含服务日志、网络配置和Kubernetes集群状态。核心检查逻辑实现于scripts/inspect.sh，通过验证关键服务活性、资源使用和配置完整性定位基础问题。
服务状态验证
关键组件状态检查：
# 检查核心服务
snap services microk8s
需确保microk8s.daemon-kubelite（集成控制平面）、microk8s.daemon-containerd（容器运行时）等服务处于active状态。服务管理逻辑参见microk8s-resources/actions/common/utils.sh中的check_service函数实现。
常见故障场景与解决方案
1. 权限访问错误
症状：执行microk8s kubectl时提示"Insufficient permissions"。
根因：当前用户未加入MicroK8s用户组。
解决方案：
sudo usermod -a -G microk8s $USER
sudo chown -R $USER ~/.kube
newgrp microk8s # 无需重启生效
权限检查逻辑位于microk8s-resources/actions/common/utils.sh的exit_if_no_permissions函数，验证用户对$SNAP_DATA/credentials/client.config的访问权限。
2. 控制平面启动失败
症状：microk8s status显示not running，检查日志发现API Server启动失败。
排查步骤：
- 检查端口占用：
sudo lsof -i :16443（API Server默认端口） - 查看详细日志：
journalctl -u snap.microk8s.daemon-kubelite -n 100
典型解决方案：
- 释放端口冲突：终止占用16443端口的进程
- 重置控制平面：
microk8s stop sudo rm -rf /var/snap/microk8s/current/var/lock/stopped.lock microk8s start
服务启停控制通过microk8s-resources/actions/common/utils.sh的restart_service函数实现，支持单组件和集群级重启。
3. 证书更新问题
症状：日志出现x509: certificate has expired or is not yet valid。
解决方案：
# 刷新证书
microk8s refresh-certs
# 验证证书有效期
openssl x509 -in /var/snap/microk8s/current/certs/ca.crt -noout -dates
证书更新逻辑位于microk8s-resources/actions/common/utils.sh的produce_certs函数，默认有效期为365天。生产环境建议配置证书自动轮换。
4. 网络插件冲突
症状：Pod间无法通信，kubectl get pods -n kube-system显示calico-node状态异常。
解决方案：
# 重置网络插件
microk8s disable calico
microk8s enable calico
# 清理残留网络接口
sudo ip link delete cni0
sudo ip link delete flannel.1
网络接口清理逻辑参见microk8s-resources/actions/common/utils.sh的remove_vxlan_interfaces函数，处理Calico/Flannel遗留虚拟网卡。
5. 资源不足问题
症状：Pod频繁重启，事件日志显示OOMKilled或Evicted。
系统检查：
# 检查节点资源使用
microk8s kubectl top node
# 查看驱逐事件
microk8s kubectl describe node | grep -A 10 "Events"
优化方案：
- 调整资源限制：修改部署的
resources.limits配置 - 禁用低内存保护（测试环境）：
microk8s start --disable-low-memory-guard
低内存保护触发逻辑位于scripts/inspect.sh的check_low_memory_guard函数，当系统内存低于1GB时自动启用。
高级排障：分布式集群问题
节点加入失败
症状：执行microk8s join时报错"connection refused"。
排查清单：
- 验证主节点API Server可访问：
nc -zv <master-ip> 25000 - 检查防火墙规则：确保UDP 8472（Flannel）、TCP 16443/25000端口开放
- 验证令牌有效性：通过
microk8s add-node重新生成Join令牌
节点通信机制实现于microk8s-resources/wrappers/microk8s-join.wrapper，采用TLS加密和双向认证确保集群安全。
数据一致性问题
症状：高可用集群中节点状态同步异常。
解决方案：检查dqlite分布式数据库状态：
microk8s dbctl sql "SELECT * FROM raft_nodes"
数据库配置文件位于/var/snap/microk8s/current/var/kubernetes/backend/，集群管理逻辑参见microk8s-resources/actions/common/utils.sh的nodes_addon函数实现。
预防与监控建议
关键指标监控
部署Prometheus和Grafana监控栈：
microk8s enable prometheus grafana
通过监控面板重点关注：
- API Server请求延迟（
apiserver_request_duration_seconds） - 容器运行时健康状态（
container_runtime_operations_errors） - etcd/dqlite数据库性能（
etcd_disk_backend_commit_duration_seconds）
定期维护任务
- 证书更新：集群部署6个月内执行
microk8s refresh-certs - 日志清理：配置logrotate处理
/var/snap/microk8s/common/var/log日志文件 - 配置备份：定期导出关键配置
microk8s config > microk8s-config.yaml
附录：核心配置文件路径
| 组件 | 配置路径 | 说明 |
|---|---|---|
| 控制平面参数 | /var/snap/microk8s/current/args/ | 包含kube-apiserver、kubelet等服务启动参数 |
| 证书文件 | /var/snap/microk8s/current/certs/ | CA证书、服务端证书和客户端密钥 |
| 网络配置 | /var/snap/microk8s/current/args/cni-network/ | CNI插件配置，默认使用Calico |
| 数据存储 | /var/snap/microk8s/current/var/kubernetes/backend/ | dqlite数据库文件 |
完整目录结构可通过项目根目录的docs/community.md获取社区维护的部署案例和最佳实践。
故障排查流程图
故障排查流程基于项目tests/smoke-test.sh的自动化测试逻辑，通过分层检查快速定位问题根源。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
