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: 一键安装

# 在 Master 节点运行
./k8s-install-all.sh

方法 2: 分步安装

# 按顺序执行每个步骤
./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: 环境准备（已完成）

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

✅ 步骤 2: 容器运行时准备（所有节点，已完成）

• 更新系统包，安装依赖工具：curl、wget、gnupg、ca-certificates、apt-transport-https 等
• 安装 containerd 并生成默认配置 /etc/containerd/config.toml
• 配置镜像加速：docker.io/quay.io 使用腾讯云镜像，其他使用高校镜像
• 安装 CNI 插件 v1.3.0（在 master 预下载并分发至 node1/node2）
• 启用并开机自启 containerd，确认服务状态正常

✅ 步骤 3: 安装 Kubernetes 组件（所有节点，已完成）

• 添加 Kubernetes APT 仓库（pkgs.k8s.io v1.32），修复 GPG key 与源配置问题
• 安装并锁定版本：kubelet、kubeadm、kubectl 为 v1.32.3
• 配置 kubelet：使用 systemd cgroup，与 containerd 对齐，写入完整配置文件
• 启用并启动 kubelet 服务

✅ 步骤 4: 集群初始化（Master 节点，已完成）

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

✅ 步骤 5: 网络插件安装 (Master 节点，已完成)

• 下载并应用 Flannel v0.27.4 清单
• 匹配 Pod CIDR 10.244.0.0/16，等待组件 Ready
• 配置 Flannel 使用国内镜像源（registry-k8s-io.mirrors.sjtug.sjtu.edu.cn、ghcr.tencentcloudcr.com）
• 预拉取所有 Flannel 镜像并打标签
• 等待所有网络组件就绪：kube-flannel-ds、coredns

✅ 步骤 6: 节点加入集群（已完成）

• 读取 node-join-command.txt 文件中的 join 命令
• 在 node1/node2 执行 join，加入成功后验证 Ready
• 验证所有节点状态：master (Ready, control-plane)、node1 (Ready)、node2 (Ready)

✅ 步骤 7: 集群验证（已完成）

• kubectl get nodes/pods -A 基线检查
• 所有 Pod 状态为 Running：控制面组件、网络组件、系统组件
• 集群完全就绪，可以部署应用

✅ 步骤 8: 为其他节点安装 kubectl（已完成）

• 在 node1 和 node2 上安装 kubectl v1.32.3
• 复制 master 的 kubeconfig 配置文件到其他节点
• 验证所有节点都能正常访问 Kubernetes 集群

📝 详细安装过程记录

步骤 1: 系统环境准备

1.1 系统重装与清理

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

1.2 主机名配置

# 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 网关：

# 启用 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 配置路由：

# 删除默认网关（如果存在）
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 密钥配置

# 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 系统更新

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 内核参数配置

# 加载内核模块
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

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

2.4 防火墙配置

sudo ufw disable

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

3.1 安装 containerd

# 安装 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 插件

# 下载 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 仓库

# 添加 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 组件

# 安装 kubelet, kubeadm, kubectl
sudo apt install -y kubelet kubeadm kubectl

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

4.3 配置 kubelet

# 配置 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 初始化集群

# 初始化 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 生成节点加入命令

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

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

6.1 下载 Flannel 清单

# 下载 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 镜像

# 预拉取并打标签
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

# 安装 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 节点加入

# 检查是否存在加入命令文件
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 验证节点状态

kubectl get nodes

8.2 验证 Pod 状态

kubectl get pods -A

8.3 验证集群功能

# 检查集群信息
kubectl cluster-info

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

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

9.1 在 node1 和 node2 安装 kubectl

# 检查是否已安装
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 配置文件

# 在 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 连接

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

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