devstar/docs/kubernetes/k8s-installtion.md

# Kubernetes 集群安装文档

## 📋 集群信息
- **Master**: 172.17.0.15 (master)
- **Node1**: 172.17.0.43 (node1)  
- **Node2**: 172.17.0.34 (node2)
- **Kubernetes 版本**: v1.32.3
- **容器运行时**: containerd
- **网络插件**: Flannel
- **镜像仓库**: 阿里云镜像

## 🎯 安装方式
**模块化安装**: 每个脚本功能清晰，可以单独执行或按顺序执行

## 📋 安装脚本

### 🔧 脚本列表
1. **`k8s-step1-prepare-env.sh`** - 环境准备 (所有节点)
2. **`k8s-step2-install-containerd.sh`** - 容器运行时安装 (所有节点)
3. **`k8s-step3-install-components.sh`** - Kubernetes 组件安装 (所有节点)
4. **`k8s-step4-init-cluster.sh`** - 集群初始化 (Master 节点)
5. **`k8s-step5-install-flannel.sh`** - 网络插件安装 (Master 节点)
6. **`k8s-step6-join-nodes.sh`** - 节点加入集群 (Node1, Node2)
7. **`k8s-install-all.sh`** - 主控制脚本 (按顺序执行所有步骤)

### 🌐 网络配置脚本
- **`setup-master-gateway.sh`** - Master 节点网关配置
- **`setup-node1.sh`** - Node1 网络路由配置
- **`setup-node2.sh`** - Node2 网络路由配置

### 🔧 辅助工具脚本
- **`install-kubectl-nodes.sh`** - 为其他节点安装 kubectl

### 🚀 使用方法

#### 方法 1: 一键安装 
```bash
# 在 Master 节点运行
./k8s-install-all.sh
```

#### 方法 2: 分步安装
```bash
# 按顺序执行每个步骤
./k8s-step1-prepare-env.sh
./k8s-step2-install-containerd.sh
./k8s-step3-install-components.sh
./k8s-step4-init-cluster.sh
./k8s-step5-install-flannel.sh
./k8s-step6-join-nodes.sh

# 可选：为其他节点安装 kubectl
./install-kubectl-nodes.sh
```

## 📋 安装步骤

### ✅ 步骤 1: 环境准备（已完成）
- [x] 云主机重装系统：确认系统盘数据清空，无残留 kube 目录与服务
- [x] 主机名设置：`master`、`node1`、`node2`（不在节点脚本中写入 hosts）
- [x] Master 配置 NAT 网关：开启 `net.ipv4.ip_forward`，设置 `iptables` MASQUERADE 并持久化
- [x] 基础内核与网络：开启 `overlay`、`br_netfilter`；`sysctl` 应用桥接与转发参数
- [x] 关闭 swap：禁用并注释 `/etc/fstab` 对应项
- [x] 防火墙：禁用 `ufw`，确保必要端口不被拦截
- [x] SSH 信任：在 master 生成密钥并分发到 `node1/node2`，验证免密可达

### ✅ 步骤 2: 容器运行时准备（所有节点，已完成）
- [x] 更新系统包，安装依赖工具：`curl`、`wget`、`gnupg`、`ca-certificates`、`apt-transport-https` 等
- [x] 安装 containerd 并生成默认配置 `/etc/containerd/config.toml`
- [x] 配置镜像加速：docker.io/quay.io 使用腾讯云镜像，其他使用高校镜像
- [x] 安装 CNI 插件 v1.3.0（在 master 预下载并分发至 node1/node2）
- [x] 启用并开机自启 `containerd`，确认服务状态正常

### ✅ 步骤 3: 安装 Kubernetes 组件（所有节点，已完成）
- [x] 添加 Kubernetes APT 仓库（pkgs.k8s.io v1.32），修复 GPG key 与源配置问题
- [x] 安装并锁定版本：`kubelet`、`kubeadm`、`kubectl` 为 `v1.32.3`
- [x] 配置 kubelet：使用 `systemd` cgroup，与 containerd 对齐，写入完整配置文件
- [x] 启用并启动 `kubelet` 服务

### ✅ 步骤 4: 集群初始化（Master 节点，已完成）
- [x] 执行 `kubeadm init` 完成初始化：包含 `controlPlaneEndpoint=172.17.0.15:6443`、Networking（ServiceCIDR `10.96.0.0/12`、PodCIDR `10.244.0.0/16`）、`imageRepository`（Aliyun）
- [x] 拷贝 `admin.conf` 到 `~/.kube/config` 并验证控制面组件：`etcd`、`kube-apiserver`、`kube-controller-manager`、`kube-scheduler`、`kube-proxy` 均 Running；`coredns` Pending（等待安装网络插件）
- [x] 生成并使用 `kubeadm token create --print-join-command` 生成 join 命令

