Kubernetes集群部署笔记

发布于2021-08-31，最后编辑于2024-10-25，全文约4382字，阅读时间约9分钟。

Kubernetes Debian Helm kubeadm containerd flannel kube-router metallb podman skopeo docker

概述¶

本文用于整理基于Debian操作系统使用kubeadm工具部署Kubernetes集群的操作过程。该集群部署于一组本地虚拟服务器上，用于学习Kubernetes的基础概念和基本操作，并作为今后其他学习内容的实践部署提供环境。

考虑到不同的网络环境，本文中一些步骤会记录两种操作方式，通过镜像等方式加快部署效率、避免部署错误。有关镜像同步的方案，可参考附件内容中的同步所需镜像。

随着操作系统和各相关组件版本的更新，笔者将在验证通过后对本文进行补充和更新，请参考更新记录。

本文未包含集群日志采集相关演练内容，可参考笔者的另一篇笔记《Kubernetes环境OpenSearch部署与应用》中的演练内容。

服务器¶

受限于本地物理服务器的配置，虚拟服务器配置规划如下表。

所有虚拟服务器CPU均为amd64架构。

截止本文发布时，笔者基于最新Debian 11 (“bullseye”)部署的集群仍然存在一些问题，故暂且发布基于Debian 10 (“buster”)的笔记。

网络环境¶

本地网络IP地址范围为10.0.0.0/24，其中：

• 10.0.0.2-10.0.0.99为静态分配，供虚拟服务器使用。
• 10.0.0.100-10.0.0.200用于DHCP自动分配。
• 10.0.0.201-10.0.0.254为静态分配，供负载均衡器使用。

其他组件¶

• 容器运行时 containerd v1.7.22

• Pod网络组件 flannel v0.14.0 kube-router v2.2.2

• 负载均衡器 metallb v0.14.8

• 持久卷供应 local-path-provisioner v0.0.30

• 指标服务 metrics-server v0.7.2

准备工作¶

服务器配置¶

本文假设服务器硬件和操作系统已经配置完毕，所有服务器上都已经正确配置了ssh服务和sudo权限。

作为参考，这里记录笔者配置sudo权限和ssh服务的过程。

• 配置sudo权限

  如操作人员的登录用户已经被正确配置了sudo权限，可跳过此步骤。

  本示例中，操作人员的登录用户名为tiscs，需要实际环境情况进行替换。

  1# 使用root用户登录系统
  2# 安装sudo，并配置sudo权限
  3apt update
  4apt install sudo
  5echo "tiscs ALL=(ALL) NOPASSWD: ALL" | tee /etc/sudoers.d/tiscs # 这在生产环境绝不是个好主意，仅仅是为了演练环境操作方便
  

• 配置ssh服务

  1# sudo sed -i 's/http:/https:/g' /etc/apt/sources.list
  2# 安装openssh-server，并配置ssh服务为自动启动
  3sudo apt update
  4sudo apt install openssh-server
  5sudo systemctl enable ssh --now
  

也可以参考笔者的原创视频：《演练环境准备——部署虚拟服务器》。

配置过程¶

安装容器运行时¶

本文配置的集群选择containerd作为容器运行时。

在所有节点上执行如下操作。

• 配置模块加载

  1cat <<EOF | sudo tee /etc/modules-load.d/containerd.conf > /dev/null
  2overlay
  3br_netfilter
  4EOF
  5
  6sudo modprobe overlay
  7sudo modprobe br_netfilter
  

• 配置sysctl参数

  1cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes-cri.conf > /dev/null
  2net.bridge.bridge-nf-call-iptables  = 1
  3net.ipv4.ip_forward                 = 1
  4net.bridge.bridge-nf-call-ip6tables = 1
  5EOF
  6
  7sudo sysctl --system
  

• 配置APT源

  1# 安装依赖项
  2sudo apt install -y ca-certificates curl gnupg
  

  1curl -fsSL https://download.docker.com/linux/debian/gpg \
  2  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
  3echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  4  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  

• 安装containerd

  1sudo apt update
  2sudo apt install -y containerd.io
  

