Rancher

1 Rancher简介

  Rancher是一个开源软件平台，使组织能够在生产中运行和管理Docker和Kubernetes。使用Rancher，组织不再需要使用一套独特的开源技术从头开始构建容器服务平台。Rancher提供了管理生产中的容器所需的整个软件堆栈。

  在 Kubernetes 环境中部署 Rancher 是构建企业级容器管理平台的重要一步。以云服务器环境为介绍如何使用 Helm 安装 Rancher，包括准备 Helm 工具、配置 Ingress Controller、安装 cert-manager 以及部署 Rancher Server 的完整流程。通过自签名证书方式实现安全访问。

  官网：https://www.rancher.com/

  中文官网：https://www.rancher.cn/

  环境介绍：

操作系统	主机名	公网IP地址	内网IP	VPN内网IP	k8s版本	containerd版本	Docker版本	配置
Rocky Linux 9.4	k8s-master	49.235.53.189	10.0.0.9	10.8.0.13	1.33.5	v2.1.4	v29.0.0	4核4G

2 Rancher的作用

  Rancher 是一个 Kubernetes 管理工具，能在任何地方和任何提供商上部署和运行集群。

  Rancher UI‌：支持多语言（含中文），覆盖企业级复杂场景

  Rancher 可以创建来自 Kubernetes 托管服务提供商的集群，创建节点并安装 Kubernetes，或者导入在任何地方运行的现有 Kubernetes 集群。开源企业级平台，支持多集群管理和生产级容器运维。

  Rancher 基于 Kubernetes 添加了新的功能，包括统一所有集群的身份验证和 RBAC，让系统管理员从一个位置控制全部集群的访问。

  Rancher 可以为集群和资源提供更精细的监控和告警，将日志发送到外部提供商，并通过应用商店（Application Catalog）直接集成 Helm。如果拥有外部 CI/CD 系统，可以将其与 Rancher 对接。没有的话，你也可以使用 Rancher 提供的 Fleet 自动部署和升级工作负载。

  Rancher 是一个全栈式的 Kubernetes 容器管理平台，是一个在任何地方都能成功运行 Kubernetes 的工具。

3 Rancher概述

  Rancher 是一个为使用容器的公司打造的容器管理平台。Rancher 使得开发者可以随处运行 Kubernetes（Run Kubernetes Everywhere），满足 IT 需求规范，赋能 DevOps 团队。

3.1 Run Kubernetes Everywhere

  Kubernetes已经成为容器编排标准。现在，大多数云和虚拟化提供商都提供容器编排服务。

  Rancher 用户可以选择使用 Rancher Kubernetes distributions（RKE2/K3s）或云 Kubernetes 服务（例如 GKE、AKS 和 EKS）创建 Kubernetes 集群，还可以导入和管理使用任何 Kubernetes 发行版或安装程序创建的现有 Kubernetes 集群。

3.2 满足 IT 需求规范

  Rancher 支持对其控制的所有 Kubernetes 集群进行集中认证、访问控制和监控。例如：

   使用 Active Directory 凭证访问由云提供商（例如 GKE）托管的 Kubernetes 集群。

   设置所有用户、组、项目、集群和云服务的权限控制策略和安全策略。

   一站式查看 Kubernetes 集群的运行状况和容量。

3.3 赋能 DevOps 团队

  Rancher 为 DevOps 工程师提供简单直接的用户界面，以管理其应用负载。不需要对 Kubernetes 有非常深入的了解，即可使用 Rancher。

  Rancher 应用商店包含一套实用的 DevOps 开发工具。Rancher 获得了多种云原生生态系统产品的认证，包括安全工具、监控系统、容器镜像仓库、存储和网络驱动等。

  下图讲述了 Rancher 在 IT 管理团队和 DevOps 开发团队之间扮演的角色。DevOps 团队把应用部署在选择的公有云或私有云上。IT 管理员负责查看并管理用户、集群、云服务的权限。

3.4 Rancher API Server 的功能

  Rancher API Server 是基于嵌入式 Kubernetes API Server 和 etcd 数据库建立的，提供了以下功能：

  1.授权和基于角色的权限控制（RBAC）

   用户管理：Rancher API Server 除了管理本地用户，还管理用户用来访问外部服务所需的认证信息，如登录 Active Directory 和 GitHub 所需的账号密码。

   授权：Rancher API Server 可以管理访问控制策略和安全标准。

  2.使用 Kubernetes 的功能

   配置 Kubernetes 集群：Rancher API Server 可以在已有节点上配置 Kubernetes，或进行 Kubernetes 版本升级。

   管理应用商店：Rancher 支持使用 Helm Chart 应用商店实现轻松重复部署应用。

   管理项目：项目由集群中多个命名空间和访问控制策略组成，是 Rancher 中的一个概念，Kubernetes 中并没有这个概念。可以使用项目实现以组为单位，管理多个命名空间，并进行 Kubernetes 相关操作。Rancher UI 提供用于项目管理和项目内应用管理的功能。

   Fleet 持续交付：Rancher中可以使用 Fleet 持续交付将应用程序从 Git 仓库部署到目标下游 Kubernetes 集群，无需任何手动操作。

   Istio：Rancher 与 Istio 集成使得管理员或集群所有者可以将 Istio 交给开发者，然后开发者使用 Istio 执行安全策略，排查问题，或为蓝绿部署、金丝雀部署，和 A/B 测试进行流量管理。

  3.配置云基础设施

   同步节点信息：Rancher API Server 可以同步所有集群中全部节点的信息。

   配置云基础设施：如果为 Rancher 配置了云提供商，Rancher 可以在云端动态配置新节点和持久化存储。

  4.查看集群信息

   日志管理：Rancher 可以与多种 Kubernetes 集群之外的主流日志管理工具集成。

   监控：可以使用 Rancher，通过业界领先并开源的 Prometheus 来监控集群节点、Kubernetes 组件和软件部署的状态和进程。

   告警：为了保证集群和应用的正常运行，提高公司的生产效率，需要随时了解集群和项目的计划内和非计划事件。

  5.使用 Rancher 编辑下游集群

   对于已有集群而言，可提供的选项和设置取决于配置集群的方法。

   使用 Rancher 创建集群后，集群管理员可以管理集群成员，管理节点池，或进行其他操作。

   下表总结了每一种类型的集群和对应的可编辑的选项和设置：

操作	Rancher 启动的 Kubernetes 集群	EKS、GKE 和 AKS 集群1	其他托管的 Kubernetes 集群	非 EKS 或 GKE 注册集群
使用 kubectl 和 kubeconfig 文件来访问集群	✓	✓	✓	✓
管理集群成员	✓	✓	✓	✓
编辑和升级集群	✓	✓	✓	✓2
管理节点	✓	✓	✓	✓3
管理持久卷和存储类	✓	✓	✓	✓
管理项目、命名空间和工作负载	✓	✓	✓	✓
使用应用目录	✓	✓	✓	✓
配置工具（Alerts、Notifiers、Monitoring、Logging 和 Istio）	✓	✓	✓	✓
运行安全扫描	✓	✓	✓	✓
轮换证书	✓	✓
备份和恢复 Rancher 启动的集群	✓	✓		✓4
在 Rancher 无法访问集群时清理 Kubernetes 组件	✓

  1.注册的 EKS、GKE 和 AKS 集群与从 Rancher UI 创建的 EKS、GKE 和 AKS 集群的可用选项一致。不同之处是，从 Rancher UI 中删除已注册的集群后，集群不会被销毁。

  2.无法编辑已注册的集群的集群配置选项（K3s 和 RKE2 集群除外）。

  3.Rancher UI 为已注册的集群节点提供了封锁、清空和编辑节点的功能。

  4.对于使用 etcd 作为 controlplane 的注册集群，必须在 Rancher UI 之外手动创建快照以用于备份和恢复。