### ✅ 步骤 5: 网络插件安装 (Master 节点，已完成)
- [x] 下载并应用 Flannel v0.27.4 清单
- [x] 匹配 Pod CIDR `10.244.0.0/16`，等待组件 Ready
- [x] 配置 Flannel 使用国内镜像源（registry-k8s-io.mirrors.sjtug.sjtu.edu.cn、ghcr.tencentcloudcr.com）
- [x] 预拉取所有 Flannel 镜像并打标签
- [x] 等待所有网络组件就绪：kube-flannel-ds、coredns

### ✅ 步骤 6: 节点加入集群（已完成）
- [x] 读取 `node-join-command.txt` 文件中的 join 命令
- [x] 在 `node1/node2` 执行 join，加入成功后验证 `Ready`
- [x] 验证所有节点状态：master (Ready, control-plane)、node1 (Ready)、node2 (Ready)

### ✅ 步骤 7: 集群验证（已完成）
- [x] `kubectl get nodes/pods -A` 基线检查
- [x] 所有 Pod 状态为 Running：控制面组件、网络组件、系统组件
- [x] 集群完全就绪，可以部署应用

### ✅ 步骤 8: 为其他节点安装 kubectl（已完成）
- [x] 在 node1 和 node2 上安装 kubectl v1.32.3
- [x] 复制 master 的 kubeconfig 配置文件到其他节点
- [x] 验证所有节点都能正常访问 Kubernetes 集群

## 📝 详细安装过程记录

### 步骤 1: 系统环境准备

#### 1.1 系统重装与清理
- 腾讯云服务器实例重装系统，确保硬盘完全清空
- 验证无残留 Kubernetes 相关目录和服务

#### 1.2 主机名配置
```bash
# Master 节点
sudo hostnamectl set-hostname master

# Node1 节点  
sudo hostnamectl set-hostname node1

# Node2 节点
sudo hostnamectl set-hostname node2
```

#### 1.3 网络配置

> **提示**: 可以使用提供的脚本自动配置网络：
> - `./setup-master-gateway.sh` - 在 Master 节点执行
> - `./setup-node1.sh` - 在 Node1 节点执行  
> - `./setup-node2.sh` - 在 Node2 节点执行

**Master 节点配置为 NAT 网关：**
```bash
# 启用 IP 转发
echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 清空现有 iptables 规则
sudo iptables -F
sudo iptables -t nat -F
sudo iptables -t mangle -F
sudo iptables -X
sudo iptables -t nat -X
sudo iptables -t mangle -X

# 设置默认策略
sudo iptables -P INPUT ACCEPT
sudo iptables -P FORWARD ACCEPT
sudo iptables -P OUTPUT ACCEPT

# 配置 NAT 规则 - 允许内网节点通过 master 访问外网
sudo iptables -t nat -A POSTROUTING -s 172.17.0.0/20 -o eth0 -j MASQUERADE

# 允许转发来自内网的流量
sudo iptables -A FORWARD -s 172.17.0.0/20 -j ACCEPT
sudo iptables -A FORWARD -d 172.17.0.0/20 -j ACCEPT

# 保存 iptables 规则
sudo apt update && sudo apt install -y iptables-persistent
sudo netfilter-persistent save
```

**Node1 和 Node2 配置路由：**
```bash
# 删除默认网关（如果存在）
sudo ip route del default 2>/dev/null || true

# 添加默认网关指向 master
sudo ip route add default via 172.17.0.15

# 验证网络连通性
ping -c 2 172.17.0.15 && echo "✓ 可以访问 master" || echo "✗ 无法访问 master"
ping -c 2 8.8.8.8 && echo "✓ 可以访问外网" || echo "✗ 无法访问外网"
```

#### 1.4 SSH 密钥配置
```bash
# Master 节点生成 SSH 密钥
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""

# 将公钥复制到 Node1 和 Node2
ssh-copy-id ubuntu@172.17.0.43
ssh-copy-id ubuntu@172.17.0.34
```

### 步骤 2: 基础环境准备（所有节点）

#### 2.1 系统更新
```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget vim net-tools gnupg lsb-release ca-certificates apt-transport-https
```

#### 2.2 内核参数配置
```bash
# 加载内核模块
sudo modprobe overlay
sudo modprobe br_netfilter

# 配置内核参数
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

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

sudo sysctl --system
```

#### 2.3 禁用 Swap
```bash
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
```

#### 2.4 防火墙配置
```bash
sudo ufw disable
```

### 步骤 3: 容器运行时安装（所有节点）