• 初始化配置

  1sudo mkdir -p /etc/containerd
  2containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
  

  1# 配置systemd cgroup驱动
  2sudo sed -i -e 's|SystemdCgroup = false|SystemdCgroup = true|g' /etc/containerd/config.toml
  

  1# （可选）配置sandbox image地址
  2# 为了方便，这里配置为与kubelet所需相同的版本（可以使用kubeadm config images list命令查看）
  3sudo sed -i -e 's|"registry.k8s.io/pause:.\+"|"quay.io/choral-k8s/pause:3.10"|g' /etc/containerd/config.toml
  

  1# 重启containerd服务，使上述配置修改生效
  2sudo systemctl restart containerd
  

安装kubeadm¶

在所有节点上执行如下操作。

• 配置APT源

  1curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key \
  2  | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
  3echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /" \
  4  | sudo tee /etc/apt/sources.list.d/kubernetes.list
  

• 安装kubeadm、kubelet和kubectl

  1# apt-cache madison kubeadm | head -1 # check latest release
  2sudo apt update
  3sudo apt install -y kubeadm=1.31.2-1.1 kubelet=1.31.2-1.1 kubectl=1.31.2-1.1 # --allow-change-held-packages
  4sudo apt-mark hold kubelet kubeadm kubectl
  

• 安装并配置crictl（可选）

  可以安装并配置crictl，便于在k8s节点上管理容器运行时。

   1# 安装crictl工具
   2sudo apt install -y cri-tools
   3
   4# 配置crictl使用containerd运行时
   5cat <<EOF | sudo tee /etc/crictl.yaml > /dev/null
   6runtime-endpoint: unix:///run/containerd/containerd.sock
   7image-endpoint: unix:///run/containerd/containerd.sock
   8timeout: 10
   9debug: false
  10EOF
  11
  12# 验证crictl配置
  13sudo crictl images # 列出所有镜像
  

配置控制平面节点¶

在k8s-n0节点上执行如下操作。

• 预先下载所需镜像

  1# 查看所需的镜像列表
  2kubeadm config images list --kubernetes-version=v1.31.2 # --image-repository quay.io/choral-k8s
  3
  4# 1. 使用默认容器镜像仓库
  5sudo kubeadm config images pull --kubernetes-version=v1.31.2
  6
  7# 2. 使用指定容器镜像仓库
  8sudo kubeadm config images pull --kubernetes-version=v1.31.2 --image-repository quay.io/choral-k8s
  

• 初始化控制平面节点

   1# --apiserver-advertise-address   当前节点IP地址
   2# --pod-network-cidr              Pod网络地址段（CIDR: https://datatracker.ietf.org/doc/html/rfc4632）
   3# --skip-phases=addon/kube-proxy  跳过安装kube-proxy组件（使用`kube-router`作为网络组件）
   4
   5# 1. 使用默认容器镜像仓库
   6sudo kubeadm init --apiserver-advertise-address 10.0.0.50 \
   7  --pod-network-cidr=10.244.0.0/16 --kubernetes-version=v1.31.2 \
   8  --skip-phases=addon/kube-proxy
   9
  10# 2. 使用指定容器镜像仓库
  11sudo kubeadm init --apiserver-advertise-address 10.0.0.50 \
  12  --pod-network-cidr=10.244.0.0/16 --kubernetes-version=v1.31.2 \
  13  --skip-phases=addon/kube-proxy \
  14  --image-repository quay.io/choral-k8s
  

  执行完上述操作后，kubeadm init命令会输出用于添加节点到集群中的说明，请保存该说明中的内容。示例如下：

  1sudo kubeadm join 10.0.0.50:6443 \
  2  --token vafq03.5dl6j1cbcd1yzf3c \
  3  --discovery-token-ca-cert-hash sha256:6a725d98e0f6bda713c9f93b8441a735cc60e8ec7454fbe960c74ab80683f938
  

• 添加kubectl配置（可选）

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

安装网络组件¶

• 安装flannel（已废弃，使用kube-router代替）

  1# 1. 使用默认镜像仓库（quay.io/coreos）安装
  2kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
  3
  4# 2 如果访问raw.githubusercontent.com上的文件存在网络问题
  5#   可以使用jsdelivr提供的GitHub CDN地址（https://www.jsdelivr.com/github）
  6kubectl apply -f https://cdn.jsdelivr.net/gh/coreos/flannel@master/Documentation/kube-flannel.yml
  