4 为什么要用 Rancher？

优势点	描述说明
多集群统一管理	支持集中管理本地、云端、边缘等多个 Kubernetes 集群，简化运维流程
图形化操作界面	提供直观的 Web UI，降低使用门槛，提升操作效率
权限与安全控制	内置 RBAC、审计日志等功能，满足企业安全合规要求
应用部署与 Helm 支持	集成 Helm Chart，可一键部署常用应用，加速 DevOps 流程
多租户与项目隔离	支持按项目划分资源，适合多团队协作又相互隔离的场景

5 部署环境信息

操作系统	主机名	公网IP地址	内网IP	VPN内网IP	角色	k8s版本	containerd版本	配置
Rocky Linux 9.4	k3s-master	124.222.84.111	10.0.0.5	10.8.0.17	master节点	1.33.5	v2.1.4	4核4G

  操作系统: Rocky Linux release 9.4 (Blue Onyx)

  Kubernetes 版本：v1.33.x

  部署方式：云服务器环境，使用 Helm 安装 Rancher

  网络组件：ingress-nginx，以 DaemonSet 模式部署并启用主机网络

  证书方案：Rancher 自签名证书，依赖 cert-manager 自动签发

  容器运行时：使用Docker(Docker version 29.0.0, build 3d4129b)

5.1 关闭防火墙和SELinux

# 下列步骤需要在集群中所有机器上完成

# 关闭防火墙并设置为开机自动关闭
systemctl disable --now firewalld

# 关闭SELinux
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config 

# 临时关闭SELinux
setenforce 0

5.2 修改主机名

1.hostnamectl命名可立即生效
# master节点
  sudo hostnamectl set-hostname k3s-master
  
2.修改配置文件
  2.1 修改主机名配置文件
  # 备份原配置文件 sudo cp /etc/hostname /etc/hostname.backup
  # 修改主机名    echo "new-hostname" | sudo tee /etc/hostname
  
  2.2 更新/etc/hosts文件
  # 备份hosts文件  sudo cp /etc/hosts /etc/hosts.backup
  # 修改hosts文件，确保有对应的解析 sudo sed -i "s/old-hostname/new-hostname/g" /etc/hosts
  # 或者手动编辑，确保包含：
  # 127.0.0.1   localhost new-hostname
  # ::1         localhost new-hostname
  
  2.3 立即生效操作
  # 方法A：使用sysctl（推荐）  sudo sysctl kernel.hostname=new-hostname
  # 方法B：使用hostname命令    sudo hostname new-hostname
  # 方法C：重启hostname服务（某些系统）  sudo systemctl restart systemd-hostnamed

5.3 关闭交换分区

# 下列步骤需要在集群中所有机器上完成

# 关闭当前交换分区
  swapoff -a
# 禁止开机自动启动交换分区
  sed -i 's/.*swap.*/#&/' /etc/fstab

5.4 系统配置优化

# 禁用交换分区（K8s 要求）
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

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

sudo modprobe overlay
sudo modprobe br_netfilter

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

# 重启确保配置生效
sudo reboot

6 Containerd部署

6.1 安装Containerd

  下载包含 containerd 和 nerdctl 的完整工具包。

  解压到 /usr/local 目录，安装所有组件。

  安装 nerdctl-full 版本集成了 containerd 。如主机已安装 containerd 请选择 nerdctl简易版（nerdctl-2.1.6-linux-amd64.tar.gz）

  下载地址：https://github.com/containerd/nerdctl/releases

# 下列步骤需要在集群中所有机器上完成

# 下载nerdctl工具，这个工具使用containerd作为底层运行时，命令行高度兼容docker，是首选方案，下载好之后，把压缩包解压到 /usr/local 目录下，这样就可以方便后面使用

wget https://github.com/containerd/nerdctl/releases/download/v2.1.6/nerdctl-full-2.1.6-linux-amd64.tar.gz
tar Cxzvvf /usr/local nerdctl-full-2.1.6-linux-amd64.tar.gz

# 查看containerd安装好的版本
[root@k3s-master ~]# containerd -v
containerd github.com/containerd/containerd/v2 v2.1.4 75cb2b7193e4e490e9fbdc236c0e811ccaba3376

6.2 生成配置文件

  创建配置目录并生成默认配置文件。

  替换 pause 镜像为国内源，这里的国内源可以是任何你能访问的源。

  配置镜像加速器路径。

# 下列步骤需要在集群中所有机器上完成

# 要给 containerd 做一些配置，让它能更好地工作。首先创建一个配置文件夹 /etc/containerd，然后生成默认的配置文件
mkdir /etc/containerd

# containerd生成配置文件
containerd config default > /etc/containerd/config.toml

# 配置crictl连接containerd
cat >> /etc/crictl.yaml <<EOF
runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: false
EOF

# 修改镜像源
1.修改一下配置文件，把默认的 pause 镜像地址换成一个国内的镜像地址，这样在国内访问会更快
  sed -i "s|sandbox = 'registry.k8s.io/pause:3.10'|sandbox = 'registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.10'|" /etc/containerd/config.toml

2.将 sandbox_image 镜像源设置为阿里云google_containers镜像源
  sed -i "s#registry.k8s.io/pause:3.8#registry.aliyuncs.com/google_containers/pause:3.10#g" /etc/containerd/config.toml

# 设置镜像仓库的配置路径，让containerd知道去哪里找镜像之类的，如果有容器镜像加速器，就应该配置在这个路径下。
# containerd的1.X版本和containerd的2.X版本，这里的路径是不一样的
sed -i '/^\s*\[plugins.'"'"'io.containerd.cri.v1.images'"'"'.registry\]/{n;s|^\(\s*\)config_path = .*$|\1config_path = '"'"'/etc/containerd/certs.d'"'"'|}' /etc/containerd/config.toml

# 配置containerd cgroup 驱动程序为systemd
sed -i 's#SystemdCgroup = false#SystemdCgroup = true#g' /etc/containerd/config.toml

6.3 使用镜像加速器

 在中国需要设置国内镜像加速器，提升拉取镜像的速度

  为了能让 containerd 正常拉取镜像，还要配置一下镜像仓库的证书信息。首先，创建一个目录来存放证书，创建一个配置文件，告诉 containerd 我们要使用一个国内的镜像代理地址，这样拉取镜像会更快。

  Containerd容器可用的免费镜像加速器配置方法。Containerd的配置方式与Docker不同，主要分为旧版本（1.5之前）和新版本（1.5及以上）两种方法‌：

1.旧版本配置方法（1.5之前）
  对于Containerd 1.5版本之前的配置，需要直接修改`/etc/containerd/config.toml`文件：
