使用k3d快速搭建K3s高可用集群指南

📅 2026/7/22 5:20:29 👁️ 阅读次数 📝 编程学习

1. 项目概述

k3d是一个轻量级的Kubernetes发行版K3s的Docker容器化实现工具，它允许开发者在本地Docker环境中快速创建和管理K3s集群。相比直接在主机上安装K3s，k3d提供了更轻量、更隔离的测试环境，特别适合本地开发和持续集成场景。

在实际生产环境中，高可用性是Kubernetes集群的基本要求。通过k3d实现K3s高可用集群，可以在本地开发环境中模拟生产环境的集群架构，提前发现和解决潜在问题。本教程将详细演示如何使用k3d创建一个三节点的K3s高可用集群，包含完整的配置步骤和故障排查方法。

2. 环境准备与工具安装

2.1 系统要求

操作系统：支持Linux、macOS或Windows（需WSL2）
Docker版本：20.10.0或更高
内存：建议至少8GB（每个节点需要1-2GB）
CPU：建议4核以上

2.2 安装Docker

对于Ubuntu/Debian系统，使用以下命令安装Docker：

sudo apt-get update sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io

2.3 安装k3d

使用官方脚本安装最新版k3d：

curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

验证安装：

k3d --version

3. 创建高可用K3s集群

3.1 集群架构设计

我们创建一个包含3个server节点（构成高可用控制平面）和2个agent节点（工作节点）的集群：

+---------------+ | LoadBalancer| +-------┬-------+ | +-----------+-----------+-----------+ | | | | +------v-----+ +---v-------+ +-v---------+ +-----------+ | Server Node1| | Server Node2| | Server Node3| | Agent Nodes | +------------+ +------------+ +------------+ +-----------+

3.2 集群创建命令

k3d cluster create my-ha-cluster \ --servers 3 \ --agents 2 \ --k3s-arg "--disable=traefik@server:*" \ --k3s-arg "--disable=metrics-server@server:*" \ --port 80:80@loadbalancer \ --port 443:443@loadbalancer \ --api-port 6443 \ --wait

参数说明：

--servers 3：创建3个server节点构成高可用控制平面
--agents 2：创建2个工作节点
--k3s-arg：传递给K3s的参数，这里禁用了traefik和metrics-server
--port：端口映射，将宿主机的80/443映射到负载均衡器
--api-port：Kubernetes API服务器端口
--wait：等待集群完全启动

3.3 验证集群状态

kubectl get nodes -o wide kubectl get pods -A

预期输出应显示3个control-plane节点和2个worker节点都处于Ready状态。

4. 高可用配置详解

4.1 嵌入式etcd集群

K3s默认使用嵌入式etcd作为数据存储。在三节点配置中，etcd会自动组成集群：

kubectl -n kube-system exec -it etcd-my-ha-cluster-server-0 -- etcdctl member list

4.2 负载均衡配置

k3d自动为集群创建了一个负载均衡器：

docker ps | grep k3d-my-ha-cluster-serverlb

负载均衡器会将请求分发到健康的control-plane节点，确保API服务器的高可用。

4.3 证书自动轮换

K3s会自动管理以下证书：

CA证书：10年有效期
客户端和服务端证书：365天有效期，到期前90天自动续期

查看证书信息：

sudo k3s certificate list

5. 高级配置选项

5.1 自定义K3s版本

k3d cluster create my-cluster --image rancher/k3s:v1.26.5-k3s1

5.2 持久化存储配置

默认情况下，k3d使用临时存储。要启用持久化存储：

k3d cluster create my-cluster --volume /path/on/host:/path/in/container@all

5.3 自定义CNI插件

替换默认的flannel CNI：

k3d cluster create my-cluster --k3s-arg "--flannel-backend=none@server:*" kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

6. 日常运维操作

6.1 集群启停

停止集群：

k3d cluster stop my-ha-cluster

启动集群：

k3d cluster start my-ha-cluster