#### 3.1 安装 containerd
```bash
# 安装 containerd
sudo apt update
sudo apt install -y containerd

# ① 停止 containerd
sudo systemctl stop containerd

# ② 生成默认配置
sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null

# ③ 注入镜像加速配置（docker.io/quay.io:腾讯云，其它:高校镜像优先）
sudo sed -i '/\[plugins."io.containerd.grpc.v1.cri".registry.mirrors\]/a\
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]\n    endpoint = ["https://mirror.ccs.tencentyun.com"]\n  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."quay.io"]\n    endpoint = ["https://quay.tencentcloudcr.com"]\n  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."ghcr.io"]\n    endpoint = ["https://ghcr.nju.edu.cn"]\n  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."k8s.gcr.io"]\n    endpoint = ["https://gcr.nju.edu.cn"]\n  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]\n    endpoint = ["https://registry-k8s-io.mirrors.sjtug.sjtu.edu.cn"]\n  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]\n    endpoint = ["https://gcr.nju.edu.cn"]' /etc/containerd/config.toml

# ④ 重新加载并启动 containerd
sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl restart containerd

# ⑤ 检查服务状态
sudo systemctl status containerd --no-pager -l
```

#### 3.2 安装 CNI 插件
```bash
# 下载 CNI 插件
CNI_VERSION="v1.3.0"
CNI_TGZ="cni-plugins-linux-amd64-${CNI_VERSION}.tgz"

# 下载 CNI 插件
curl -L --fail --retry 3 --connect-timeout 10 \
  -o "$CNI_TGZ" \
  "https://github.com/containernetworking/plugins/releases/download/${CNI_VERSION}/$CNI_TGZ"

# 安装 CNI 插件
sudo mkdir -p /opt/cni/bin
sudo tar -xzf "$CNI_TGZ" -C /opt/cni/bin/
rm -f "$CNI_TGZ"
```

### 步骤 4: Kubernetes 组件安装（所有节点）

#### 4.1 添加 Kubernetes 仓库
```bash
# 添加 Kubernetes 仓库 (pkgs.k8s.io v1.32)
# 确保 keyrings 目录存在并可读
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
sudo chmod a+r /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list >/dev/null

# 更新包列表
sudo apt update
```

#### 4.2 安装 Kubernetes 组件
```bash
# 安装 kubelet, kubeadm, kubectl
sudo apt install -y kubelet kubeadm kubectl

# 锁定版本防止自动更新
sudo apt-mark hold kubelet kubeadm kubectl
```

#### 4.3 配置 kubelet
```bash
# 配置 kubelet
sudo mkdir -p /var/lib/kubelet
cat <<EOF | sudo tee /var/lib/kubelet/config.yaml
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
authentication:
  anonymous:
    enabled: false
  webhook:
    enabled: true
  x509:
    clientCAFile: /etc/kubernetes/pki/ca.crt
authorization:
  mode: Webhook
clusterDomain: cluster.local
clusterDNS:
  - 10.96.0.10
containerRuntimeEndpoint: unix:///var/run/containerd/containerd.sock
cgroupDriver: systemd
failSwapOn: false
hairpinMode: promiscuous-bridge
healthzBindAddress: 127.0.0.1
healthzPort: 10248
httpCheckFrequency: 20s
imageMinimumGCAge: 2m0s
imageGCHighThresholdPercent: 85
imageGCLowThresholdPercent: 80
iptablesDropBit: 15
iptablesMasqueradeBit: 15
kubeAPIBurst: 10
kubeAPIQPS: 5
makeIPTablesUtilChains: true
maxOpenFiles: 1000000
maxPods: 110
nodeStatusUpdateFrequency: 10s
oomScoreAdj: -999
podCIDR: 10.244.0.0/16
registryBurst: 10
registryPullQPS: 5
resolvConf: /etc/resolv.conf
rotateCertificates: true
runtimeRequestTimeout: 2m0s
serializeImagePulls: true
serverTLSBootstrap: true
streamingConnectionIdleTimeout: 4h0m0s
syncFrequency: 1m0s
volumeStatsAggPeriod: 1m0s
EOF

# 启动 kubelet
sudo systemctl daemon-reload
sudo systemctl enable kubelet
sudo systemctl start kubelet
```

### 步骤 5: 集群初始化（Master 节点）

#### 5.1 初始化集群
```bash
# 初始化 Kubernetes 集群
sudo kubeadm init \
  --apiserver-advertise-address=172.17.0.15 \
  --control-plane-endpoint=172.17.0.15:6443 \
  --kubernetes-version=v1.32.3 \
  --service-cidr=10.96.0.0/12 \
  --pod-network-cidr=10.244.0.0/16 \
  --image-repository=registry.aliyuncs.com/google_containers \
  --upload-certs \
  --ignore-preflight-errors=Swap

# 配置 kubectl
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
```

#### 5.2 生成节点加入命令
```bash
# 生成节点加入命令
JOIN_COMMAND=$(kubeadm token create --print-join-command)
echo "节点加入命令:"
echo "$JOIN_COMMAND"
echo "$JOIN_COMMAND" > node-join-command.txt
```