tomlCopy Code[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://docker.m.daocloud.io", "https://hub-mirror.c.163.com"]

2.新版本配置方法（1.5及以上）
  新版本推荐使用`/etc/containerd/certs.d/`目录进行配置，这种方式支持热加载，无需重启服务：

mkdir /etc/containerd/certs.d/docker.io -p
cat > /etc/containerd/certs.d/docker.io/hosts.toml <<-'EOF'
server = "https://docker-0.unsee.tech"
[host."https://docker-0.unsee.tech"]
  capabilities = ["pull", "resolve", "push"]
EOF

# 修改后需要重启Containerd服务。
systemctl restart containerd

  常用免费加速器地址

   以下是一些可用的免费镜像加速器地址，可以根据需要选择使用‌：

   阿里云镜像加速器：https://<your_id>.mirror.aliyuncs.com（需替换为您的ID）

    https://1016220537097033.mirror.aliyuncs.com

   DaoCloud镜像加速器：https://docker.m.daocloud.io

  优先推荐（就近+稳定）:https://docker.1ms.run、https://docker-0.unsee.tech

  其他备选（均正常）:

   https://docker.m.daocloud.io

   https://ccr.ccs.tencentyun.com

   https://hub.xdark.top

   https://dhub.kubesre.xyz

   https://docker.kejilion.pro

   https://docker.xuanyuan.me

  测试拉取镜像

   配置完成后，可以使用以下命令测试加速器是否生效‌：

[root@k3s-master ~]# nerdctl pull calico/node:v3.30.4
docker.io/calico/node:v3.30.4:                                                    resolved       |++++++++++++++++++++++++++++++++++++++|
index-sha256:362f10b69142fcc654c0ab65a5f371923f9a1d8f7772eac0ff223b9dc67704de:    done           |++++++++++++++++++++++++++++++++++++++|
manifest-sha256:b6c92e535b935575f48092edadcfaec716ebce53f1fbc56d312744e86ce0fb17: done           |++++++++++++++++++++++++++++++++++++++|
config-sha256:833e8e11d9dc187377eab6f31e275114a6b0f8f0afc3bf578a2a00507e85afc9:   done           |++++++++++++++++++++++++++++++++++++++|
layer-sha256:44c2028a3ff8d71676da71a6c671786584592f991e0eea338c6de86237383ff7:    done           |++++++++++++++++++++++++++++++++++++++|
elapsed: 39.8s                                                                    total:  149.6  (3.8 MiB/s)

6.4 启动Containerd服务

  启动并设置 containerd 和 buildkit 服务为开机自启。

   containerd 是一个高性能的容器运行时，负责管理容器的生命周期，包括镜像拉取、容器创建、运行、停止等，是 Kubernetes 支持的主流运行时之一。

   BuildKit 是 Docker 和 containerd 的构建引擎，用于高效地构建镜像，支持并行构建、缓存优化和安全隔离等高级功能。

# 下列步骤需要在集群中所有机器上完成

# 启动 containerd 和 buildkit 服务
systemctl daemon-reload

# 启动containerd并设置开机自启动
systemctl enable --now containerd
systemctl enable --now buildkit

# 查看containerd状态
systemctl status containerd

6.5 添加nerdctl命令自动补齐

  生成 bash 自动补齐脚本，立即生效，提高命令行操作效率。

# 下列步骤需要在集群中所有机器上完成
nerdctl completion bash > /etc/bash_completion.d/nerdctl
source /etc/bash_completion.d/nerdctl

7 Docker CE 部署

  dockerd实际真实调用的还是containerd的api接口，containerd是dockerd和runC之间的一个中间交流组件。所以启动docker服务的时候，也会启动containerd服务的。

  kubernets自ｖ1.24.0后，就不再使用docker.shim，替换采用containerd作为容器运行时端点。因此需要安装containerd（在docker的基础下安装），上面安装docker的时候就自动安装了containerd了。这里的docker只是作为客户端而已。容器引擎还是containerd。

  可以直接安装container.io，而不用安装docker

7.1 卸载旧版本

  在安装 Docker Engine 之前，需要卸载任何冲突的软件包。

  Linux 发行版可能会提供非官方的 Docker 包，这可能会发生冲突 使用 Docker 提供的官方软件包。必须卸载这些包在安装正式版 Docker Engine 之前。

# dnf可能会报告您没有安装这些软件包。
# 存储在 卸载 Docker 时自动删除。/var/lib/docker/
sudo dnf remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-engine \
                  podman \
                  runc

7.2 使用 rpm 存储库安装

  可以根据需要以不同的方式安装 Docker Engine：

   可以设置 Docker 的存储库并安装，从他们那里方便安装和升级任务。这是推荐的方法。

   可以下载 RPM 包，手动安装，然后管理完全手动升级。适合在无法访问互联网的的系统上安装Docker。

   在测试和开发环境中，可以使用自动化便利脚本来安装 Docker。

1.设置存储库

  在首次在新主机上安装 Docker Engine 之前，需要设置 Docker 存储库。之后可以从存储库安装和更新 Docker 。

# yum install -y yum-utils device-mapper-persistent-data lvm2
# yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

2.安装 Docker 引擎

1.安装 Docker 包
  # yum install -y docker-ce docker-ce-cli containerd.io
  sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
  
2.启动 Docker 引擎
  sudo systemctl enable --now docker

3.关于Docker的完整安装

1.卸载docker旧版本
  yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-selinux docker-engine-selinux docker-engine

2.安装相关工具类
  yum install -y yum-utils device-mapper-persistent-data lvm2

3.配置docker仓库(阿里云)
  yum-config-manager --add-repo http://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

4.安装docker
  yum install docker-ce

5.验证docker安装成功
  #启动docker
   systemctl start docker
   
  # 创建开机自启
   sudo systemctl enable --now docker
  #检查 Docker 服务状态
   sudo systemctl status docker

  #验证docker
   docker run hello-world

7.3 Docker 镜像加速器

  添加Docker 镜像加速器，这里只限在国内部署时才需要加速，在国外这样加速反而缓慢

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
        "https://docker.mirrors.ustc.edu.cn",
        "https://mirror.baidubce.com",
        "https://docker.m.daocloud.io",
        "https://mirror.ccs.tencentyun.com",
        "https://docker.nju.edu.cn",
        "https://docker.mirrors.sjtug.sjtu.edu.cn",
        "https://mirror.gcr.io",
        "https://docker.registry.cyou",
        "https://docker-cf.registry.cyou",
        "https://dockercf.jsdelivr.fyi",
        "https://docker.jsdelivr.fyi",
        "https://dockertest.jsdelivr.fyi",
        "https://mirror.aliyuncs.com",
        "https://dockerproxy.com"
   ],
   "exec-opts": ["native.cgroupdriver=systemd"]
}
EOF

systemctl daemon-reload
systemctl restart docker

8 DNS解析

  这一步需要在集群中所有机器上完成

# 配置racher所在的服务器与外部集群以及harbor进行相互解析
[root@k3s-master ~]# vim /etc/hosts
......
10.8.0.13 k8s-master
10.8.0.14 k8s-node1
10.8.0.16 k8s-node2
10.8.0.17 k3s-master
110.40.154.116 mirrors.harbor.com

9 关于安装的说明

  安装Rancher‌不需要‌先安装Kubernetes（K8S），但推荐在Kubernetes集群上安装以实现更高效的管理。 ‌

  安装方式选择：

   1.独立Docker安装‌：通过Docker运行Rancher容器时，Rancher会自动创建本地K3s或RKE2集群供其管理，无需提前安装K8S。 ‌

   2‌.Kubernetes集群安装‌：在生产环境中，建议将Rancher部署在K8S集群上，可实现更高效的资源管理和高可用性。 ‌

  关键配置说明：

   1.离线安装时需手动准备镜像仓库并配置registries.yaml文件，确保K3s或RKE2节点能访问私有镜像。 ‌

   2.容器化部署需通过Helm Chart仓库安装Rancher，需提前配置Helm环境。 ‌

10 部署K3S

10.1 网络与安全组

  开放端口：确保安全组规则允许 80、443、6443 端口的入站流量。

  内网互通：配置四台云主机处于同一VPC内，使用内网IP进行通信，提升安全性和降低延迟。

10.2 安装K3S

curl -sfL https://get.k3s.io |  INSTALL_K3S_VERSION=<VERSION> sh -s - server \
  --datastore-endpoint="<DATASTORE_ENDPOINT>"
# 其中 <DATASTORE_ENDPOINT> 是数据存储的连接 URI。例如，如果你使用的是 MySQL，则为 mysql://username:password@tcp(hostname:3306)/database-name。有效的数据存储包括 etcd、MySQL、PostgreSQL 或 SQLite（默认）。


# 使用国内镜像源安装
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  INSTALL_K3S_MIRROR=cn \
  sh -s - \
  --write-kubeconfig-mode 644 \
  --docker \
  --system-default-registry "registry.cn-hangzhou.aliyuncs.com"
  
