本节介绍如何离线安装 Kubernetes 和 KubeSphere 企业版。部署环境无需访问外网,可完全离线安装 KubeSphere 企业版和扩展组件。

安装过程中将用到开源工具 KubeKey。有关 KubeKey 的更多信息,请访问 GitHub KubeKey 仓库

前提条件

  • 您需要联系 KubeSphere 企业版的交付服务专家获取 KubeSphere 企业版 v4.1.3 安装包。

  • 您需要准备至少 1 台 Linux 服务器作为集群节点。在生产环境中,为确保集群具备高可用性,建议准备至少 5 台 Linux 服务器,其中 3 台作为控制平面节点,另外 2 台作为工作节点。如果您在多台 Linux 服务器上安装 KubeSphere 企业版,请确保所有服务器属于同一子网。

  • 集群节点的操作系统和版本须为 Ubuntu 16.04、Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04、Debian 9、Debian 10、CentOS 7、CentOS Stream、RHEL 7、RHEL 8、SLES 15 或 openSUSE Leap 15。多台服务器的操作系统可以不同。关于其它操作系统和版本支持,请咨询青云科技官方解决方案专家或交付服务专家。

  • 在生产环境中,为确保集群具有足够的计算和存储资源,建议每台集群节点配置至少 8 个 CPU 核心、16 GB 内存和 200 GB 磁盘空间。除此之外,建议在每台集群节点的 /var/lib/docker(对于 Docker)或 /var/lib/containerd(对于 containerd) 目录额外挂载至少 200 GB 磁盘空间用于存储容器运行时数据。

  • 除集群节点外,您还需要准备一台 Linux 服务器用于创建私有镜像服务,该服务器必须与 KubeSphere 企业版集群节点网络连通,并且在 /mnt/registry 目录挂载至少 100 GB 磁盘空间。

  • 在生产环境中,建议提前为 KubeSphere 企业版集群配置高可用性以避免单个控制平面节点出现故障时集群服务中断。有关更多信息,请参阅配置高可用性

    说明

    如果您规划了多个控制平面节点,请务必提前为集群配置高可用性。

  • 默认情况下,KubeSphere 企业版使用集群节点的本地磁盘空间作为持久化存储。在生产环境中,建议提前配置外部存储系统作为持久化存储。有关更多信息,请参阅配置外部持久化存储

  • 如果集群节点未安装容器运行时,安装工具 KubeKey 将在安装过程中自动为每个集群节点安装 Docker 作为容器运行时。您也可以提前手动安装 containerd、CRI-O 或 iSula 作为容器运行时。

    说明

    CRI-O 和 iSula 与 KubeSphere 企业版的兼容性尚未经过充分测试,可能存在未知问题。

  • 请确保所有集群节点上 /etc/resolv.conf 文件中配置的 DNS 服务器地址可用。否则,KubeSphere 企业版集群可能会出现域名解析问题。

  • 请确保在所有集群节点上都可以使用 sudocurlopenssl 命令。

  • 请确保所有集群节点时间同步。

配置防火墙规则

KubeSphere 企业版需要特定端口和协议用于服务之间的通信。如果您的基础设施环境已启用防火墙,您需要在防火墙设置中放行所需的端口和协议。如果您的基础设施环境未启用防火墙,您可以跳过此步骤。

下表列出需要在防火墙中放行的端口和协议。

服务 协议 起始端口 结束端口 备注

ssh

TCP

22

etcd

TCP

2379

2380

apiserver

TCP

6443

calico

TCP

9099

9100

bgp

TCP

179

nodeport

TCP

30000

32767

master

TCP

10250

10258

dns

TCP

53

dns

UDP

53

metrics-server

TCP

8443

local-registry

TCP

5000

离线环境需要

local-apt

TCP

5080

离线环境需要

rpcbind

TCP

111

使用 NFS 作为持久化存储时需要

ipip

IPENCAP/IPIP

使用 Calico 时需要