### 步骤 6: 网络插件安装（Master 节点）

#### 6.1 下载 Flannel 清单
```bash
# 下载 Flannel v0.27.4
FLANNEL_VER="v0.27.4"
curl -fsSL https://raw.githubusercontent.com/flannel-io/flannel/${FLANNEL_VER}/Documentation/kube-flannel.yml -O

# 修改 Flannel 配置
sed -i 's|"Network": "10.244.0.0/16"|"Network": "10.244.0.0/16"|g' kube-flannel.yml
```

#### 6.2 预拉取 Flannel 镜像
```bash
# 预拉取并打标签
REGISTRY_K8S_MIRROR="registry-k8s-io.mirrors.sjtug.sjtu.edu.cn"
GHCR_MIRROR="ghcr.tencentcloudcr.com"

# 预拉取 pause 镜像
sudo ctr -n k8s.io images pull ${REGISTRY_K8S_MIRROR}/pause:3.8 || true
sudo ctr -n k8s.io images tag ${REGISTRY_K8S_MIRROR}/pause:3.8 registry.k8s.io/pause:3.8 || true

# 预拉取 flannel 镜像
sudo ctr -n k8s.io images pull ${GHCR_MIRROR}/flannel-io/flannel:${FLANNEL_VER} || true
sudo ctr -n k8s.io images tag ${GHCR_MIRROR}/flannel-io/flannel:${FLANNEL_VER} ghcr.io/flannel-io/flannel:${FLANNEL_VER} || true
```

#### 6.3 安装 Flannel
```bash
# 安装 Flannel
kubectl apply -f kube-flannel.yml

# 等待 Flannel 组件就绪
kubectl -n kube-flannel rollout status daemonset/kube-flannel-ds --timeout=600s
kubectl wait --for=condition=ready pod -l app=flannel -n kube-flannel --timeout=600s

# 等待 CoreDNS 就绪
kubectl -n kube-system rollout status deploy/coredns --timeout=600s
```

### 步骤 7: 节点加入集群

#### 7.1 节点加入
```bash
# 检查是否存在加入命令文件
if [ ! -f "node-join-command.txt" ]; then
    echo "错误: 找不到 node-join-command.txt 文件"
    echo "请先运行 k8s-step4-init-cluster.sh 初始化集群"
    exit 1
fi

# 读取加入命令
JOIN_COMMAND=$(cat node-join-command.txt)
echo "使用加入命令: $JOIN_COMMAND"

# Node1 加入集群
ssh ubuntu@172.17.0.43 "sudo $JOIN_COMMAND"

# Node2 加入集群  
ssh ubuntu@172.17.0.34 "sudo $JOIN_COMMAND"

# 等待节点加入
sleep 30

# 验证集群状态
kubectl get nodes
kubectl get pods -n kube-system
kubectl get pods -n kube-flannel
```

### 步骤 8: 集群验证

#### 8.1 验证节点状态
```bash
kubectl get nodes
```

#### 8.2 验证 Pod 状态
```bash
kubectl get pods -A
```

#### 8.3 验证集群功能
```bash
# 检查集群信息
kubectl cluster-info

# 检查节点详细信息
kubectl describe nodes
```

### 步骤 9: 为其他节点安装 kubectl

#### 9.1 在 node1 和 node2 安装 kubectl
```bash
# 检查是否已安装
if command -v kubectl &> /dev/null; then
    echo "kubectl 已安装，版本: $(kubectl version --client 2>/dev/null | grep 'Client Version' || echo 'unknown')"
    echo "跳过安装"
    exit 0
fi

# 安装 kubectl
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl

# 添加 Kubernetes 官方 GPG key
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# 添加 Kubernetes apt 仓库
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# 更新包列表并安装 kubectl
sudo apt update
sudo apt install -y kubectl
```

#### 9.2 复制 kubeconfig 配置文件
```bash
# 在 master 节点执行
# 为 node1 创建 .kube 目录
ssh ubuntu@172.17.0.43 "mkdir -p ~/.kube"

# 为 node2 创建 .kube 目录
ssh ubuntu@172.17.0.34 "mkdir -p ~/.kube"

# 复制 kubeconfig 到 node1
scp ~/.kube/config ubuntu@172.17.0.43:~/.kube/config

# 复制 kubeconfig 到 node2
scp ~/.kube/config ubuntu@172.17.0.34:~/.kube/config
```

#### 9.3 验证 kubectl 连接
```bash
# 验证 node1 kubectl 连接
ssh ubuntu@172.17.0.43 "kubectl get nodes"

# 验证 node2 kubectl 连接
ssh ubuntu@172.17.0.34 "kubectl get nodes"
```