基于K3s搭建GitOps环境1-K3s安装

发表于 更新于

一、核心定位

本文作为GitOps环境搭建系列的第一篇，聚焦K3s集群的部署与基础配置。K3s是Rancher Labs推出的轻量级Kubernetes发行版，专为边缘计算、IoT设备和资源受限环境设计。相比标准Kubernetes，K3s具有安装包小（约40MB）、内存占用低、启动快速等优势，是构建轻量级GitOps环境的理想选择。

在GitOps环境中，K3s作为底层容器编排平台，承载所有GitOps组件（Gitea、ArgoCD、Tekton、Harbor等）的运行，提供容器调度、服务发现、存储管理、网络通信等核心能力。

二、部署前置检查

部署前需验证服务器环境，确保满足K3s运行要求：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. 检查操作系统版本（支持Ubuntu 20.04+/CentOS 7+/RHEL 8+）
cat /etc/os-release

# 2. 检查内核版本（需≥3.10）
uname -r

# 3. 检查内存和存储空间
free -h
df -h /

# 4. 检查网络连通性
ping -c 3 8.8.8.8

# 5. 检查防火墙状态（建议关闭或配置放行规则）
sudo systemctl status firewalld
# 或
sudo ufw status

前置条件检查清单：

  • 操作系统符合要求
  • 内核版本≥3.10
  • 内存≥2GB，存储≥20GB
  • 网络可访问外网（用于拉取镜像）
  • 防火墙已关闭或配置放行规则
  • 已配置sudo权限或root用户

三、K3s集群部署

3.1 Master节点安装

执行以下命令安装K3s Master节点：

1
2
3
4
# 使用国内镜像源加速安装
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
    INSTALL_K3S_MIRROR=cn \
    INSTALL_K3S_EXEC='--write-kubeconfig-mode=644' sh -

安装参数说明：

  • INSTALL_K3S_MIRROR=cn：使用中国区镜像源，加速安装过程
  • --write-kubeconfig-mode=644：设置kubeconfig文件权限为644，便于多用户访问
  • --service-node-port-range=1-65535：解除NodePort端口限制（默认30000-32767）
  • --advertise-address=192.168.1.100：指定集群管理IP（替换为实际IP）
  • --disable=traefik：禁用Traefik（如需自定义Traefik配置）
  • --disable=local-path：禁用本地存储（如需使用其他存储方案）

3.2 Worker节点加入集群

在Worker节点执行以下命令加入集群：

1
2
3
4
5
6
7
8
# 获取Master节点的token（在Master节点执行）
sudo cat /var/lib/rancher/k3s/server/node-token

# 在Worker节点执行加入命令（替换<k3s-server-ip>和<token>）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
    K3S_URL=https://<k3s-server-ip>:6443 \
    K3S_TOKEN=<token> \
    INSTALL_K3S_EXEC='--write-kubeconfig-mode=644' sh -

参数说明：

  • <k3s-server-ip>：Master节点的IP地址
  • <token>：从Master节点获取的加入令牌

3.3 配置kubeconfig

配置kubectl访问凭证：

1
2
3
4
5
6
7
# 设置KUBECONFIG环境变量
echo "export KUBECONFIG=/etc/rancher/k3s/k3s.yaml" >> ~/.bashrc
source ~/.bashrc

# 验证集群访问
kubectl get nodes
kubectl cluster-info

四、存储配置优化

4.1 修改local-path存储类回收策略

K3s默认使用local-path存储类，其回收策略为Delete（删除Pod时会删除关联的PV）。生产环境建议改为Retain，防止数据误删。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 查看当前存储类配置
kubectl get storageclasses.storage.k8s.io local-path -o yaml

# 创建修改后的存储类配置
cat > storage-class.yaml << EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  annotations:
    defaultVolumeType: local
    storageclass.kubernetes.io/is-default-class: "true"
  name: local-path
provisioner: rancher.io/local-path
reclaimPolicy: Retain  # 修改为Retain，防止数据误删
volumeBindingMode: WaitForFirstConsumer
EOF

# 应用修改后的存储类
kubectl delete storageclasses.storage.k8s.io local-path
kubectl apply -f storage-class.yaml

4.2 自定义存储路径

如需自定义存储路径，可在安装时指定：

1
2
3
4
# 安装时指定存储路径
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
    INSTALL_K3S_MIRROR=cn \
    INSTALL_K3S_EXEC='--write-kubeconfig-mode=644 --default-local-storage-path=/mnt/storage/k3s' sh -

五、管理工具安装

5.1 Helm安装

Helm是Kubernetes的包管理工具，后续组件部署将大量使用：

1
2
3
4
5
6
7
8
# 在线安装（推荐）
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Ubuntu使用snap安装
sudo snap install helm --classic