安装依赖项

您需要为所有集群节点安装 socat、conntrack、ebtables 和 ipset。如果上述依赖项在各集群节点上已存在,您可以跳过此步骤。

在 Ubuntu 操作系统上,执行以下命令为服务器安装依赖项:

sudo apt install socat conntrack ebtables ipset -y

如果集群节点使用其他操作系统,请将 apt 替换为操作系统对应的软件包管理工具。

校验安装包完整性

获取 KubeSphere 企业版安装包后,可采用校验文件哈希值的方法验证安装包的完整性,以确保其没有被损坏。

  1. 根据安装包文件所在的操作系统,执行对应的命令,查看安装包的 SHA256 值。

    • Windows 系统

      certutil -hashfile [file location] SHA256

      示例:

      certutil -hashfile C:\Users\user1\Downloads\kse-v4.1.3-offline-linux-amd64-all-20250225.tar.gz SHA256
    • Linux 系统

      sha256sum [file location]

      示例:

      sha256sum ~/Downloads/kse-v4.1.3-offline-linux-amd64-all-20250225.tar.gz
    • MacOS 系统

      shasum -a 256 [file location]

      示例:

      shasum -a 256 ~/Downloads/kse-v4.1.3-offline-linux-amd64-all-20250225.tar.gz
  2. 与安装包中的 SHA256 值进行比对,确保上一步得到的 SHA256 与其一致。

    注意

    如果 SHA256 不一致,您需要重新获取完整的 KubeSphere 企业版安装包。

查看安装包内容

了解 KubeSphere 企业版 v4.1.3 的安装包内容,以便进行后续步骤。

安装包包含以下文件:

kse-v4.1.3-offline-linux-amd64-all/
├── charts
│   ├── ks-core                   # KubeSphere 企业版核心组件
│   └── nfs-client-provisioner    # 用于对接 NFS 存储
├── tools
│   ├── extension-resources-patch.sh   # 用于处理 v4.1.2 及之前版本通过 kse-extension-publish 创建的扩展组件资源产生的冲突
│   └── oras                      # OCI 工具,便于镜像同步等操作
├── kse-extensions                # 其中包含所有扩展组件的 installplan,可用于快速安装 KubeSphere 企业版扩展组件
├── config-sample.yaml            # 安装配置文件的模版
├── create_project_harbor.sh      # 用于快速创建 harbor 项目
├── kk                            # 集群部署工具
├── kubekey-artifact.tar.gz       # KubeSphere 企业版制品,其中包含集群部署所需的二进制文件及镜像
└── manifest-v413-amd64.yaml      # KubeSphere 企业版制品清单,其中包含各组件的版本以及镜像列表

配置安装配置文件

config-sample.yaml 是 KubeSphere 企业版的安装配置文件,请先配置该文件,以便进行后续步骤。

说明

