Debian12 使用 kubeadm 安装 Kubernetes (k8s) 1.32.0 （CRI-O 容器运行时）（一控制节点+多工作节点）

创建日期：2023/06/15 修改日期：2025/01/19 Linux Docker Kubernetes

> 官方文档：[使用 kubeadm 引导集群](https://kubernetes.io/zh-cn/docs/setup/production-environment/tools/kubeadm/)

说明：由于大陆拉取镜 `docker.io` 像存在问题，需要准备一个可用的镜像代理，否则无法正常安装

# 说明

1. 本教程适用于开发或测试环境，因为仅有一个控制节点，生产环境应当有多个控制节点
2. 下文的命令除特殊说明外，在所有主机上都需要执行

下文的机器环境信息如下：

| 主机名     | ip              | 角色     |
| ---------- | --------------- | -------- |
| controller | 192.168.220.201 | 控制节点 |
| work1      | 192.168.220.202 | 工作节点 |
| work2      | 192.168.220.203 | 工作节点 |

# 系统检查与配置

## 机器唯一性

确保每个节点上 `MAC` 地址和 `product_uuid` 的唯一性

- 使用命令 `ip link` 或 `ifconfig -a` 来获取网络接口的 `MAC` 地址
- 可以使用 `cat /sys/class/dmi/id/product_uuid` 命令对 `product_uuid` 校验

## 关闭 swap

`kubelet` 在节点上检测到交换内存时无法启动，执行以下命令关闭

> 立即关闭

```bash
swapoff -a
```

> 永久关闭

编辑配置文件

```bash
vim /etc/fstab
```

在 `/etc/fstab` 中 `swap` 分区这行前加 `#`

```
# /dev/mapper/centos-swap swap swap defaults 0 0
```

## 设置 hostname

在**各自节点**设置

```bash
# node1
hostnamectl set-hostname controller
# node2
hostnamectl set-hostname work1
# node3
hostnamectl set-hostname work2
```

之后再**各自节点**设置对应的 `hosts` 解析

```bash
# 编辑 hosts 文件
vim /etc/hosts
# 添加如下内容（ xxx 为 hostname 名称）
127.0.0.1 xxx
```

## 设置网络与文件存储

### 加载系统模块

> 立即生效

```bash
modprobe overlay
modprobe br_netfilter
```

> 永久配置

```bash
cat <<EOF | tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
```

### 配置 sysctl

写入配置文件永久生效

```bash
cat <<EOF | 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
```

保存后执行命令立即生效

```bash
sysctl -p
```

# 安装容器运行时 CRI-O

`Kubernetes` 需要在集群内每个节点上安装一个 **容器运行时**（容器运行时是负责运行容器的软件） 以使 `Pod` 可以运行在上面。下文介绍 CRI-O

## 更新 apt 包索引并安装基础软件

```bash
apt-get update
apt-get install -y curl gnupg
```

## 添加 cri-o 的密钥

```bash
# 官方源（需要可以访问外网）
curl -fsSL https://pkgs.k8s.io/addons:/cri-o:/stable:/v1.32/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/cri-o-apt-keyring.gpg

# 清华源
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/kubernetes/addons:/cri-o:/stable:/v1.32/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/cri-o-apt-keyring.gpg
```

## 设置存储库并更新缓存

设置源

```bash
# 官方源（需要可以访问外网）
echo "deb [signed-by=/etc/apt/keyrings/cri-o-apt-keyring.gpg] https://pkgs.k8s.io/addons:/cri-o:/stable:/v1.32/deb/ /" | tee /etc/apt/sources.list.d/cri-o.list

# 清华源
echo "deb [signed-by=/etc/apt/keyrings/cri-o-apt-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/kubernetes/addons:/cri-o:/stable:/v1.32/deb/ /" | tee /etc/apt/sources.list.d/cri-o.list
```

更新源

```bash
apt-get update
```

## 安装 cri-o

```bash
apt-get install -y cri-o
```

## 配置 cri-o

### 配置 pause 镜像

`cri-o` 默认使用的 `pause` 可能会比 `k8s` 要求的版本低，具体对应的版本，通过查看编译文件 [https://github.com/kubernetes/kubernetes/blob/v1.32.0/build/pause/Makefile](https://github.com/kubernetes/kubernetes/blob/v1.32.0/build/pause/Makefile) 中 `TAG ?=` 的值

```bash
# 编辑配置文件（默认是新文件）
vim /etc/crio/crio.conf

# 添加如下内容并保存
[crio.image]
pause_image="registry.k8s.io/pause:3.10"

# 重启服务
systemctl restart crio.service
```

注：如果下载镜像需要使用大陆镜像节点，则上述的 `pause_image` 值改为 `registry.aliyuncs.com/google_containers/pause:3.10`

### 配置 docker.io 镜像

若不能正常访问 `docker.io` 拉取镜像，则需要执行以下配置，其中镜像地址自行准备（即下文中的 `192.168.100.98:5000` ）

```bash
# 编辑配置文件（默认是新文件）
vim /etc/containers/registries.conf

# 添加如下内容并保存
unqualified-search-registries = ["docker.io"]
[[registry]]
location="docker.io"
[[registry.mirror]]
location="192.168.100.98:5000"
insecure = true

# 重启服务
systemctl restart crio.service
```

# 安装 k8s

## 秘钥

```bash
# 官方源（需要可以访问外网）
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# 清华源
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/kubernetes/core:/stable:/v1.32/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
```

## apt 源

设置源，二选一即可

```bash
# 官方源（需要可以访问外网）
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list

# 清华源
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/kubernetes/core:/stable:/v1.32/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list
```

更新源

```bash
apt-get update
```

## 安装服务

```bash
# 安装最新版本（2025-01-04最新）
apt-get install -y kubelet=1.32.0-1.1 kubeadm=1.32.0-1.1 kubectl=1.32.0-1.1

# 保持当前版本
apt-mark hold kubelet kubeadm kubectl
```

# 部署

## 部署控制节点

### 执行初始化

在**控制节点**上执行以下命令

```bash
# 官方源（需要可以访问外网）
kubeadm init \
  --apiserver-advertise-address=192.168.220.201 \
  --kubernetes-version v1.32.0 \
  --pod-network-cidr=10.244.0.0/16

# 阿里源（使用 --image-repository 指定镜像源）
kubeadm init \
  --apiserver-advertise-address=192.168.220.201 \
  --kubernetes-version v1.32.0 \
  --pod-network-cidr=10.244.0.0/16 \
  --image-repository=registry.aliyuncs.com/google_containers
```

初始化之后会显示如下类似内容

Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

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

Alternatively, if you are the root user, you can run:

export KUBECONFIG=/etc/kubernetes/admin.conf

You should now deploy a pod network to the cluster.
	Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
	  https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 192.168.220.201:6443 --token lva03p.dc88fr2bpoquka5u \
		--discovery-token-ca-cert-hash sha256:9136787e06152d907ae1ac62b61ce87abce909767761e32124fd72564b080a1e

其中 `kubeadm join xxxxxx --token xxxxxx \ --discovery-token-ca-cert-hash xxxxxx` 需要复制下来，用于从节点加入使用。

默认 `token` 有效期为24小时，当过期之后，需要重新创建 `token` ，命令如下：

```bash
kubeadm token create --print-join-command
```

### 允许当前用户访问 k8s

继续在**控制节点**上执行以下命令

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

## 部署工作节点

在**工作节点**执行上文中提交的以下命令

```bash
kubeadm join 192.168.220.201:6443 --token g9t71p.wajxnogsklp2l02z \
	--discovery-token-ca-cert-hash sha256:b20b3beed6eb847aac5085777e92b2c701a779b4e6e89d625d50c838f6e2cafd
```

## 配置网络插件

在**控制节点**上执行以下命令：

```bash
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
```

# 测试

在**控制节点**上执行以下命令：

```bash
kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl get nodes,pod,svc
```

展示类似于如下信息：

NAME         STATUS   ROLES           AGE     VERSION
	node/node1   Ready    control-plane   2m22s   v1.32.0
	node/node2   Ready    <none>          2m4s    v1.32.0
	node/node3   Ready    <none>          2m3s    v1.32.0
	
	NAME                         READY   STATUS    RESTARTS   AGE
	pod/nginx-5869d7778c-gxd5d   1/1     Running   0          22s
	
	NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
	service/kubernetes   ClusterIP   10.96.0.1        <none>        443/TCP        2m22s
	service/nginx        NodePort    10.105.226.241   <none>        80:32576/TCP   22s

通过访问 `ip:32576` （端口是随机的，根据展示信息自行修改）查看页面

# 补充

## 命令自动补全

在**控制节点**执行以下命令，后续使用时按 `tab` 键可以自动补全命令

```bash
mkdir /etc/bash_completion.d/
kubectl completion bash | tee /etc/bash_completion.d/kubectl > /dev/null
kubeadm completion bash | tee /etc/bash_completion.d/kubeadm > /dev/null
```

## 安装失败后的重置

如果在执行 `kubeadm init` 或 `kubeadm join` 时出错后需要重新执行，则可以执行以下命令初始化

1. 执行 `kubeadm reset` 重置 `kubeadm` 安装的状态
2. 执行 `iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X` 重置 `iptables`
3. 如果重置的是工作节点，则需要在控制节点执行 `kubectl delete node <节点名称>` 删除被重置的节点

482

全部评论

母夜叉-孙二娘2023/09/06 16:56:39

debian12 kubeadm安装没问题，你是啥问题
管理员回复母夜叉-孙二娘2023/09/06 16:58:47

Debian11/12 安装之后短时间没问题，过了几分钟之后再执行 kubectl get nodes,pod,svc 就报错，后面有时间我再试试
母夜叉-孙二娘回复管理员2023/09/06 17:04:09

看下报错日志，我感觉是containerd的问题
管理员回复母夜叉-孙二娘2025/01/05 18:20:06

确认是 containerd 问题，没有设置为 SystemdCgroup 驱动，不过现在文档中容器运行时已经换成 CRI-O 了