# 验证安装
helm version --short

5.2 命令自动补全

配置命令自动补全，提升操作效率：

1
2
3
4
5
6
7
8
9
10
11
# 安装bash-completion
sudo apt install bash-completion
source /usr/share/bash-completion/bash_completion

# kubectl自动补全
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

# helm自动补全
echo 'source <(helm completion bash)' >> ~/.bashrc
source ~/.bashrc

六、私有镜像库配置

K3s支持配置私有镜像库，加速镜像拉取或使用内网镜像仓库：

6.1 配置镜像加速器

1
2
3
4
5
6
7
8
9
10
11
# 创建registries.yaml配置文件
sudo cat > /etc/rancher/k3s/registries.yaml << EOF
mirrors:
  "docker.io":
    endpoint:
      - "https://fogjl973.mirror.aliyuncs.com"  # 阿里云镜像加速器
      - "https://registry-1.docker.io"
EOF

# 重启K3s使配置生效
sudo systemctl restart k3s

6.2 配置私有Harbor仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 配置带认证的私有仓库
sudo cat > /etc/rancher/k3s/registries.yaml << EOF
mirrors:
  "harbor.example.io":  # 替换为您的Harbor域名
    endpoint:
      - "https://harbor.example.io"
configs:
  "harbor.example.io":
    auth:
      username: admin
      password: Harbor12345
    tls:
      ca_file: /opt/certs/ca.crt  # 自签名证书路径
EOF

七、验证部署结果

7.1 基础功能测试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. 创建测试应用
kubectl create deploy whoami --image=traefik/whoami --replicas=2

# 2. 监控Pod启动状态
kubectl get pods --watch

# 3. 暴露服务
kubectl expose deploy whoami --port=80

# 4. 查看服务状态
kubectl get svc whoami -o wide

# 5. 扩容测试
kubectl scale deploy whoami --replicas=5
kubectl get pods

# 6. 清理测试资源
kubectl delete all --all

7.2 集群状态检查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看所有节点状态
kubectl get nodes -o wide

# 查看所有命名空间资源
kubectl get all -A

# 查看核心组件状态
kubectl get pods -n kube-system

# 查看存储类
kubectl get storageclass

# 查看集群事件
kubectl get events --sort-by='.lastTimestamp'

八、常用运维命令

8.1 集群管理

1
2
3
4
5
6
7
8
9
10
11
12
# 查看集群信息
kubectl cluster-info

# 查看节点详细信息
kubectl describe node <node-name>

# 查看节点标签
kubectl get node --show-labels

# 查看资源使用情况
kubectl top nodes
kubectl top pods -A

8.2 应用管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 查看指定命名空间资源
kubectl get all -n <namespace>

# 查看Pod日志
kubectl logs -n <namespace> <pod-name>
kubectl logs -f -n <namespace> <pod-name>  # 实时日志

# 进入Pod容器
kubectl exec -it -n <namespace> <pod-name> -- /bin/bash

# 重启Deployment
kubectl rollout restart deploy/<deploy-name> -n <namespace>

# 查看部署历史
kubectl rollout history deploy/<deploy-name> -n <namespace>

8.3 Helm管理

1
2
3
4
5
6
7
8
9
10
11
# 查看charts的values文件
helm show values bitnami/redis > values.yaml

# 添加Helm仓库
helm repo add <repo-name> <repo-url>

# 更新仓库索引
helm repo update

# 搜索chart
helm search repo <keyword>

九、常见问题修复

问题现象 排查方向 修复方案
节点NotReady 网络/容器运行时 检查网络连通性，重启containerd：sudo systemctl restart containerd
Pod一直Pending 资源不足/存储问题 检查节点资源：kubectl describe pod <pod-name>，查看事件
镜像拉取失败 镜像仓库/网络 检查镜像地址，配置镜像加速器或私有仓库
kubeconfig权限错误 文件权限 设置正确权限：sudo chmod 644 /etc/rancher/k3s/k3s.yaml
Helm安装失败 网络/版本 检查网络，使用国内镜像源或离线安装

十、配置参考

所有配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops/k3s

该目录包含：

  • K3s安装脚本
  • 存储类配置
  • 镜像仓库配置
  • 节点加入脚本
  • 生产环境优化配置

总结

本文完成了K3s集群的标准化部署，包括Master节点安装、Worker节点加入、存储配置优化、管理工具安装等核心步骤。K3s作为轻量级Kubernetes发行版，为后续GitOps组件部署提供了稳定可靠的底层平台。

部署完成后，建议进行全面的功能测试，确保集群各项功能正常。下一篇文章将基于此K3s集群，部署Traefik反向代理，为后续组件提供统一的访问入口。