# 验证安装
sudo systemctl status k3s
k3s --version

[root@k3s-master ~]# k3s --version
k3s version v1.33.5+k3s1 (fab4a5c3)
go version go1.24.6

10.3 kubectl配置

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
export KUBECONFIG=~/.kube/config

10.4 K3S配置节点

# 获取主 Server 节点令牌
cat /var/lib/rancher/k3s/server/token

# 在第二个 K3s Server 节点上运行命令
curl -sfL https://get.k3s.io |  INSTALL_K3S_VERSION=<VERSION> sh -s - server \
    --datastore-endpoint="<DATASTORE_ENDPOINT>" \
    --token "<MAIN_SERVER_NODE_TOKEN>"
    
[root@k3s-master ~]# cat /var/lib/rancher/k3s/server/token
K10daaa916ca1dce79da5d58491e9655b6dde1471f3d9a98288ec824283fccb0736::server:47e505667eab929b8f74a688a9e4a9cf

10.5 检查 K3s 是否正常运行

  在其中一个 K3s Server 节点上运行以下命令，来确认 K3s 是否已经设置成功：

# 验证集群状态
sudo k3s kubectl get nodes

[root@k3s-master ~]# kubectl get nodes
NAME         STATUS   ROLES                  AGE     VERSION
k3s-master   Ready    control-plane,master   3m48s   v1.33.5+k3s1

# 测试集群 Pod 的健康状况
sudo k3s kubectl get pods --all-namespaces

[root@k3s-master ~]# k3s kubectl get pods --all-namespaces
NAMESPACE     NAME                                      READY   STATUS      RESTARTS   AGE
kube-system   coredns-c8fbf7479-7cp7k                   1/1     Running     0          15m
kube-system   helm-install-traefik-crd-p5r7c            0/1     Completed   0          15m
kube-system   helm-install-traefik-pldtl                0/1     Completed   2          15m
kube-system   local-path-provisioner-65c47647b6-7j9vw   1/1     Running     0          15m
kube-system   metrics-server-64f5cd9f57-bppx7           1/1     Running     0          15m
kube-system   svclb-traefik-0a9b644f-px6z5              2/2     Running     0          8m11s
kube-system   traefik-856869ccc9-2dvbv                  1/1     Running     0          8m11s

1. 所有核心组件都在运行状态
   · CoreDNS: ✅ 提供集群内部 DNS 解析
   · Traefik: ✅ 提供 Ingress 路由功能
   · Metrics Server: ✅ 收集资源使用指标
   · Local Path Provisioner: ✅ 提供动态存储
2. Job 任务状态正常
   · helm-install-traefik-crd-p5r7c: Completed 状态表示安装任务成功完成
   · helm-install-traefik-pldtl: Completed 状态表示安装任务成功完成（虽然有 2 次重启，但最终成功了）
3. 负载均衡器正常
   · svclb-traefik: 2/2 表示两个容器都正常运行

10.6 解决镜像拉取问题

  1.配置 Docker 镜像加速器

# 创建 Docker 配置目录
sudo mkdir -p /etc/docker

# 配置国内镜像加速器
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://registry.docker-cn.com"
  ],
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  },
  "storage-driver": "overlay2"
}
EOF

# 重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

  2.预拉取关键镜像

# 拉取 K3s 核心镜像
sudo docker pull registry.cn-hangzhou.aliyuncs.com/k3s-helm/traefik:latest
sudo docker pull registry.cn-hangzhou.aliyuncs.com/k3s-helm/coredns:latest
sudo docker pull registry.cn-hangzhou.aliyuncs.com/k3s-helm/local-path-provisioner:latest
sudo docker pull registry.cn-hangzhou.aliyuncs.com/k3s-helm/metrics-server:latest

# 重新标记镜像
sudo docker tag registry.cn-hangzhou.aliyuncs.com/k3s-helm/traefik:latest traefik:latest
sudo docker tag registry.cn-hangzhou.aliyuncs.com/k3s-helm/coredns:latest coredns:latest

10.7 集群状态监控与修复

10.7.1 实时监控安装进度

# 监控所有 Pod 状态
watch -n 5 'kubectl get pods --all-namespaces'

# 或者使用这个脚本持续监控
while true; do
  clear
  echo "=== K3s 集群状态监控 ==="
  echo "节点状态:"
  kubectl get nodes
  echo -e "\n所有 Pod 状态:"
  kubectl get pods --all-namespaces
  echo -e "\n问题 Pod 详情:"
  kubectl get pods --all-namespaces --field-selector=status.phase!=Running | grep -v "Completed"
  echo -e "\n等待 10 秒后刷新..."
  sleep 10
done

10.7.2 常见问题修复脚本

#!/bin/bash
# k3s-fix.sh - K3s 集群修复脚本

echo "开始修复 K3s 集群..."

# 1. 重启 K3s 服务
echo "重启 K3s 服务..."
sudo systemctl restart k3s

# 2. 等待 30 秒让服务稳定
sleep 30

# 3. 检查并重启有问题的 Pod
echo "检查有问题的 Pod..."
kubectl get pods --all-namespaces --field-selector=status.phase!=Running | \
grep -v "Completed" | \
grep -v "NAME" | \
while read namespace pod rest; do
  if [[ -n "$pod" ]]; then
    echo "重启 Pod: $namespace/$pod"
    kubectl delete pod -n $namespace $pod
  fi
done

# 4. 再次检查状态
echo "修复完成，当前状态:"
kubectl get nodes
kubectl get pods --all-namespaces | grep -v Running | grep -v Completed

10.8 验证集群健康状态

10.8.1 基础健康检查

# 运行完整健康检查脚本
#!/bin/bash
echo "=== K3s 集群健康检查 ==="

echo "1. 节点状态:"
kubectl get nodes -o wide

echo -e "\n2. 核心系统 Pod 状态:"
kubectl get pods -n kube-system -o wide

echo -e "\n3. 所有命名空间 Pod 汇总:"
kubectl get pods --all-namespaces -o wide | grep -v Running | grep -v Completed

echo -e "\n4. 系统服务状态:"
sudo systemctl status k3s --no-pager -l

echo -e "\n5. 网络连通性测试:"
kubectl get svc -n kube-system

echo -e "\n6. DNS 解析测试:"
kubectl run test-dns --image=busybox --rm -it --restart=Never -- nslookup kubernetes.default.svc.cluster.local

echo -e "\n=== 检查完成 ==="

10.8.2 等待所有 Pod Running 的自动脚本

#!/bin/bash
# wait-for-running.sh - 等待所有 Pod 达到 Running 状态

MAX_WAIT=600  # 最大等待时间（秒）
INTERVAL=10   # 检查间隔（秒）
elapsed=0

echo "等待所有 Pod 达到 Running 状态..."

while [ $elapsed -lt $MAX_WAIT ]; do
  # 获取非 Running 状态的 Pod 数量（排除已完成的 Job）
  non_running=$(kubectl get pods --all-namespaces --field-selector=status.phase!=Running --no-headers | grep -v "Completed" | wc -l)
  
  if [ $non_running -eq 0 ]; then
    echo "✅ 所有 Pod 都已达到 Running 状态！"
    kubectl get pods --all-namespaces
    exit 0
  fi
  
  echo "等待中... ($elapsed/$MAX_WAIT 秒) - 还有 $non_running 个 Pod 非 Running 状态"
  sleep $INTERVAL
  elapsed=$((elapsed + INTERVAL))
done

echo "❌ 超时：在 $MAX_WAIT 秒内仍有 Pod 未达到 Running 状态"
kubectl get pods --all-namespaces --field-selector=status.phase!=Running
exit 1

10.9 最终验证

10.9.1 运行完整验证套件

# 使脚本可执行
chmod +x k3s-fix.sh wait-for-running.sh

