# kubernetes-deploy

**Repository Path**: jessedev/kubernetes-deploy

## Basic Information

- **Project Name**: kubernetes-deploy
- **Description**: 本项目提供一套完整的 Kubernetes 集群自动化部署脚本，覆盖从系统初始化到应用上线的全流程。支持单 Master 高可用和多 Master 高可用两种部署模式，并内置国内镜像加速配置。
- **Primary Language**: YAML
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kubernetes 集群部署完整指南

本项目提供一套完整的 Kubernetes 集群自动化部署脚本，覆盖从系统初始化到应用上线的全流程。支持**单 Master 高可用**和**多 Master 高可用**两种部署模式，并内置国内镜像加速配置。

---

## 目录

- [项目结构](#项目结构)
- [环境要求](#环境要求)
- [节点规划](#节点规划)
- [单 Master 部署（base_script）](#单-master-部署base_script)
  - [阶段一：系统初始化](#阶段一系统初始化所有节点执行)
  - [阶段二：安装容器运行时与 K8s 组件](#阶段二安装容器运行时与-k8s-组件所有节点执行)
  - [阶段三：初始化集群与部署核心插件](#阶段三初始化集群与部署核心插件master-节点执行)
  - [阶段四：部署平台级应用（可选）](#阶段四部署平台级应用可选master-节点执行)
- [多 Master 高可用部署（cluster_script）](#多-master-高可用部署cluster_script)
- [应用部署（app_script）](#应用部署app_script)
- [YAML 示例参考（base_yml）](#yaml-示例参考base_yml)
- [集群维护与验证](#集群维护与验证)
- [常见问题与排障](#常见问题与排障)
- [版本信息](#版本信息)

---

## 项目结构

```
kubernetes-deploy/
├── base_script/       # 单 Master 模式 - 基础部署脚本
├── cluster_script/    # 多 Master 高可用模式 - 集群部署脚本
├── app_script/        # 平台级应用部署脚本（GitLab、ArgoCD、SonarQube 等）
├── base_yml/          # Kubernetes YAML 配置示例与学习参考
└── nfs/               # NFS 服务端与客户端安装脚本
```

### 脚本命名规范

- 前缀数字表示执行顺序，如 `1.1` → `1.2` → `1.3`
- 节点标识：`master` = 仅 Master 节点，`node` = 仅 Worker 节点，`all` = 所有节点

---

## 环境要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Ubuntu（推荐）或 CentOS |
| CPU | 至少 2 核 |
| 内存 | 至少 2 GB |
| 网络 | 节点间网络互通 |
| 权限 | root 用户 |
| Swap | 必须关闭 |

> **注意**：CentOS 系统需手动关闭 SELinux，本项目脚本未包含此操作。

---

## 节点规划

本项目示例使用以下节点规划，请根据实际环境修改脚本中的 IP 和主机名：

| 主机名 | IP 地址 | 角色 |
|--------|---------|------|
| k8s-master-01 | 192.168.30.10 | Master（控制平面） |
| k8s-node-01 | 192.168.30.11 | Worker |
| k8s-node-02 | 192.168.30.12 | Worker |
| k8s-node-03 | 192.168.30.15 | Worker（可选） |

---

## 单 Master 部署（base_script）

> 所有脚本位于 `base_script/` 目录，请以 root 用户执行。

### 阶段一：系统初始化（所有节点执行）

#### 1.1 设置主机名

```bash
# Master 节点
bash 1.1-master-init.sh

# 各 Worker 节点分别执行（传入主机名）
bash 1.2-node-init.sh k8s-node-01
bash 1.2-node-init.sh k8s-node-02
```

验证：`hostname`

#### 1.2 配置 hosts 文件

```bash
bash 1.3-all-config-hosts.sh
```

脚本会在 `/etc/hosts` 中添加所有节点的映射关系。修改前请先编辑脚本顶部的 `HOSTS_ENTRIES` 数组以匹配你的实际 IP。

验证：`ping k8s-master-01`

#### 1.3 关闭 Swap

```bash
bash 1.4-all-close-swap.sh
```

脚本会备份 `/etc/fstab` 并永久禁用 Swap。

验证：`free -h`（Swap 行应全为 0）

#### 1.4 加载内核模块与配置网络参数

```bash
bash 1.5-all-load-modules.sh
```

- 加载 `overlay` 和 `br_netfilter` 内核模块（持久化到 `/etc/modules-load.d/k8s.conf`）
- 配置内核参数：`bridge-nf-call-iptables`、`ip_forward` 等（写入 `/etc/sysctl.d/k8s.conf`）

验证：
```bash
lsmod | grep -E 'overlay|br_netfilter'
sysctl net.ipv4.ip_forward
```

---

### 阶段二：安装容器运行时与 K8s 组件（所有节点执行）

#### 2.1 安装基础依赖

```bash
bash 2.1-all-install-k8s.sh
```

安装 `apt-transport-https`、`ca-certificates`、`curl`、`gnupg` 等基础包。

#### 2.2 安装 containerd 容器运行时

```bash
bash 2.2-all-install-containerd.sh
```

**功能**：
- 安装 containerd.io（通过 Docker 官方仓库）
- 配置 SystemdCgroup = true
- 替换 pause 镜像源为阿里云
- 配置 18 个国内镜像加速源：
  - Docker Hub：13 个（阿里云、DaoCloud、清华、中科大、南大、交大、百度云等）
  - registry.k8s.io：3 个（阿里云、DaoCloud）
  - quay.io：2 个（阿里云、DaoCloud）
- 配置 crictl 工具

验证：
```bash
ctr version
crictl pull registry.k8s.io/pause:3.10
```

#### 2.3 安装 Kubernetes 组件

```bash
bash 2.3-all-k8s-components.sh
```

- 添加 Kubernetes apt 仓库（v1.32）
- 安装 kubelet、kubeadm、kubectl 并锁定版本
- 配置 kubelet 在 containerd 之后启动

验证：
```bash
kubectl version --client
kubeadm version
```

> 此时 kubelet 会处于失败状态，属正常现象（集群尚未初始化）。

#### 2.4 配置 IPVS 内核模块

```bash
bash 2.4-all-k8s-ipvs.sh
```

- 安装 ipvsadm、ipset、conntrack
- 加载 13 个 IPVS 内核模块（持久化配置）

验证：`lsmod | grep ip_vs`

#### 2.5 安装 KubeKey 依赖（可选）

```bash
bash 2.5-all-install-kk-deps.sh
```

安装 socat、conntrack、ebtables、ethtool 等 KubeKey 所需依赖。

---

### 阶段三：初始化集群与部署核心插件（Master 节点执行）

#### 3.0 自定义证书有效期（可选）

```bash
bash 3.0-master-k8s-cert.sh
```

> **必须在 kubeadm init 之前执行。**

通过编译自定义 kubeadm，将证书有效期从默认 1 年延长到 10 年。过程包括：安装 Go → 获取 K8s 源码 → 修改证书配置 → 编译 → 替换 kubeadm。

> 编译耗时约 10-30 分钟，需确保磁盘空间 ≥ 3 GB。

#### 3.1 初始化 Kubernetes Master

```bash
bash 3.1-master-k8s-init.sh
```

**核心参数**（可在脚本顶部修改）：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| K8S_VERSION | v1.32.13 | Kubernetes 版本 |
| SERVICE_CIDR | 10.96.0.0/12 | Service 网段 |
| POD_NETWORK_CIDR | 10.244.0.0/16 | Pod 网段（需与 Calico 一致） |
| IMAGE_REPO | registry.aliyuncs.com/google_containers | 镜像仓库 |

执行完成后**务必保存 join 命令**：
```bash
kubeadm token create --print-join-command
```

#### 3.2 Node 节点加入集群

在 Master 节点获取 join 命令后，在每个 Worker 节点执行：

```bash
# 方式一：交互式
bash 3.2-node-k8s-join.sh

# 方式二：直接传入命令
bash 3.2-node-k8s-join.sh kubeadm join <master-ip>:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx
```

> Token 默认有效期 24 小时，过期后需在 Master 重新生成。

#### 3.3 部署 Calico 网络插件

```bash
bash 3.3-master-k8s-calico.sh
```

- 下载 Calico v3.26.1
- 自动配置 Pod CIDR 为 `10.244.0.0/16`（必须与 kubeadm init 的 `--pod-network-cidr` 一致）
- 等待 calico-kube-controllers 和 calico-node 就绪

验证：
```bash
kubectl get pods -n kube-system | grep calico
kubectl get nodes   # 应全部显示 Ready
```

#### 3.4 部署 Metrics Server

```bash
bash 3.4-master-k8s-metrics.sh
```

- 启用 kube-apiserver 聚合层路由
- 部署 metrics-server v0.7.2（镜像使用阿里云加速）
- 支持 `kubectl top node` / `kubectl top pods`

验证：`kubectl top node`

#### 3.5 安装 Helm

```bash
bash 3.5-master-k8s-hlem.sh
```

- 安装 Helm v3.17.2（自动检测 amd64/arm64 架构）
- 添加常用仓库：Bitnami、阿里云、Azure 中国、Prometheus Community

验证：
```bash
helm version
helm repo list
```

#### 3.6 部署 Ingress-Nginx

```bash
bash 3.6-master-k8s-ingress-nginx.sh
```

通过 Helm 部署 Ingress-Nginx 控制器，采用 **DaemonSet + hostNetwork** 模式：

| 配置项 | 值 |
|--------|-----|
| Chart 版本 | v4.11.3 |
| 部署模式 | DaemonSet + hostNetwork |
| Service 类型 | ClusterIP |
| 目标节点 | k8s-node-01（通过标签 `ingress=true` 控制） |
| 镜像源 | 阿里云 |

验证：
```bash
kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx
```

#### 3.7 部署 NFS 动态存储制备器

```bash
bash 3.7-master-k8s-nfs-subdir-external-provisioner.sh
```

> 前提：需提前准备好 NFS 服务器（参见 `nfs/` 目录）。

| 配置项 | 默认值 |
|--------|--------|
| NFS 服务器 | 192.168.30.14 |
| NFS 共享目录 | /data/nfs-share |
| StorageClass 名称 | nfs-client |
| 是否默认 StorageClass | 是 |

验证：
```bash
kubectl get pods -n nfs-provisioner
kubectl get storageclass
```

#### 3.8 部署 Prometheus 监控系统

```bash
bash 3.8.0-master-k8s-prometheus.sh
```

通过 Helm 部署 kube-prometheus-stack，包含：
- **Prometheus**：指标采集与存储（数据保留 30 天）
- **Grafana**：可视化面板（默认密码 admin123）
- **Alertmanager**：告警管理

| 配置项 | 默认值 |
|--------|--------|
| Chart 版本 | v79.12.0 |
| 命名空间 | monitoring |
| 镜像加速 | quay.io → quay.m.daocloud.io |

访问地址：
- Grafana: `http://<节点IP>:3000`（admin / admin123）
- Prometheus: `http://<节点IP>:9090`
- Alertmanager: `http://<节点IP>:9093`

#### 3.9 部署 Local Path Provisioner（可选）

```bash
# 所有节点：创建本地存储目录
bash 3.9.1-all-k8s-local-path-provisioner.sh

# Master 节点：部署 Provisioner
bash 3.9.2-master-k8s-local-path-provisioner.sh
```

基于 Rancher 的本地路径动态存储制备器，适用于无 NFS 环境的场景。

---

### 阶段四：部署平台级应用（可选，Master 节点执行）

完成阶段三后，可根据需要部署以下平台级应用。详细配置参见 `app_script/` 目录下各子目录。

| 应用 | 目录 | 说明 |
|------|------|------|
| ArgoCD | `app_script/argo-cd/` | GitOps 持续交付工具 |
| ArgoCD Notifications | `app_script/argo-cd-notification/` | ArgoCD 通知配置 |
| GitLab | `app_script/gitlab/` | 代码托管平台（含 Redis、PostgreSQL、MinIO） |
| GitLab Runner | `app_script/gitlab-runner/` | CI/CD 执行器 |
| MySQL | `app_script/mysql/` | MySQL 数据库（Bitnami Chart） |
| SonarQube | `app_script/sonarqube/` | 代码质量扫描（含 PostgreSQL） |
| JumpServer | `app_script/jumpserver/` | 堡垒机 |
| Prometheus Webhook | `app_script/prometheus-webhook/` | 告警 Webhook（企业微信） |

---

## 多 Master 高可用部署（cluster_script）

> 适用于生产环境，需要至少 2 个 Master 节点和 1 个负载均衡器。

`cluster_script/` 提供多控制平面高可用部署方案，执行顺序与 base_script 类似：

```
1.0-all-init.sh          → 设置主机名
1.3-all-config-hosts.sh  → 配置 hosts
1.4-all-close-swap.sh    → 关闭 Swap
1.5-all-load-modules.sh  → 加载内核模块
1.6-lb-01.sh             → 配置负载均衡器（步骤1）
1.7-lb-02.sh             → 配置负载均衡器（步骤2）
2.2-master-worker-install-containerd.sh  → 安装 containerd
2.3-master-worker-k8s-components.sh      → 安装 K8s 组件
2.4-all-k8s-ipvs.sh      → 配置 IPVS
3.1-master-k8s-init.sh   → 初始化首个 Master
3.1-master-k8s-join.sh   → Worker 加入集群
3.2-master-k8s-join-cp.sh → 额外 Master 加入控制平面
3.2-node-k8s-join.sh     → Worker 加入集群
3.3-master-k8s-calico.sh → 部署 Calico
3.4-master-k8s-metrics.sh → 部署 Metrics Server
3.5-master-k8s-hlem.sh   → 安装 Helm
3.6-master-k8s-ingress-nginx.sh → 部署 Ingress-Nginx
3.7-master-k8s-nfs-subdir-external-provisioner.sh → NFS 存储
3.9.x                    → Local Path Provisioner
```

---

## 应用部署（app_script）

每个应用目录包含独立的 `install.sh` 安装脚本和所需的 values 配置文件。典型使用方式：

```bash
cd app_script/<应用名>
bash install.sh
```

### 应用部署示例

**MySQL**：
```bash
cd app_script/mysql
bash install.sh
# 连接: mysql -h mysql.mysql.svc.cluster.local -uroot -p
```

**SonarQube**（含 PostgreSQL 依赖）：
```bash
cd app_script/sonarqube
bash install.sh
# 默认账号: admin / admin
```

**ArgoCD**：
```bash
cd app_script/argo-cd
bash install.sh
# 获取初始密码:
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
```

**GitLab**（需按顺序部署依赖）：
```bash
# 部署顺序：
# 1. 命名空间 → 2. Redis → 3. PostgreSQL → 4. Secrets → 5. MinIO → 6. GitLab
cd app_script/gitlab
bash 1.0-master-namespace.sh
bash 2.0-master-redis.sh
bash 2.1-master-postgresql.sh
bash 2.2-master-create-secrets.sh
bash 2.3-master-minio.sh
bash 3.0-master-gitlab.sh
```

---

## YAML 示例参考（base_yml）

`base_yml/` 目录包含 Kubernetes 核心资源的 YAML 配置示例，适合学习和参考：

| 文件 | 资源类型 |
|------|----------|
| 1-Pod.yaml | Pod 基础配置 |
| 2-Pod生命周期-Init容器-指针.yaml | Init 容器、生命周期探针 |
| 3-Deployment.yaml | Deployment |
| 4-StatefulSet.yaml | StatefulSet |
| 5-DeamonSet.yaml | DaemonSet |
| 6-HPA.yaml | 水平自动扩缩容 |
| 7-Service.yaml | Service |
| 8.0-Ingress.yaml | Ingress 配置 |
| 9.0-ConfigMap.yaml | ConfigMap |
| 10.0-Secret.yaml | Secret |
| 11.0-Volume.yaml | Volume 挂载 |
| 13.0-PV.yaml / 13.0-PVC.yaml | 持久卷与持久卷声明 |
| 14.0-NFS动态制备器.yaml | NFS 动态制备 |
| 15.0-Job.yaml | Job |
| 16.0-CronJob.yaml | CronJob |
| 17.0-污点与容忍.yaml | Taints & Tolerations |
| 18.0-亲和性.yaml | 亲和性与反亲和性 |
| 19.0-认证与鉴权.yaml | RBAC 认证鉴权 |
| 20.0-证书更新.sh | 证书更新脚本 |
| 21.0-NetworkPolicy.yaml | 网络策略 |

---

## 集群维护与验证

### 健康检查

```bash
# 检查节点状态
kubectl get nodes

# 检查系统 Pod
kubectl get pods -n kube-system

# 检查组件健康
kubectl get --raw='/readyz?verbose'

# 资源使用
kubectl top nodes
kubectl top pods --all-namespaces
```

### 常用维护命令

```bash
# 查看集群信息
kubectl cluster-info

# 查看事件
kubectl get events --all-namespaces --sort-by='.lastTimestamp'

# 备份 etcd
ETCDCTL_API=3 etcdctl snapshot save snapshot.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# 更新证书
kubeadm certs renew all
```

### 启用 kube-proxy IPVS 模式（可选）

在完成集群部署后，可切换到 IPVS 模式以提升网络性能：

```bash
# 编辑 kube-proxy 配置
kubectl edit cm kube-proxy -n kube-system
```

修改 `mode: "ipvs"`，然后滚动重启：
```bash
kubectl rollout restart daemonset kube-proxy -n kube-system
```

验证：
```bash
kubectl logs -n kube-system -l k8s-app=kube-proxy | grep -i ipvs
ipvsadm -Ln
```

### 服务器重启后网络修复

如果重启后出现网络不通问题：

```bash
# 1. 停止 kubelet，清理残留容器
systemctl stop kubelet
crictl rm -f $(crictl ps -aq)

# 2. 清理 CNI 网络与 iptables 规则
iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
ipvsadm -C                                    # IPVS 模式需要
ip link del cni0 2>/dev/null
ip link delete type cali 2>/dev/null
rm -rf /var/lib/cni/*

# 3. 重启服务
systemctl restart containerd
systemctl restart kubelet

# 4. 验证
kubectl get nodes
kubectl get pods -n kube-system | grep calico
```

---

## 常见问题与排障

### kubelet 启动失败

```bash
journalctl -xeu kubelet

# 常见原因排查：
free -h                          # Swap 是否关闭
lsmod | grep br_netfilter        # 内核模块是否加载
systemctl status containerd      # containerd 是否运行
```

### 镜像拉取失败

```bash
# 检查镜像源配置
cat /etc/containerd/certs.d/docker.io/hosts.toml
cat /etc/containerd/certs.d/registry.k8s.io/hosts.toml

# 手动测试拉取
crictl pull registry.k8s.io/pause:3.10

# 查看日志
journalctl -u containerd -f
```

### 节点加入失败

```bash
# Token 过期 → 重新生成
kubeadm token create --print-join-command

# 节点显示 NotReady → 部署 Calico 后自动恢复
# 如仍 NotReady，检查：
kubectl describe node <node-name>
```

### Pod 一直处于 Pending

```bash
kubectl describe pod <pod-name>

# 常见原因：资源不足、节点污点、PVC 未绑定、网络插件未就绪
```

### CoreDNS 异常

```bash
kubectl get pods -n kube-system | grep coredns
kubectl logs -n kube-system <coredns-pod-name>
kubectl rollout restart deployment coredns -n kube-system
```

### 重置集群

```bash
# 所有节点执行
kubeadm reset -f
iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
ip link delete type cali 2>/dev/null
rm -rf /etc/cni/net.d $HOME/.kube/config
systemctl restart kubelet
```

---

## 版本信息

| 组件 | 版本 |
|------|------|
| Kubernetes | v1.32.13 |
| Calico | v3.26.1 |
| containerd | 最新稳定版 |
| Helm | v3.17.2 |
| Metrics Server | v0.7.2 |
| Ingress Nginx | Chart v4.11.3 |
| NFS Provisioner | Chart v4.0.18 |
| Prometheus Stack | Chart v79.12.0 |

---

## 参考资源

- [Kubernetes 官方文档](https://kubernetes.io/docs/)
- [Calico 官方文档](https://projectcalico.docs.tigera.io/)
- [containerd 配置指南](https://github.com/containerd/containerd/blob/main/docs/ops.md)
- [kubeadm 官方文档](https://kubernetes.io/docs/reference/setup-tools/kubeadm/)
- [Helm 官方文档](https://helm.sh/docs/)