6.2 节点管理

添加worker节点：

k3d node create new-worker --cluster my-ha-cluster --role agent

删除节点：

k3d node delete k3d-my-ha-cluster-agent-1

6.3 集群备份与恢复

备份etcd数据：

kubectl -n kube-system exec etcd-my-ha-cluster-server-0 -- \ etcdctl snapshot save /tmp/etcd-backup.db docker cp k3d-my-ha-cluster-server-0:/tmp/etcd-backup.db .

从备份恢复：

k3d cluster delete my-ha-cluster k3d cluster create restored-cluster --servers 3 --agents 2 docker cp etcd-backup.db k3d-restored-cluster-server-0:/tmp/ kubectl -n kube-system exec etcd-k3d-restored-cluster-server-0 -- \ etcdctl snapshot restore /tmp/etcd-backup.db \ --data-dir=/var/lib/rancher/k3s/server/db/etcd-restored

7. 故障排查与常见问题

7.1 节点NotReady状态排查

检查节点状态详情：

kubectl describe node <node-name>

查看kubelet日志：

docker logs k3d-<cluster-name>-<node-role>-<index>

7.2 网络问题排查

检查CNI插件状态：

kubectl -n kube-system get pods -l k8s-app=flannel

查看网络策略：

kubectl get networkpolicies -A

7.3 常见错误解决方案

问题1：端口已被占用

Error: failed to create cluster: failed to create loadbalancer: failed to start loadbalancer container

解决方案：修改端口映射或释放被占用的端口。

问题2：镜像拉取失败

Failed to pull image "rancher/k3s:v1.26.5-k3s1"

解决方案：检查网络连接，或手动拉取镜像：

docker pull rancher/k3s:v1.26.5-k3s1

问题3：etcd集群健康状态异常

etcdserver: unhealthy cluster

解决方案：检查etcd成员状态并重新加入节点：

kubectl -n kube-system exec etcd-my-ha-cluster-server-0 -- etcdctl cluster-health

8. 性能优化建议

8.1 资源分配

为Docker分配足够资源：

在Docker Desktop中，建议分配至少4CPU和8GB内存
在Linux上，调整cgroup限制：

sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json <<EOF { "default-ulimits": { "nofile": { "Name": "nofile", "Hard": 65535, "Soft": 65535 } } } EOF sudo systemctl restart docker

8.2 内核参数调优

对于Linux主机，建议调整以下内核参数：

sudo tee /etc/sysctl.d/k8s.conf <<EOF net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-ip6tables = 1 net.bridge.bridge-nf-call-iptables = 1 EOF sudo sysctl --system

8.3 存储优化

使用更高效的存储驱动：

sudo tee /etc/docker/daemon.json <<EOF { "storage-driver": "overlay2" } EOF sudo systemctl restart docker

9. 安全最佳实践

9.1 访问控制

限制kubeconfig访问权限：

chmod 600 ~/.kube/config

启用RBAC：

kubectl create clusterrolebinding admin-binding \ --clusterrole=cluster-admin \ --user=your-username

9.2 网络策略

应用默认拒绝所有流量的网络策略：

apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: default-deny-all spec: podSelector: {} policyTypes: - Ingress - Egress

9.3 镜像安全

使用私有镜像仓库：

k3d cluster create my-cluster --registry-config registry.yaml

扫描镜像漏洞：

docker scan nginx:latest

10. 实际应用场景

10.1 本地开发环境

为开发团队创建隔离的Kubernetes环境：

k3d cluster create dev-env \ --servers 1 \ --agents 3 \ --port 8080:80@loadbalancer \ --volume ~/projects:/projects@all

10.2 CI/CD流水线

在GitLab CI中使用k3d：

test: stage: test image: docker:latest services: - docker:dind script: - apk add --no-cache curl - curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash - k3d cluster create ci-cluster - kubectl apply -f k8s/ - kubectl wait --for=condition=available deployment/my-app --timeout=300s

10.3 教育培训