# 运行等待脚本（最多等待10分钟）
./wait-for-running.sh

# 如果还有问题，运行修复脚本
./k3s-fix.sh

# 再次验证
./wait-for-running.sh

10.9.2 预期成功状态

  当所有步骤完成后，应该看到：

$ kubectl get nodes
NAME    STATUS   ROLES                  AGE   VERSION
ubuntu  Ready    control-plane,master   5m    v1.29.5+k3s1

$ kubectl get pods --all-namespaces
NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
kube-system   local-path-provisioner-5cff76f6fd-xxxxx   1/1     Running   0          5m
kube-system   coredns-76f75df574-xxxxx                  1/1     Running   0          5m
kube-system   metrics-server-5f9f764df5-xxxxx           1/1     Running   0          5m
kube-system   traefik-65bccdc4bd-xxxxx                  1/1     Running   0          5m

10.10 故障排除备忘录

  如果遇到特定问题：

   1.镜像拉取失败：检查 Docker 镜像加速器配置，手动预拉取镜像

   2.Pod 一直 Pending：检查节点资源，确保没有污点阻止调度

   3.Pod CrashLoopBackOff：查看 Pod 日志 kubectl logs -n

   4.网络问题：重启 K3s 服务 sudo systemctl restart k3s

11 准备Helm环境

  Helm 在安装 Rancher 时充当自动化部署工具的角色，将 Rancher 的所有 Kubernetes 资源（包括 Deployment、Service、Ingress、配置等）打包为一个可复用的 Chart，使用户能够通过一条命令快速部署、配置和管理 Rancher，同时支持版本控制、参数定制和后续升级，极大简化了企业级容器平台的部署流程。

  下载helm工具，最新版可从此页面下载。

[root@k3s-master ~]# wget https://get.helm.sh/helm-v3.19.0-linux-amd64.tar.gz
--2025-11-18 11:20:52--  https://get.helm.sh/helm-v3.19.0-linux-amd64.tar.gz
Resolving get.helm.sh (get.helm.sh)... 13.107.213.50, 13.107.246.50, 2620:1ec:bdf::50, ...
Connecting to get.helm.sh (get.helm.sh)|13.107.213.50|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 18019607 (17M) [application/x-tar]
Saving to: ‘helm-v3.19.0-linux-amd64.tar.gz’

helm-v3.19.0-linux-amd64.tar.gz               100%[================================================================================================>]  17.18M  12.3MB/s    in 1.4s

2025-11-18 11:20:54 (12.3 MB/s) - ‘helm-v3.19.0-linux-amd64.tar.gz’ saved [18019607/18019607]

  将helm工具安装到用户的$PATH路径中

[root@k3s-master ~]# tar xf helm-v3.19.0-linux-amd64.tar.gz
[root@k3s-master ~]# ls
helm-v3.19.0-linux-amd64.tar.gz  linux-amd64  nerdctl-full-2.1.6-linux-amd64.tar.gz
[root@k3s-master ~]# mv linux-amd64/helm /usr/bin/helm
[root@k3s-master ~]# helm version
version.BuildInfo{Version:"v3.19.0", GitCommit:"3d8990f0836691f0229297773f3524598f46bda6", GitTreeState:"clean", GoVersion:"go1.24.7"}

  添加helm命令补齐功能

  执行以下命令后，可以退出ssh，并重新登录或者执行sudo -i，即可使用helm的tab补齐功能

helm completion bash > /etc/bash_completion.d/helm

[root@k3s-master ~]# helm completion bash > /etc/bash_completion.d/helm

12 安装cert-manager

  Rancher 默认需要 TLS 证书来保护访问安全。可选择三种方式终止 TLS：

   Rancher 自签证书：需安装 cert-manager，自动生成和管理证书

   Let’s Encrypt 公共证书：也需 cert-manager，通过 HTTP 验证自动申请

   已有证书：手动上传 tls.crt 和 tls.key，无需 cert-manager

  通过 Helm 设置 ingress.tls.source 参数即可指定证书来源，这里选择自签名证书的方式，所以先完成cert-manager的安装。

Kubernetes版本与cert-manager版本的对应关系：

Kubernetes版本	cert-manager版本	备注
1.29+	v1.13.x	推荐
1.27 - 1.28	v1.12.x	兼容
1.25 - 1.26	v1.11.x	兼容

12.1 添加 Jetstack Helm 仓库

# 添加Jetstack Helm仓库
helm repo add jetstack https://charts.jetstack.io
helm repo update

[root@k3s-master ~]# helm repo add jetstack https://charts.jetstack.io
"jetstack" has been added to your repositories

# 查看仓库是否添加完毕
[root@k3s-master ~]# helm repo list
NAME            URL
jetstack        https://charts.jetstack.io

# 更新本地 Helm Chart 仓库缓存
[root@k3s-master ~]# helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "jetstack" chart repository
Update Complete. ⎈Happy Helming!⎈

12.2 安装CRDs

  安装cert-manager的Custom Resource Definitions (CRDs)

# kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<VERSION>/cert-manager.crds.yaml

kubectl apply -f https://hub.gitmirror.com/https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.crds.yaml

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.crds.yaml

# 如果这步安装了crds，则在下面安装cert-manager时设置--set installCRDs=false
[root@k3s-master ~]# kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.1/cert-manager.crds.yaml
customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/clusterissuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/issuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/orders.acme.cert-manager.io created

12.3 创建命名空间

kubectl create namespace cert-manager

[root@k3s-master ~]# kubectl create namespace cert-manager
namespace/cert-manager created

12.4 cert-manager可用版本

# 查看cert-manager可用的版本

[root@k3s-master ~]# helm search repo jetstack/cert-manager
NAME                                    CHART VERSION   APP VERSION     DESCRIPTION
jetstack/cert-manager                   v1.19.1         v1.19.1         A Helm chart for cert-manager
jetstack/cert-manager-approver-policy   v0.22.2         v0.22.2         approver-policy is a CertificateRequest approve...
jetstack/cert-manager-csi-driver        v0.11.1         v0.11.1         cert-manager csi-driver enables issuing secretl...
jetstack/cert-manager-csi-driver-spiffe v0.10.1         v0.10.1         csi-driver-spiffe is a Kubernetes CSI plugin wh...
jetstack/cert-manager-google-cas-issuer v0.10.1         v0.10.1         A Helm chart for jetstack/google-cas-issuer
jetstack/cert-manager-istio-csr         v0.14.3         v0.14.3         istio-csr enables the use of cert-manager for i...
jetstack/cert-manager-trust             v0.2.1          v0.2.0          DEPRECATED: The old name for trust-manager. Use...