• 安装kube-router

  1curl -s https://cdn.jsdelivr.net/gh/cloudnativelabs/[email protected]/daemonset/generic-kuberouter-all-features.yaml \
  2  | sed \
  3    -e "s|%APISERVER%|$(kubectl get cm -n kube-public -o yaml cluster-info | sed -n 's/^ \+server: \(.\+\)/\1/p')|g" \
  4    -e "s|%CLUSTERCIDR%|$(kubectl get cm -n kube-system -o yaml kubeadm-config | sed -n 's/^ \+podSubnet: \(.\+\)/\1/p')|g" \
  5    -e "s|\(\s\+\)args:|\1args:\n\1- \"--advertise-loadbalancer-ip=true\"\n\1- \"--hairpin-mode=true\"|g" \
  6    -e "s|docker.io/cloudnativelabs/kube-router\$|quay.io/choral-k8s/kube-router:v2.2.2|g" \
  7  | kubectl apply -f -
  8# 检查组件部署成功
  9kubectl get pods -n kube-system
  

添加工作节点¶

在k8s-n1、k8s-n2和k8s-n3节点上执行如下操作。该操作中需要的token值和hash值通过上述步骤中的kubeadm init操作获取。

• 添加工作节点

  1sudo kubeadm join 10.0.0.50:6443 \
  2  --token vafq03.5dl6j1cbcd1yzf3c \
  3  --discovery-token-ca-cert-hash sha256:6a725d98e0f6bda713c9f93b8441a735cc60e8ec7454fbe960c74ab80683f938
  

• 查看节点状态

  在k8s-n0节点上执行如下操作。

  1kubectl get nodes
  

安装Helm工具（可选）¶

本文暂不涉及使用helm执行的操作，该步骤可选。

• 安装Helm工具

  1# 下载并安装
  2curl -sL https://get.helm.sh/helm-v3.16.1-linux-amd64.tar.gz | tar xzf - linux-amd64/helm
  3sudo cp ./linux-amd64/helm /usr/local/bin/helm
  4rm -rf ./linux-amd64
  5sudo chown root:root /usr/local/bin/helm
  6sudo chmod 755 /usr/local/bin/helm
  7
  8# 验证helm安装
  9helm version
  

安装Metrics Server（可选）¶

部署metrics server以启用指标服务，未安装metrics server前，kubectl top命令无法正常执行。

在k8s-n0节点上执行如下操作。

• 执行清单文件

  这里需要注意，为解决证书错误，需要添加metrics-server容器的参数--kubelet-insecure-tls，这里选择通过sed命令修改清单文件后再使用kubectl执行。

   1# 1. 使用官方镜像地址直接安装
   2curl -sL https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml \
   3  | sed -e "s|\(\s\+\)- args:|\1- args:\n\1  - --kubelet-insecure-tls|" | kubectl apply -f -
   4
   5# 2. 使用自定义镜像地址安装
   6curl -sL https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml \
   7  | sed \
   8    -e "s|\(\s\+\)- args:|\1- args:\n\1  - --kubelet-insecure-tls|" \
   9    -e "s|registry.k8s.io/metrics-server|quay.io/choral-k8s|g" \
  10  | kubectl apply -f -
  11
  12# 3. 查看集群指标信息
  13kubectl top nodes
  14kubectl top pods -n kube-system
  

安装负载均衡组件¶

由云服务商提供的Kubernetes服务，通常会提供内置的负载均衡实现，而笔者部署环境为私有环境，需要一个轻量的负载均衡实现以支撑LoadBalancer类型的服务。

笔者选择MetalLB作为负载均衡实现，配置为二层网络模式。LoadBalancer地址范围配置为10.0.0.201-10.0.0.254，需根据具体网络环境进行修改。

在k8s-n0节点上执行如下操作。