安装完成后,请勿删除安装配置文件 config-sample.yaml,后续进行节点添加等操作时仍需要使用该文件。如果该文件丢失,您需要重新创建安装配置文件。

  1. 将 KubeSphere 企业版安装包传输到任意集群节点,并登录该集群节点。

  2. 执行以下命令解压安装包,并进入安装包解压后生成的目录(将 <package name> 替换为安装包的实际名称,将 <directory> 替换为安装包解压后生成的目录):

    tar -zxvf <package name>
    cd <directory>
  3. 执行以下命令为 KubeKey 二进制文件 kk 添加执行权限:

    sudo chmod +x kk
  4. 执行以下命令编辑安装配置文件 config-sample.yaml

    vi config-sample.yaml

    以下为部分示例配置文件,如需了解完整示例,请参阅此文件

    apiVersion: kubekey.kubesphere.io/v1alpha2
    kind: Cluster
    metadata:
      name: sample
    spec:
      hosts:
      - {name: controlplane1, address: 192.168.0.2, internalAddress: 192.168.0.2, port: 23, user: ubuntu, password: Testing123, arch: arm64} # arm64 节点注意添加参数 arch: arm64
      - {name: controlplane2, address: 192.168.0.3, internalAddress: 192.168.0.3, user: ubuntu, privateKeyPath: "~/.ssh/id_rsa"}
      - {name: worker1, address: 192.168.0.4, internalAddress: 192.168.0.4, user: ubuntu, password: Testing123}
      - {name: worker2, address: 192.168.0.5, internalAddress: 192.168.0.5, user: ubuntu, password: Testing123}
      - {name: registry, address: 192.168.0.6, internalAddress: 192.168.0.6, user: ubuntu, password: Testing123}
      roleGroups:
        etcd:
        - controlplane1
        - controlplane2
        control-plane:
        - controlplane1
        - controlplane2
        worker:
        - worker1
        - worker2
        # 如需使用 kk 自动部署镜像仓库,请设置 registry(建议镜像仓库与集群节点分离部署,减少相互影响)
        registry:
        - registry
      controlPlaneEndpoint:
        internalLoadbalancer: haproxy # 如需部署⾼可⽤集群,且⽆负载均衡器可⽤,可开启该参数,做集群内部负载均衡
        domain: lb.kubesphere.local
        address: ""
        port: 6443
      kubernetes:
        version: v1.23.15
        clusterName: cluster.local
      network:
        plugin: calico
        kubePodsCIDR: 10.233.64.0/18
        kubeServiceCIDR: 10.233.0.0/18
        ## multus support. https://github.com/k8snetworkplumbingwg/multus-cni
        enableMultusCNI: false
      registry:
        # 如需使用 kk 部署 harbor,可将该参数设置为 harbor,不设置该参数且需使用 kk 部署容器镜像仓库,将默认部署 docker registry。
        # harbor 不支持 arm64,arm64 环境部署时,可不配置该参数。
        type: harbor
        # 如使用 kk 部署的 harbor 或其他需要登录的仓库,需设置对应仓库的 auths,如使用 kk 部署默认的 docker registry 仓库,则无需配置 auths 参数。
        # 注意:如使用 kk 部署 harbor,auths 参数请于创建 harbor 项目之后设置。
        auths:
          "dockerhub.kubekey.local":
            username: admin # harbor 默认用户名
            password: Harbor12345 # harbor 默认密码
            plainHTTP: false  # 如果仓库使用 http,请将该参数设置为 true
        privateRegistry: "dockerhub.kubekey.local/kse"   # 设置集群部署时使用的私有仓库地址
        registryMirrors: []
        insecureRegistries: []
      addons: []
  5. config-sample.yaml 配置文件的 spec:hosts 参数下设置各服务器的信息。

    参数 描述

    name

    用户自定义的服务器名称。

    address

    服务器的 SSH 登录 IP 地址。

    internalAddress

    服务器在子网内部的 IP 地址。

    port

    服务器的 SSH 端口号。如果使用默认端口 22 可不设置此参数。

    user

    服务器的 SSH 登录用户名,该用户必须为 root 用户或其他具有 sudo 命令执行权限的用户。如果使用 root 用户可不设置此参数。

    password

    服务器的 SSH 登录密码。如果已经设置 privateKeyPath 可不设置此参数。

    privateKeyPath

    服务器的 SSH 登录密钥的路径。如果已经设置 password 可不设置此参数。

    arch

    服务器的硬件架构。如果服务器的硬件架构为 arm64,请将此参数设置为 arm64,否则请勿设置此参数。安装包默认仅支持所有集群节点都为 x86_64 或 arm64 架构的场景。如果某集群节点的硬件架构不完全相同,需针对具体情况进行技术评估,请咨询青云科技官方解决方案专家或交付服务专家。

  6. config-sample.yaml 配置文件的 spec:roleGroups 参数下设置服务器的角色:

    参数 描述

    etcd

    安装 etcd 数据库的节点。请在此参数下设置集群控制平面节点。

    control-plane

    集群控制平面节点。如果您已经为集群配置了高可用性,您可以设置多个控制平面节点。

    worker

    集群工作节点。

    registry

    用于创建私有镜像服务的服务器。该服务器不会用作集群节点。 安装、升级 KubeSphere 企业版时,如果集群节点无法连接互联网,需要在此参数下设置用于创建私有镜像服务的服务器。其他情况下请将此参数注释掉。

  7. 如果您规划了多个控制平面节点,在 config-sample.yaml 配置文件的 spec:controlPlaneEndpoint 参数下设置高可用性信息。

    参数 描述

    internalLoadbalancer

    本地负载均衡器的类型。如果使用本地负载均衡配置,请将此参数设置为 haproxy。否则,请将此参数注释掉。

    domain

    负载均衡器的内部访问域名。请将此参数设置为 lb.kubesphere.local

    address

    负载均衡器的 IP 地址。如果使用本地负载均衡配置,请将此参数留空;如果使用专用负载均衡器,请将此参数设置为负载均衡器的 IP 地址;如果使用通用服务器作为负载均衡器,请将此参数设置为负载均衡器的浮动 IP 地址。

    port

    负载均衡器监听的端口号,即 apiserver 服务的端口号。请将此参数设置为 6443

  8. 如果您需要使用外部持久化存储,在 config-sample.yaml 配置文件的 spec:addons 参数下设置外部持久化存储信息。

    • 如果使用云上存储设备,在 spec:addons 下设置以下参数(将 <configuration file path> 替换为存储插件配置文件的实际路径):

        - name: csi-qingcloud
          namespace: kube-system
          sources:
            chart:
              name: csi-qingcloud
              path: charts/csi-qingcloud  # 替换为 chart 包的实际路径
              valuesFile: <configuration file path>
    • 如果使用 NeonSAN 存储设备,在 spec:addons 下设置以下参数(将 <configuration file path> 替换为存储插件配置文件的实际路径):

        - name: csi-neonsan
          namespace: kube-system
          sources:
            chart:
              name: csi-neonsan
              path: charts/csi-neonsan  # 替换为 chart 包的实际路径
              valuesFile: <configuration file path>
    • 如果使用 NFS 存储系统,在 spec:addons 下设置以下参数(将 <configuration file path> 替换为存储插件配置文件的实际路径):

        - name: nfs-client
          namespace: kube-system
          sources:
            chart:
              name: nfs-client-provisioner
              repo: charts/nfs-client-provisioner
              valuesFile: <configuration file path>