快速创建多集群环境用于Kubernetes教学：

for i in {1..5}; do k3d cluster create student-$i \ --servers 1 \ --agents 2 \ --k3s-arg "--disable=traefik@server:*" done

11. 集群监控与日志

11.1 部署Prometheus监控

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts helm install prometheus prometheus-community/kube-prometheus-stack

访问Grafana：

kubectl port-forward svc/prometheus-grafana 3000:80

11.2 集中式日志收集

部署Loki日志系统：

helm repo add grafana https://grafana.github.io/helm-charts helm install loki grafana/loki-stack \ --set promtail.enabled=true \ --set grafana.enabled=true

11.3 性能指标监控

安装Metrics Server：

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

查看节点资源使用：

kubectl top nodes

12. 集群升级与维护

12.1 K3s版本升级

备份集群：

k3d cluster stop my-ha-cluster docker commit k3d-my-ha-cluster-server-0 my-ha-cluster-backup

升级集群：

k3d cluster delete my-ha-cluster k3d cluster create my-ha-cluster --image rancher/k3s:v1.27.2-k3s1 --servers 3 --agents 2

12.2 证书轮换

手动轮换证书：

k3s certificate rotate

12.3 节点维护

安全排空节点：

kubectl drain k3d-my-ha-cluster-agent-0 --ignore-daemonsets --delete-emptydir-data

13. 集群扩展与集成

13.1 多集群管理

使用kubefed管理多个k3d集群：

helm install kubefed kubefed-charts/kubefed \ --namespace kube-federation-system \ --create-namespace

13.2 服务网格集成

安装Istio服务网格：

curl -L https://istio.io/downloadIstio | sh - cd istio-* ./bin/istioctl install --set profile=demo -y

13.3 数据库集成

部署PostgreSQL Operator：

kubectl apply -k github.com/CrunchyData/postgres-operator-examples/kustomize/install/namespace kubectl apply -k github.com/CrunchyData/postgres-operator-examples/kustomize/install/default

14. 资源清理

14.1 删除集群

k3d cluster delete my-ha-cluster

14.2 清理残留资源

docker system prune -af rm -rf ~/.kube/cache

14.3 完全卸载k3d

rm $(which k3d) rm -rf ~/.config/k3d

15. 经验总结与建议

在实际使用k3d部署K3s高可用集群的过程中，有几个关键点值得特别注意：

资源分配：确保Docker有足够的内存和CPU资源，特别是运行多个节点时。我曾遇到因内存不足导致etcd节点频繁崩溃的情况，增加Docker资源分配后问题解决。
网络性能：在Mac和Windows上，WSL2或Docker Desktop的虚拟网络性能可能不如Linux原生。对于性能敏感的应用，建议在Linux主机上运行k3d集群。
持久化存储：默认情况下，k3d使用临时存储，这意味着容器重启后数据会丢失。对于需要持久化数据的应用，务必配置volume映射。
镜像缓存：k3d不会自动清理旧镜像，长期使用可能导致磁盘空间不足。定期运行docker system prune清理无用镜像。
生产环境使用：虽然k3d非常适合开发和测试，但不建议直接用于生产环境。生产环境应考虑使用K3s的原生高可用部署方案。
版本兼容性：注意k3d、K3s和Kubernetes版本之间的兼容性。我曾遇到因版本不匹配导致API无法访问的问题，保持组件版本一致很重要。
调试技巧：当集群出现问题时，可以临时增加--verbose参数运行k3d命令，获取更详细的日志信息。例如：

k3d cluster create --verbose my-debug-cluster

多集群管理：当需要管理多个k3d集群时，建议使用不同的kubeconfig文件，并通过KUBECONFIG环境变量切换：

export KUBECONFIG=$(k3d kubeconfig write cluster1):$(k3d kubeconfig write cluster2) kubectl config view --flatten > merged-config kubectl config use-context k3d-cluster1

编程学习技术分享实战经验

资讯详情