• 安装MetalLB

   1# 创建用于部署MetalLB的命名空间
   2kubectl create namespace metallb-system
   3
   4# 1. 直接执行清单文件
   5kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.14.8/config/manifests/metallb-frr.yaml
   6
   7# 2. 为避免特殊网络环境中的清单文件加载问题，可以使用jsdelivr提供的加速方案
   8kubectl apply -f https://cdn.jsdelivr.net/gh/metallb/[email protected]/config/manifests/metallb-frr.yaml
   9
  10# 创建地址池配置文件
  11cat <<EOF | kubectl apply -f - > /dev/null
  12apiVersion: metallb.io/v1beta1
  13kind: IPAddressPool
  14metadata:
  15  name: default-pool
  16  namespace: metallb-system
  17spec:
  18  addresses:
  19    - 10.0.0.201-10.0.0.254
  20EOF
  21
  22# 创建二层广播配置文件
  23cat <<EOF | kubectl apply -f - > /dev/null
  24apiVersion: metallb.io/v1beta1
  25kind: L2Advertisement
  26metadata:
  27  name: default-l2ad
  28  namespace: metallb-system
  29spec:
  30  ipAddressPools:
  31    - default-pool
  32EOF
  

安装持久卷供应程序¶

Kubernetes内置的local-storage存储类无法动态供应卷，为便于基于该环境演练时自动创建持久卷，选择使用local-path-provisioner作为持久卷供应程序。

• 创建所需的目录

  在所有节点上执行如下操作。

  1sudo mkdir -p /opt/local-path-provisioner
  

• 安装local-path-provisioner

  在k8s-n0节点上执行如下操作。

   1# 1. 使用官方清单文件地址直接安装
   2kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.30/deploy/local-path-storage.yaml
   3#   1.1 同样可以使用jsdelivr提供的加速方案
   4kubectl apply -f https://cdn.jsdelivr.net/gh/rancher/[email protected]/deploy/local-path-storage.yaml
   5
   6# 2. 替换命名空间
   7curl -s https://cdn.jsdelivr.net/gh/rancher/[email protected]/deploy/local-path-storage.yaml \
   8  | sed \
   9    -e "1,6d" \
  10    -e "s|namespace: local-path-storage|namespace: kube-system|" \
  11    -e "s|image: rancher|image: quay.io/choral-k8s|" \
  12    -e "s|image: busybox|image: quay.io/choral-k8s/busybox|" \
  13  | kubectl apply -f -
  

• 配置默认存储类

  1kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
  

检查集群工作状态¶

在k8s-n0节点上执行如下操作。

• 查看节点状态

  1kubectl get nodes
  

  1kubectl top nodes
  

• 查看Pod状态

  1kubectl get pods -A
  

  1kubectl top pods -A
  

附加内容¶

同步所需镜像¶

由于特殊网络环境问题，需要同步kubelet所需镜像至其他镜像仓库的，可参考如下操作。

笔者开发环境中使用podman管理容器和镜像，已将docker设置为podman的别名（alias docker=podman）。

• 同步kubelet所需镜像

  首先，需要创建自定义镜像仓库认证凭据。

  1# 根据需要将`quay.io`替换为自定义镜像仓库地址
  2docker login quay.io
  

  创建一个脚本k8s_mirror_sync.sh，内容如下。

   1# k8s_mirror_sync.sh
   2# 根据需要将`quay.io/choral-k8s/`替换为自定义镜像仓库地址
   3while read o
   4  do {
   5      t=$(echo $o | sed -e 's|registry.k8s.io.*/|quay.io/choral-k8s/|g' -e 's|registry.k8s.io.*/|quay.io/choral-k8s/|g')
   6      docker pull $o
   7      docker tag $o $t
   8      docker push $t
   9      docker rmi $o
  10      docker rmi $t
  11  }
  12done < "${1:-/dev/stdin}"
  

  该脚本有两种使用方法。

  1kubeadm config images list --kubernetes-version=v1.31.2 | bash k8s_mirror_sync.sh
  

  1# 列出所需镜像列表并保存到文件
  2kubeadm config images list --kubernetes-version=v1.31.2 > k8s-image-list
  3# 拷贝该文件至k8s_mirror_sync.sh所在主机，然后执行该脚本
  4bash k8s_mirror_sync.sh k8s-image-list
  