12.5 安装cert-manager

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version <VERSION>
```
注意：请将 <VERSION> 替换为与你的Kubernetes版本兼容的cert-manager版本，例如 v1.13.3。


helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.19.1 \
  --set installCRDs=true
  
  
[root@k3s-master ~]# helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.19.1 \
  --set installCRDs=true
NAME: cert-manager
LAST DEPLOYED: Tue Nov 18 13:12:44 2025
NAMESPACE: cert-manager
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
⚠️  WARNING: `installCRDs` is deprecated, use `crds.enabled` instead.
⚠️  WARNING: New default private key rotation policy for Certificate resources.
The default private key rotation policy for Certificate resources was
changed to `Always` in cert-manager >= v1.18.0.
Learn more in the [1.18 release notes](https://cert-manager.io/docs/releases/release-notes/release-notes-1.18).

cert-manager v1.19.1 has been deployed successfully!

In order to begin issuing certificates, you will need to set up a ClusterIssuer
or Issuer resource (for example, by creating a 'letsencrypt-staging' issuer).

More information on the different types of issuers and how to configure them
can be found in our documentation:

https://cert-manager.io/docs/configuration/

For information on how to configure cert-manager to automatically provision
Certificates for Ingress resources, take a look at the `ingress-shim`
documentation:

https://cert-manager.io/docs/usage/ingress/


[root@k3s-master ~]# kubectl get crd | grep cert-manager
certificaterequests.cert-manager.io         2025-11-18T05:12:45Z
certificates.cert-manager.io                2025-11-18T05:12:45Z
challenges.acme.cert-manager.io             2025-11-18T05:12:45Z
clusterissuers.cert-manager.io              2025-11-18T05:12:45Z
issuers.cert-manager.io                     2025-11-18T05:12:45Z
orders.acme.cert-manager.io                 2025-11-18T05:12:45Z

[root@k3s-master ~]# kubectl get pod -A
NAMESPACE      NAME                                       READY   STATUS      RESTARTS   AGE
cert-manager   cert-manager-77b74755d9-9bvhj              1/1     Running     0          3m45s
cert-manager   cert-manager-cainjector-65fcfd6ccf-77nmm   1/1     Running     0          3m45s
cert-manager   cert-manager-webhook-9b4dd78-rzjzj         1/1     Running     0          3m45s
kube-system    coredns-c8fbf7479-7cp7k                    1/1     Running     0          146m
kube-system    helm-install-traefik-crd-p5r7c             0/1     Completed   0          146m
kube-system    helm-install-traefik-pldtl                 0/1     Completed   2          146m
kube-system    local-path-provisioner-65c47647b6-7j9vw    1/1     Running     0          146m
kube-system    metrics-server-64f5cd9f57-bppx7            1/1     Running     0          146m
kube-system    svclb-traefik-0a9b644f-px6z5               2/2     Running     0          139m
kube-system    traefik-856869ccc9-2dvbv                   1/1     Running     0          139m

12.6 安装cert-manager超时

  方案1：配置国内镜像源 最推荐，一劳永逸

  方案2：手动预拉取镜像 快速解决当前问题

  方案3：使用替代镜像仓库 企业环境常用

  方案4：直接使用YAML安装 绕过Helm问题

12.6.1 配置国内镜像源

  1.配置 Docker 镜像加速器

# 编辑 Docker 配置
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://registry.docker-cn.com",
    "https://docker.nju.edu.cn"
  ]
}
EOF

# 重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

  2.使用国内镜像安装 cert-manager

# 先手动拉取镜像到国内仓库，然后使用替代镜像安装
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.19.1 \
  --set installCRDs=true \
  --set image.repository=registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-controller \
  --set webhook.image.repository=registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-webhook \
  --set cainjector.image.repository=registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-cainjector

12.6.2 手动预拉取镜像

  1.手动拉取所有必需镜像

# 拉取 cert-manager 核心镜像
sudo docker pull quay.io/jetstack/cert-manager-controller:v1.19.1
sudo docker pull quay.io/jetstack/cert-manager-webhook:v1.19.1
sudo docker pull quay.io/jetstack/cert-manager-cainjector:v1.19.1

# 拉取依赖的基础镜像
sudo docker pull quay.io/jetstack/cert-manager-ctl:v1.19.1
sudo docker pull registry.k8s.io/ingress-nginx/kube-webhook-certgen:v20231011-8b53cabe2

  2.验证镜像拉取成功

# 检查镜像是否拉取成功
sudo docker images | grep jetstack

[root@k3s-master ~]# sudo docker images | grep jetstack
WARNING: This output is designed for human readability. For machine-readable output, please use --format.
quay.io/jetstack/cert-manager-cainjector:v1.19.1                              c7898aece8fb       53.8MB         12.5MB
quay.io/jetstack/cert-manager-controller:v1.19.1                              cd49e769e18a        109MB         23.5MB
quay.io/jetstack/cert-manager-startupapicheck:v1.19.1                         96a82fa28b14       49.6MB         11.8MB
quay.io/jetstack/cert-manager-webhook:v1.19.1                                 f5bfe77541e3       91.3MB         19.9MB

  3.安装 cert-manager

# 现在安装应该不会超时了
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.19.1 \
  --set installCRDs=true

13.6.3 使用替代镜像仓库

  如果手动拉取仍然超时，使用阿里云等国内仓库：

# 从阿里云拉取镜像
sudo docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-controller:v1.19.1
sudo docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-webhook:v1.19.1
sudo docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-cainjector:v1.19.1

# 重新标记镜像
sudo docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-controller:v1.19.1 quay.io/jetstack/cert-manager-controller:v1.19.1
sudo docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-webhook:v1.19.1 quay.io/jetstack/cert-manager-webhook:v1.19.1
sudo docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-cainjector:v1.19.1 quay.io/jetstack/cert-manager-cainjector:v1.19.1

12.6.4 直接使用 YAML 安装

  如果 Helm 持续有问题，直接使用 YAML：

# 1. 安装 CRD
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.1/cert-manager.crds.yaml

# 2. 创建命名空间
kubectl create namespace cert-manager

# 3. 下载并修改 YAML 文件，使用国内镜像
wget https://github.com/cert-manager/cert-manager/releases/download/v1.19.1/cert-manager.yaml

# 4. 替换镜像源（将 quay.io 替换为国内镜像）
sed -i 's|quay.io/jetstack|registry.cn-hangzhou.aliyuncs.com/google_containers|g' cert-manager.yaml

# 5. 安装
kubectl apply -f cert-manager.yaml

12.6.5 一键解决方案

  创建这个完整的解决脚本：

#!/bin/bash
# fix-cert-manager-install.sh

set -e

echo "=== 解决 cert-manager 镜像拉取问题 ==="

# 1. 配置 Docker 镜像加速器
echo "步骤 1: 配置 Docker 镜像加速器..."
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://registry.docker-cn.com"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
sleep 5

# 2. 清理旧安装
echo "步骤 2: 清理旧安装..."
helm uninstall cert-manager -n cert-manager 2>/dev/null || true
kubectl delete namespace cert-manager 2>/dev/null || true
sleep 10

# 3. 手动预拉取镜像（使用后台任务和重试机制）
echo "步骤 3: 预拉取 cert-manager 镜像..."
(
sudo docker pull quay.io/jetstack/cert-manager-controller:v1.19.1 || \
sudo docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-controller:v1.19.1
) &
(
sudo docker pull quay.io/jetstack/cert-manager-webhook:v1.19.1 || \
sudo docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-webhook:v1.19.1
) &
(
sudo docker pull quay.io/jetstack/cert-manager-cainjector:v1.19.1 || \
sudo docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-cainjector:v1.19.1
) &

# 等待所有拉取任务完成
wait

# 4. 重新标记镜像（如果使用了国内源）
echo "步骤 4: 验证和标记镜像..."
if sudo docker images | grep -q "registry.cn-hangzhou.aliyuncs.com"; then
    sudo docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-controller:v1.19.1 quay.io/jetstack/cert-manager-controller:v1.19.1
    sudo docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-webhook:v1.19.1 quay.io/jetstack/cert-manager-webhook:v1.19.1
    sudo docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/cert-manager-cainjector:v1.19.1 quay.io/jetstack/cert-manager-cainjector:v1.19.1
fi

# 5. 安装 cert-manager
echo "步骤 5: 安装 cert-manager..."
kubectl create namespace cert-manager
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.19.1 \
  --set installCRDs=true

# 6. 监控安装进度
echo "步骤 6: 监控安装进度..."
echo "等待 30 秒让 Pod 启动..."
sleep 30

for i in {1..20}; do
    echo "检查状态... ($i/20)"
    kubectl get pods -n cert-manager
    running_count=$(kubectl get pods -n cert-manager --no-headers 2>/dev/null | grep Running | wc -l)
    if [ $running_count -eq 3 ]; then
        echo "✅ 所有 Pod 运行正常!"
        break
    fi
    sleep 10
done

echo "=== cert-manager 安装完成 ==="

  运行脚本：

chmod +x fix-cert-manager-install.sh
./fix-cert-manager-install.sh

  验证安装成功

# 检查所有 Pod 状态
kubectl get pods -n cert-manager

# 应该看到：
# NAME                                       READY   STATUS    RESTARTS   AGE
# cert-manager-xxxxx                        1/1     Running   0          2m
# cert-manager-cainjector-xxxxx             1/1     Running   0          2m  
# cert-manager-webhook-xxxxx                1/1     Running   0          2m

12.6.6 总结

  如果上述方法都失败，使用离线安装：

# 在有网络的环境下载所有资源，然后拷贝到目标机器
# 1. 下载所有镜像保存为 tar 包
# 2. 下载 cert-manager.yaml
# 3. 在目标机器加载镜像并安装

13 Ingress Controller

  虽然K3s默认集成了Traefik作为Ingress Controller，但在企业环境中，Nginx Ingress Controller因其强大的功能和高度的可定制性而被广泛使用。

13.1 安装Nginx Ingress Controller

  使用Helm安装Nginx Ingress Controller，并通过NodePort方式暴露服务。

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

[root@k3s-master ~]# helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
"ingress-nginx" has been added to your repositories

[root@k3s-master ~]# helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "rancher-stable" chart repository
...Successfully got an update from the "ingress-nginx" chart repository
...Successfully got an update from the "jetstack" chart repository
Update Complete. ⎈Happy Helming!⎈

[root@k3s-master ~]# helm repo list
NAME            URL
jetstack        https://charts.jetstack.io
rancher-stable  https://releases.rancher.com/server-charts/stable
ingress-nginx   https://kubernetes.github.io/ingress-nginx


  
# 通过诺脚本直接安装并解决镜像问题
#!/bin/bash

echo "=== 使用 hostNetwork 模式安装 nginx-ingress ==="

# 卸载现有安装（如果存在）
echo "1. 清理现有安装..."
helm uninstall ingress-nginx -n ingress-nginx 2>/dev/null || true
kubectl delete namespace ingress-nginx --force --grace-period=0 2>/dev/null || true
sleep 10

# 使用 hostNetwork + ClusterIP 安装
echo "2. 安装 nginx-ingress (hostNetwork + ClusterIP)..."
helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.type=ClusterIP \
  --set controller.hostNetwork=true \
  --set controller.ingressClass=nginx \
  --set controller.image.registry=mirrors.harbor.com:446 \
  --set controller.image.image=ingress_nginx/controller \
  --set controller.image.tag=v1.13.3 \
  --set controller.hostPort.ports.http=8090 \
  --set controller.hostPort.ports.https=8445 \
  --set controller.image.digest="" \
  --set controller.admissionWebhooks.patch.image.registry=mirrors.harbor.com:446 \
  --set controller.admissionWebhooks.patch.image.image=ingress_nginx/ingress-nginx/kube-webhook-certgen \
  --set controller.admissionWebhooks.patch.image.tag=v1.6.3 \
  --set controller.admissionWebhooks.patch.image.digest="" \
  --set controller.admissionWebhooks.enabled=false \
  --set defaultBackend.enabled=true \
  --set controller.resources.requests.cpu=10m \
  --set controller.resources.requests.memory=32Mi \
  --set defaultBackend.resources.requests.cpu=10m \
  --set defaultBackend.resources.requests.memory=32Mi
  --wait \
  --timeout 15m \
  --atomic 
  
# 等待启动
echo "3. 等待启动完成..."
sleep 30

# 验证安装
echo "4. 验证安装..."
kubectl get pods -n ingress-nginx -o wide
echo "端口监听状态:"
netstat -tlnp | grep -E ':(80|443)'

# 测试访问
echo "5. 测试访问..."
curl -H "Host: rancher.k3s.cn" http://localhost 2>/dev/null && echo "HTTP 访问成功" || echo "HTTP 访问失败"
curl -k -H "Host: rancher.k3s.cn" https://localhost 2>/dev/null && echo "HTTPS 访问成功" || echo "HTTPS 访问失败"

echo "=== 安装完成 ==="  

13.2 配置Rancher使用Nginx Ingress

  确保Rancher的Ingress资源使用nginx作为Ingress Class。在安装Rancher时，可以通过添加注解来指定：

# 如果已经安装了Rancher，可以通过upgrade命令添加注解
helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --set hostname=rancher.k3s.cn \
  --set ingress.extraAnnotations.'kubernetes\.io/ingress\.class'=nginx
  
  
  kubectl patch ingressclass nginx \
  --type='merge' \
  -p '{"metadata":{"annotations":{"ingressclass.kubernetes.io/is-default-class":"true"}}}'
   
# 也可以直接编辑Rancher的Ingress资源：
kubectl annotate ingress rancher -n cattle-system kubernetes.io/ingress.class=nginx

14 安装 Rancher

  Rancher 是通过 Kubernetes 的 Helm 包管理器进行安装的。Helm Chart 为原始的 YAML 清单提供了模板化能力，使用户能够根据参数动态生成资源配置，从而实现灵活、可定制的部署方式，而不再依赖于固定的静态文件。

  使用 Helm 安装 Rancher 相比手工编写 YAML 文件的方式，具有显著优势：它通过模板化和参数化机制简化了部署流程，避免了繁琐的资源定义和版本兼容问题；同时支持一键安装、升级、回滚和卸载，便于统一管理和持续维护，大幅提升了部署效率与可控性，尤其适合企业级环境中的标准化运维。

14.1 添加 Helm Chart 仓库

  在安装 Rancher 前，需通过 helm repo add 命令添加官方 Helm Chart 仓库。根据使用场景选择合适的版本源：

  Latest：用于体验最新功能

helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

  Stable：推荐用于生产环境

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update

[root@k3s-master ~]# helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
"rancher-stable" has been added to your repositories

# 删除仓库命令
helm repo remove [仓库名称]

  Alpha：实验性预览版本，适合探索即将发布的功能

helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha

⚠️ 注意：Alpha 版本不支持升级或版本间切换，仅适用于临时测试。

  选择仓库时应根据稳定性需求和功能预期权衡，确保部署策略与环境匹配，本次安装选择stable

  看看仓库是否添加完毕

[root@k3s-master ~]# helm repo update
[root@k3s-master ~]# helm repo list

14.2 创建命名空间

  在安装 Rancher 之前，必须先创建一个专用的 Kubernetes 命名空间，用于隔离和管理 Rancher 所部署的资源。

  推荐使用命名空间名称 cattle-system，执行以下命令即可创建：

kubectl create namespace cattle-system

[root@k3s-master ~]# kubectl create namespace cattle-system
namespace/cattle-system created

这样可以确保 Helm 安装的所有组件都集中在该命名空间中，便于后续的运维与权限控制。

14.3 安装 Rancher

  采用的是自签名证书方式，因此 Rancher 会默认生成 CA，并通过 cert-manager 自动签发用于访问 Rancher Server 的 TLS 证书。由于 ingress.tls.source=rancher 是 Helm Chart 的默认配置项，安装时无需显式指定该参数。这样可以简化部署流程，同时确保接口通信具备基础的加密保护。

  在使用 Helm 安装 Rancher 时，请确保设置以下关键参数：

   hostname：指定解析到负载均衡器的 DNS 名称或使用分配给ingress的域名，用于外部访问 Rancher UI，打算用rancher.k8s.cn作为访问域名，不过这需要做hosts解析，因为这域名并不属于我。设置访问Rancher的地址，生产环境强烈建议使用真实域名并配置DNS解析到此云主机的公网IP。如果暂时没有域名，在测试时可以考虑使用主机的公网IP，但需要注意证书警告。

   replicas：设置为1。如果未来需要高可用，可以扩展为3。

   ingress.tls.source：设置为rancher，表示使用Rancher默认的自签名证书（由cert-manager管理）。首次访问时浏览器会警告，需手动接受。生产环境建议使用secret方式配置可信证书。

   bootstrapPassword：为 admin 用户设置初始登录密码，确保安全性，在下面的例子中用的是rancher

   --version：如需安装特定版本的 Rancher，可通过该标志指定版本号，例如 --version 2.12.3

  这些参数可通过 --set 传入 Helm 命令，实现定制化部署。

# 删除当前的 Rancher 安装
kubectl delete namespace cattle-system --grace-period=0 --force
kubectl delete namespace cattle-system

# 更新 Helm 仓库
[root@k3s-master ~]# helm repo update rancher-stable
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "rancher-stable" chart repository
Update Complete. ⎈Happy Helming!⎈

# 查看可用的 Rancher 版本
[root@k3s-master ~]# helm search repo rancher-stable/rancher -l


helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --set hostname=rancher.k3s.cn \
  --set ingress.ingressClassName=nginx \
  --set global.cattle.psp.enabled=false \
  --set replicas=1 \
  --set ingress.tls.source=rancher \
  --set telemetry.enabled=false \
  --set auditLog.level=0 \
  --set auditLog.enabled=false \
  --set resources.limits.cpu=800m \
  --set resources.limits.memory=1200Mi \
  --set resources.requests.cpu=300m \
  --set resources.requests.memory=400Mi \
  --set telemetry.enabled=false \
  --set bootstrapPassword=rancher@779543
  
......
NAME: rancher
LAST DEPLOYED: Tue Nov 18 20:42:15 2025
NAMESPACE: cattle-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Rancher Server has been installed. Rancher may take several minutes to fully initialize.

Please standby while Certificates are being issued, Containers are started and the Ingress rule comes up.

Check out our docs at https://rancher.com/docs/

## First Time Login

If you provided your own bootstrap password during installation, browse to https://rancher.k3s.cn to get started.
If this is the first time you installed Rancher, get started by running this command and clicking the URL it generates:

```
echo https://rancher.k3s.cn/dashboard/?setup=$(kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}')
```

To get just the bootstrap password on its own, run:

```
kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}{{ "\n" }}'
```


Happy Containering!

# 以上信息告诉我们，如果需要，可以用secret的方法找到我们的密码。

14.4 脚本安装Rancher

#!/bin/bash
# install-rancher.sh

set -e

echo "=== 开始安装 Rancher ==="

# 检查前置条件
echo "步骤 1: 检查前置条件..."
kubectl get nodes
kubectl get pods -n cert-manager

# 创建命名空间
echo "步骤 2: 创建命名空间..."
kubectl create namespace cattle-system --dry-run=client -o yaml | kubectl apply -f -

# 安装 Rancher
echo "步骤 3: 安装 Rancher..."
helm upgrade --install rancher rancher-stable/rancher \
 --namespace cattle-system \
  --set hostname=rancher.k3s.cn \
  --set replicas=1 \
  --set ingress.tls.source=rancher \
  --set ingress.ingressClassName=nginx \
  --set global.cattle.psp.enabled=false \
  --set bootstrapPassword=rancher@779543
  --wait

# 等待部署完成
echo "步骤 4: 等待 Rancher 启动..."
kubectl rollout status deployment/rancher -n cattle-system --timeout=600s

echo "=== Rancher 安装完成 ==="
echo "访问地址: https://rancher.k3s.com"
echo "用户名: admin"
echo "密码: rancher@779543"

# 运行脚本
chmod +x install-rancher.sh
./install-rancher.sh

14.5 Rancher Server 状态

# 需要pod全部处于running状态
[root@k3s-master ~]# kubectl get pod -A

  一切正常后，试试访问rancher看看，在访问前，需要看看是否创建了ingress供我们访问

[root@k3s-master ~]# kubectl get ingress -n cattle-system
NAME      CLASS   HOSTS            ADDRESS       PORTS     AGE
rancher   nginx   rancher.k3s.cn   10.43.40.89   80, 443   54m


[root@k3s-master ~]# kubectl get pods -n cattle-system -w
NAME                                        READY   STATUS      RESTARTS   AGE
helm-operation-9fkxg                        0/2     Completed   0          52m
helm-operation-cqgfk                        0/2     Completed   0          52m
helm-operation-vp9r4                        0/2     Completed   0          52m
rancher-786f59fdcb-pmb92                    1/1     Running     0          55m
rancher-webhook-bbb9cf866-ggkvg             1/1     Running     0          52m
system-upgrade-controller-c84595cc6-gh2sn   1/1     Running     0          52m

14.6 修改为NodePort

# 查看 nginx-ingress 服务的 NodePort 端口
kubectl get svc -n ingress-nginx ingress-nginx-controller

[root@k3s-master ~]# kubectl get svc -n ingress-nginx ingress-nginx-controller
NAME                       TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)          AGE
ingress-nginx-controller   ClusterIP   10.43.40.89   <none>        80/TCP,443/TCP   30m

# 1. 改为 NodePort 并获取端口
kubectl patch svc ingress-nginx-controller -n ingress-nginx -p '{"spec": {"type": "NodePort"}}'


[root@k3s-master ~]# kubectl get svc -n ingress-nginx ingress-nginx-controller
NAME                       TYPE       CLUSTER-IP    EXTERNAL-IP   PORT(S)                      AGE
ingress-nginx-controller   NodePort   10.43.40.89   <none>        80:32645/TCP,443:32356/TCP   37m


# 创建临时的 NodePort service 直接访问 Rancher
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Service
metadata:
  name: rancher-direct
  namespace: cattle-system
spec:
  type: NodePort
  selector:
    app: rancher
  ports:
  - name: http
    port: 80
    targetPort: 80
    nodePort: 30080
  - name: https
    port: 443
    targetPort: 443
    nodePort: 30443
EOF

echo "直接访问地址: http://124.222.84.111:30080"、"https://124.222.84.111:30443"

15 配置浏览器访问

15.1 配置腾讯云安全组

  1.登录腾讯云控制台 → 轻量应用服务器

   防火墙规则 → 添加规则：

   · 协议：TCP

   · 端口：80, 443, 32645, 32356

   · 来源：0.0.0.0/0（或你的 IP 段）

  2.云服务器网络结构说明

   公网用户 → 腾讯云公网IP 124.222.84.111 → SNAT转换 → 服务器内网IP 10.0.0.5

15.2 配置 Windows 访问

  1.用管理员权限编辑 C:\Windows\System32\drivers\etc\hosts

124.222.84.111 rancher.k3s.cn

  2.Windows测试连通性

# 测试域名解析
nslookup rancher.k3s.cn

# 测试端口连通性
Test-NetConnection -ComputerName rancher.k3s.cn -Port 32645
Test-NetConnection -ComputerName rancher.k3s.cn -Port 32356

15.3 预期结果

  完成配置后，你应该能在浏览器中看到：

你好！

欢迎使用 Rancher
这是你第一次访问 Rancher。如果你预先设置了 Bootstrap 密码，请在此处输入。否则我们会为你生成一个随机密码。找到它：

"docker run" 安装：
运行docker ps找到你的容器 ID，然后运行：
docker logs container-id 2>&1 | grep "Bootstrap Password:"

Helm 安装，运行：

kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{.data.bootstrapPassword|base64decode}}{{"\n"}}'



 
欢迎使用 Rancher！
此 Rancher 安装应使用什么 URL？集群中的所有节点都需要能访问该 URL。

服务器 URL *
https://124.222.84.111:30443
用户名/密码:admin/rancher@779543

  1.首次访问: Rancher 设置页面

  2.需要接受自签名证书的安全警告（点击”继续访问”）

  3.输入 bootstrap 密码完成初始化