创建私有镜像仓库

注意

如果您已有可用的镜像仓库,可跳过此步骤。但需要把私有镜像服务的默认地址 dockerhub.kubekey.local/kse 替换为您的实际镜像仓库地址。

  1. 在配置文件 config-sample.yamlspec:hosts 参数下设置用于创建私有镜像服务的服务器的信息。

    spec:
      hosts:
      - {name: registry, address: 192.168.0.6, internalAddress: 192.168.0.6, user: ubuntu, password: Testing123}
    参数 描述

    name

    用户自定义的服务器名称。

    address

    服务器的 SSH 登录 IP 地址。

    internalAddress

    服务器在子网内部的 IP 地址。

    port

    服务器的 SSH 端口号。如果使用默认端口 22 可不设置此参数。

    user

    服务器的 SSH 登录用户名,该用户必须为 root 用户或其他具有 sudo 命令执行权限的用户。如果使用 root 用户可不设置此参数。

    password

    服务器的 SSH 登录密码。如果已经设置 privateKeyPath 可不设置此参数。

    privateKeyPath

    服务器的 SSH 登录密钥的路径。如果已经设置 password 可不设置此参数。

    arch

    服务器的硬件架构。如果服务器的硬件架构为 arm64,请将此参数设置为 arm64,否则请勿设置此参数。安装包默认仅支持所有集群节点都为 x86_64 或 arm64 架构的场景。如果某集群节点的硬件架构不完全相同,需针对具体情况进行技术评估,请咨询青云科技官方解决方案专家或交付服务专家。

  2. spec:roleGroups:registry 参数下设置用于创建私有镜像服务的服务器名称(将 <registry name> 替换为 spec:hosts 参数下设置的服务器实际名称)。

    spec:
      roleGroups:
        registry:
        - <registry name>
  3. spec:registry:privateRegistry 参数设置为私有镜像服务的默认地址 dockerhub.kubekey.local/kse,然后保存文件。

    spec:
      registry:
        registryMirrors: []
        insecureRegistries: []
        privateRegistry: dockerhub.kubekey.local/kse
  4. 执行以下命令初始化私有镜像服务:

    ./kk init registry -f config-sample.yaml -a kubekey-artifact.tar.gz

    如果显示如下信息,则表明镜像仓库创建成功。

    verify-registry

    说明

    KubeKey 将在 config-sample.yaml 配置文件中 spec:roleGroups:registry 参数指定的服务器上创建私有镜像服务,默认地址为 dockerhub.kubekey.local/kse

  5. spec:registry:type 参数设置为 harbor,执行以下命令创建 Harbor 项目。

    bash create_project_harbor.sh

    创建 harbor 项目后,在 config-sample.yaml 中配置 spec:registry:auths 参数。

    说明

    harbor 安装文件在 /opt/harbor 目录下,可在该目录下对 harbor 进行运维。

  6. 如果同时满足以下条件,需执行以下步骤在 harbor 所在节点添加 containerd 配置。

    • 镜像仓库使用 harbor

    • 容器运行时为 containerd

    • harbor 所在节点也在待部署的集群中

    mkdir /etc/containerd
    # 创建 containerd 配置文件
    # 注意修改 sandbox_image 以及 [plugins."io.containerd.grpc.v1.cri".registry.configs]
    # 下的仓库信息为实际环境信息
    
    cat <<EOF > /etc/containerd/config.toml
    version = 2
    root = "/var/lib/containerd"
    state = "/run/containerd"
    
    [grpc]
      address = "/run/containerd/containerd.sock"
      uid = 0
      gid = 0
      max_recv_message_size = 16777216
      max_send_message_size = 16777216
    
    [ttrpc]
      address = ""
      uid = 0
      gid = 0
    
    [debug]
      address = ""
      uid = 0
      gid = 0
      level = ""
    
    [metrics]
      address = ""
      grpc_histogram = false
    
    [cgroup]
      path = ""
    
    [timeouts]
      "io.containerd.timeout.shim.cleanup" = "5s"
      "io.containerd.timeout.shim.load" = "5s"
      "io.containerd.timeout.shim.shutdown" = "3s"
      "io.containerd.timeout.task.state" = "2s"
    
    [plugins]
      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
        runtime_type = "io.containerd.runc.v2"
        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
          SystemdCgroup = true
      [plugins."io.containerd.grpc.v1.cri"]
        sandbox_image = "dockerhub.kubekey.local/kse/kubesphere/pause:3.6"
        [plugins."io.containerd.grpc.v1.cri".cni]
          bin_dir = "/opt/cni/bin"
          conf_dir = "/etc/cni/net.d"
          max_conf_num = 1
          conf_template = ""
        [plugins."io.containerd.grpc.v1.cri".registry]
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
            [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
              endpoint = ["https://registry-1.docker.io"]
            [plugins."io.containerd.grpc.v1.cri".registry.configs]
              [plugins."io.containerd.grpc.v1.cri".registry.configs."dockerhub.kubekey.local".auth]
                username = "admin"
                password = "harbor2345"
                [plugins."io.containerd.grpc.v1.cri".registry.configs."dockerhub.kubekey.local".tls]
                  ca_file = ""
                  cert_file = ""
                  key_file = ""
                  insecure_skip_verify = true
    EOF
    # 重启 containerd
    systemctl restart containerd
  7. 登录所有集群节点,执行以下命令编辑 /etc/hosts 文件:

    vi /etc/hosts

    /etc/hosts 文件中添加以下信息,从而为集群节点配置私有镜像服务的域名解析规则(将 <registry IP address> 替换成私有镜像服务的实际 IP 地址,将私有镜像服务的默认地址 dockerhub.kubekey.local 替换为您的实际镜像仓库地址),然后保存文件:

    <registry IP address> dockerhub.kubekey.local

安装 Kubernetes

说明
  • 如果您已有可用的 Kubernetes 集群,可跳过此步骤。

  • 安装包中集成了 CentOS 7、Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04 依赖包,如使用这些操作系统需要使用 kk 自动安装系统依赖,可在安装命令后添加 --with-packages ; 如使用这些操作系统之外的操作系统或由于依赖问题导致失败,需手动安装相关依赖(conntrack)。

  • 如需使用 openebs localpv,可在如下命令后添加参数 --with-local-storage,如需对接其他存储,可在配置文件 addons 中添加配置相关存储插件,或 Kubernetes 集群部署完成后自行安装。

  • 如使用 kk 部署的 harbor,请确保安装 Kubernetes 之前,已创建 harbor 项目,且配置文件 config-sample.yaml 中已配置 spec:registry:auths 参数。

执行以下命令创建 Kubernetes 集群:

 ./kk create cluster -f config-sample.yaml -a kubekey-artifact.tar.gz

如果显示如下信息,则表明 Kubernetes 集群创建成功。

Pipeline[CreateclusterPipeline] execute successfully
Installation is complete.

导入镜像到私有镜像仓库

执行以下命令将镜像导入到指定的私有镜像仓库中。

./kk artifact images push  -f config-sample.yaml -a kubekey-artifact.tar.gz

如果显示如下信息,则表明导入成功。

Pipeline[ArtifactImagesPushPipeline] execute successfully

安装 KubeSphere 企业版

  1. 在集群节点,执行以下命令安装 KubeSphere Core。

    helm upgrade --install -n kubesphere-system --create-namespace ks-core charts/ks-core \
    --debug \
    --wait \
    --set global.imageRegistry=dockerhub.kubekey.local/kse \
    --set extension.imageRegistry=dockerhub.kubekey.local/kse
    注意

    global.imageRegistryextension.imageRegistry 的默认地址 dockerhub.kubekey.local/kse 替换为您的实际镜像仓库地址。

    取决于您的硬件和网络环境,您可能需要配置流量转发规则并在防火墙中放行 30880 端口。如果显示如下信息,则表明 ks-core 安装成功:

    NOTES:
    Thank you for choosing KubeSphere Helm Chart.
    
    Please be patient and wait for several seconds for the KubeSphere deployment to complete.
    
    1. Wait for Deployment Completion
    
        Confirm that all KubeSphere components are running by executing the following command:
    
        kubectl get pods -n kubesphere-system
    
    2. Access the KubeSphere Console
    
        Once the deployment is complete, you can access the KubeSphere console using the following URL:
    
        http://192.168.6.10:30880
    
    3. Login to KubeSphere Console
    
        Use the following credentials to log in:
    
        Account: admin
        Password: P@88w0rd
    
    NOTE: It is highly recommended to change the default password immediately after the first login.
    
    For additional information and details, please visit https://kubesphere.io.
  2. 从成功信息中的 ConsoleAccountPassword 参数分别获取 KubeSphere 企业版 Web 控制台的 IP 地址、管理员用户名和管理员密码,并使用网页浏览器登录 KubeSphere 企业版 Web 控制台。

  3. 根据激活提示点击激活,导入 KubeSphere 企业版的 license。

  4. 此时,Web 控制台仅提供 KubeSphere 企业版的核心功能,若要体验更多功能,还需在扩展中心安装扩展组件