• 同步附加组件镜像

  1# 根据需要将`quay.io/choral-k8s/`替换为自定义镜像仓库地址。
  2
  3# 同步metrics server所需镜像
  4docker pull registry.k8s.io/metrics-server/metrics-server:v0.7.2
  5docker tag registry.k8s.io/metrics-server/metrics-server:v0.7.2 quay.io/choral-k8s/metrics-server:v0.7.2
  6docker push quay.io/choral-k8s/metrics-server:v0.7.2
  7docker rmi registry.k8s.io/metrics-server/metrics-server:v0.7.2
  8docker rmi quay.io/choral-k8s/metrics-server:v0.7.2
  

• 使用GitHub Actions同步镜像

  整理上面步骤中的脚本后，可以使用GitHub Actions执行镜像同步任务，使用skopeo工具同步镜像。

  首先创建GitHub Actions执行时所需的Secrets。

  1# GitHub Actions Secrets
  2CONTAINER_REGISTRY_NAMESPACE: 'choral-k8s' # 根据需要将`choral-k8s`替换为自定义命名空间
  3CONTAINER_REGISTRY_HOSTNAME:  'quay.io'    # 根据需要将`quay.io`替换为自定义镜像仓库主机名称
  4CONTAINER_REGISTRY_USERNAME:  '<REDACTED>'
  5CONTAINER_REGISTRY_PASSWORD:  '<REDACTED>'
  

  创建一个GitHub Actions配置文件，例如.github/workflows/sync-kubeadm-images.yml。

   1name: Sync images required by kubeadm
   2
   3on:
   4  push:
   5    branches: [ "main" ]
   6
   7jobs:
   8  sync-images:
   9    runs-on: ubuntu-latest
  10    container:
  11      image: quay.io/skopeo/stable:latest
  12      env:
  13        KUBERNETES_VERSION:           v1.31.2 # 需要同步镜像的`kubernetes`版本
  14        CONTAINER_REGISTRY_HOSTNAME:  ${{ secrets.CONTAINER_REGISTRY_HOSTNAME  }}
  15        CONTAINER_REGISTRY_USERNAME:  ${{ secrets.CONTAINER_REGISTRY_USERNAME  }}
  16        CONTAINER_REGISTRY_PASSWORD:  ${{ secrets.CONTAINER_REGISTRY_PASSWORD  }}
  17        CONTAINER_REGISTRY_NAMESPACE: ${{ secrets.CONTAINER_REGISTRY_NAMESPACE }}
  18
  19    steps:
  20      - run: |
  21          curl -sL https://dl.k8s.io/release/$KUBERNETES_VERSION/bin/linux/amd64/kubeadm -o /usr/local/bin/kubeadm
  22          chmod 755 /usr/local/bin/kubeadm
  23          kubeadm version
  24          kubeadm config images list --kubernetes-version=$KUBERNETES_VERSION          
  25      - run: |
  26          echo $CONTAINER_REGISTRY_PASSWORD | skopeo login --username $CONTAINER_REGISTRY_USERNAME --password-stdin $CONTAINER_REGISTRY_HOSTNAME
  27          for o in $(kubeadm config images list --kubernetes-version=$KUBERNETES_VERSION); do
  28            t=$(echo $o | sed "s|registry.k8s.io.*/|$CONTAINER_REGISTRY_HOSTNAME/$CONTAINER_REGISTRY_NAMESPACE/|g" | sed "s|registry.k8s.io.*/|$CONTAINER_REGISTRY_HOSTNAME/$CONTAINER_REGISTRY_NAMESPACE/|g")
  29            echo "Syncing $o"
  30            skopeo copy --all docker://$o docker://$t
  31          done          
  

  执行上述配置文件定义的GitHub Actions时，将指定版本Kubernetes所需的镜像同步到指定仓库的指定命名空间中。

参考资料¶

• https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/

• https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/

• https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/

• https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes/

• https://github.com/flannel-io/flannel/blob/master/Documentation/kubernetes.md

• https://www.kube-router.io/docs/user-guide/

• https://helm.sh/docs/intro/install/

• https://github.com/kubernetes-sigs/metrics-server

• https://metallb.org/installation/

• https://github.com/rancher/local-path-provisioner