本节介绍如何在不能访问 Internet 的环境下使用离线安装包部署 Kubernetes 和 KubeSphere。

安装过程中将用到开源工具 KubeKey 的 v4.x 版本。有关 KubeKey 的更多信息，请访问 GitHub KubeKey 仓库。

注意： KubeSphere 社区版用户需要在联网状态下自行构建离线安装包；KubeSphere 其他版本的用户可联系 KubeSphere 交付服务专家获取最新的离线安装包，即可跳过「构建离线安装包」一节。

说明

安装过程依赖 tar 工具完成软件包的压缩和解压，请提前确认系统环境已预装该命令。若 config.yaml 中配置了 charts 参数，请确保打包节点已提前安装 Helm。

概述

与在线安装相比，离线安装需要先在可访问 Internet 的机器上将所需的组件与镜像打包为离线安装包，再将其传输至目标环境进行安装。整体流程如下：

  1. 构建离线安装包（在联网机器上）：下载组件与镜像，并打包为 artifact.tgz。

  2. 传输离线包：将 artifact.tgz 拷贝至目标环境（例如通过存储介质或内网传输）。

  3. 安装集群（在目标环境）：解压离线包，将镜像推送至私有镜像仓库（若单独安装私有镜像仓库，即方式一；若由 KubeKey 在创建集群时同步安装，镜像推送由安装流程自动完成），然后安装 Kubernetes 与 KubeSphere。

角色说明

离线安装涉及以下四类角色：

角色 职责 最低配置（每节点） 网络要求

打包节点

从 Internet 下载所需软件包与镜像，构建离线安装包

CPU：1 核，内存：1 GB，硬盘：150 GB

需能访问互联网

部署节点（运行 Web Installer 服务）

安装过程中在该节点执行 kk 命令以运行安装服务

CPU：1 核，内存：1 GB，硬盘：150 GB

与 Kubernetes 节点网络互通

私有镜像仓库节点

存放集群所需的容器镜像

CPU：8 核，内存：16 GB，硬盘：100 GB

与 Kubernetes 节点网络互通

Kubernetes 节点

运行集群工作负载（无需提前安装 Kubernetes）

CPU：2 核，内存：4 GB，硬盘：40 GB

节点间网络互通
说明

  • 同一台主机可同时承担多个角色，例如同时作为部署节点与私有镜像仓库节点，或同时作为部署节点与 Kubernetes 节点。

  • 私有镜像仓库节点与 Kubernetes 节点不能是同一台主机，因为安装过程中 Kubernetes 组件会重启容器运行时，可能导致镜像仓库服务中断。

前提条件

说明

以下为 Kubernetes 节点需满足的前提条件。

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

  • 集群节点的操作系统和版本须为 Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04、Ubuntu 24.04、Debian 10、Debian 11、CentOS 8、AlmaLinux 9.0 或 Kylin v10。多台服务器的操作系统可以不同。关于其它操作系统和版本支持，请咨询青云科技官方解决方案专家或交付服务专家。

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

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

    说明

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

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

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

  • 请确保在所有集群节点上都可以使用 sudo、tar、curl 和 openssl 命令。

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

配置防火墙规则

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

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

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

ssh

TCP

allow

22

N/A

N/A

etcd

TCP

allow

2379

2380

N/A

apiserver

TCP

allow

6443

N/A

N/A

calico

TCP

allow

9099

9100

N/A

bgp

TCP

allow

179

N/A

N/A

nodeport

TCP

allow

30000

32767

N/A

master

TCP

allow

10250

10258

N/A

worker

TCP

allow

10250

N/A

N/A

dns

TCP

allow

53

N/A

N/A

dns

UDP

allow

53

N/A

N/A

local-registry

TCP

allow

5000

N/A

离线环境需要

local-apt

TCP

allow

5080

N/A

离线环境需要

rpcbind

TCP

allow

111

N/A

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

ipip

IPENCAP / IPIP

allow

N/A

N/A

使用 Calico 时需要

构建离线安装包

创建配置文件

提示： 可通过 https://get-images.kubesphere.io 页面生成配置文件。 登录打包节点，在打包节点上创建 config.yaml 文件：

apiVersion: kubekey.kubesphere.io/v1
kind: Config
spec:
  zone: "cn"
  download:
    arch:
      - amd64
      - arm64
    images:
      policy: warn
      registry: hub.kubesphere.com.cn
    kubernetes:
      kube_version:
        - v1.23.17
        - v1.24.17
        - v1.25.16
        - v1.26.15
        - v1.27.16
        - v1.28.15
        - v1.29.15
        - v1.30.14
        - v1.31.12
        - v1.32.11
        - v1.33.7
        - v1.34.3
    cni:
      type:
        - calico
        - cilium
        - flannel
        - kubeovn
        - hybridnet
      # multi_cni:               # 可选，多 CNI 管理组件，如 multus
      #   - multus
      #   - spiderpool
    cri:
      container_manager:
        - containerd
        - docker
    storage_class:
      local:
        enabled: true
      nfs:
        enabled: true
    image_registry:
      type:
        - harbor
        - docker-registry
    iso:
      - "almalinux-9.0-rpms"
      - "kylin-v10SP3-rpms"
      - "ubuntu-22.04-debs"
      - "centos-8-rpms"
      - "kylin-v10SP2-rpms"
      - "ubuntu-24.04-debs"
      - "debian-10-debs"
      - "kylin-v10SP1-rpms"
      - "debian-11-debs"
      - "ubuntu-18.04-debs"
      - "kylin-v10SP3-2403-rpms"
      - "ubuntu-20.04-debs"
      # 按需增删

字段说明：

字段 说明

apiVersion

配置文件的 API 版本，固定值为 kubekey.kubesphere.io/v1

kind

资源类型，固定值为 Config

spec.zone

软件包下载的区域，cn 表示使用国内源

spec.download.arch

指定需要下载的 CPU 架构，支持 amd64 和 arm64

spec.download.images.policy

镜像下载策略，warn 表示如果镜像缺少某些CPU架构或操作系统，仅记录警告；strict 表示拉取的镜像必须包含所有选定的CPU架构和操作系统，否则报错

spec.download.images.registry

镜像仓库地址

spec.download.kubernetes.kube_version

需要包含的 Kubernetes 版本列表

spec.download.cni.type

需要包含的 CNI 插件类型

spec.download.cni.multi_cni

需要包含的多 CNI 管理组件

spec.download.cri.container_manager

容器运行时类型，支持 containerd 和 docker

spec.download.storage_class

需要包含的存储类，支持 local、nfs

spec.download.image_registry.type

镜像仓库类型，支持 harbor 和 docker-registry

spec.download.iso

制作 ISO 依赖包的操作系统列表，用于安装系统依赖

获取 kk 与 Web Installer

如果访问 GitHub 或 Google APIs 受限，请设置如下环境变量：

export KKZONE=cn

执行以下命令下载 KubeKey 和 Web Installer：

curl -sfL https://get-kk.kubesphere.io | sh -

执行完成后，会在当前目录生成以下文件：

原文件 解压后文件

kubekey-v4.x.x-linux-amd64.tar.gz

kk：KubeKey 二进制文件

web-installer.tgz

dist：Web 页面资源；host-check.yaml、kubernetes、kubesphere：任务模板文件；schema：配置文件；README.md：安装说明文档

package.sh

离线安装包的构建脚本

制作离线安装包

执行构建脚本：

./package.sh config.yaml

当输出以下信息时，表示制作成功：

Offline package artifact.tgz has been created successfully.

离线包为 artifact.tgz，包含以下内容：

artifact/
├── kubekey-artifact.tgz    # 完整的离线资源包
└── tools/                  # 不同架构的工具包
    ├── amd64/
    │   ├── kubekey-v4.x.x-linux-amd64.tar.gz
    │   ├── nerdctl-2.2.1-linux-amd64.tar.gz
    │   └── oras_1.3.0_linux_amd64.tar.gz
    └── arm64/
        ├── kubekey-v4.x.x-linux-arm64.tar.gz
        ├── nerdctl-2.2.1-linux-arm64.tar.gz
        └── oras_1.3.0_linux_arm64.tar.gz

将 artifact.tgz 传输至目标环境后，后续步骤均在目标环境中执行。

使用离线包安装集群

安装集群前，需要指定私有镜像仓库地址。有以下两种方式：

  • 方式一：单独安装私有镜像仓库，请参考 镜像仓库安装。

  • 方式二：在创建集群时同时安装镜像仓库，需要在 inventory.yaml 和 config.yaml 中添加对应配置信息。详情请参考下文命令行安装步骤。

选择安装方式

以下两种方法均可完成 Kubernetes 和 KubeSphere 的安装，安装结果一致，您只需选择其中一种操作入口即可，无需同时执行：

  • 方法 1：命令行安装：适用于熟悉命令行操作、需要精细化配置集群参数的场景。

  • 方法 2：Web Installer 安装：适用于希望通过图形化界面完成节点添加、参数配置和安装校验的场景。

说明

两种方法任选其一，请勿重复执行。两种方法均支持上文所述的两种私有镜像仓库部署方式（单独安装、或在创建集群时同步安装）。

解压离线包

tar -zxvf artifact.tgz

方法 1：命令行安装

1. 进入离线包目录并解压工具

KubeKey 工具位于 tools/{arch}/ 目录下，请根据安装机器的架构解压对应工具。

查看机器架构：

uname -m

进入离线包目录：

cd artifact/

解压 KubeKey 到离线包目录：

tar -zxvf tools/{arch}/kubekey-v4.x.x-linux-{arch}.tar.gz -C .

2. 推送镜像到私有镜像仓库（仅方式一：单独安装私有镜像仓库）

说明

  • 仅当采用 方式一（单独安装私有镜像仓库） 时，需要手动执行本步骤，将离线包中的镜像推送到已部署的私有镜像仓库。如果采用

  • 方式二（创建集群时同步安装镜像仓库），KubeKey 会在执行 kk create cluster 时自动部署镜像仓库并推送镜像，请跳过本步骤。

执行以下命令将离线包中的镜像推送到已部署的私有镜像仓库：

./kk artifact images --push -c config.yaml -a kubekey-artifact.tgz

注意： 执行前请确保推送所用的 config.yaml 中已正确配置私有镜像仓库地址（即 spec.image_registry.auth 字段）。该 config.yaml 与上文「构建离线安装包」步骤中用于打包的配置文件为同一文件。

3. 创建节点配置文件

执行以下命令创建节点配置文件 inventory.yaml：

./kk create inventory -o .

命令执行完毕后，将生成节点配置文件 inventory.yaml。inventory.yaml 主要用于设置集群中各节点的连接信息，示例如下：

apiVersion: kubekey.kubesphere.io/v1
kind: Inventory
metadata:
  name: default
spec:
  hosts:
    # localhost:
    #   connector:
    #     password: 123456
    # node1:
    #   connector:
    #     type: ssh
    #     host: node1
    #     port: 22
    #     user: root
    #     password: 123456
    #   internal_ipv4: 1.1.1.1
  groups:
    # 所有 Kubernetes 节点
    k8s_cluster:
      groups:
        - kube_control_plane
        - kube_worker
    # 控制平面节点
    kube_control_plane:
      hosts:
        - localhost
    # 工作节点
    kube_worker:
      hosts:
        - localhost
    # etcd 节点（仅当 etcd_deployment_type 为 external 时）
    etcd:
      hosts:
        - localhost
#    image_registry:
#      hosts:
#        - localhost
    # NFS 节点（用于镜像仓库存储和 Kubernetes NFS 存储）
#    nfs:
#      hosts:
#        - localhost

spec.hosts 中的节点连接参数：

参数 描述

<key>

节点名称

<key>.connector

节点连接信息

<key>.connector.type

节点连接类型。支持 local（本地连接）和 ssh（远程连接）。KubeKey 会根据节点名称或 IP 自动识别连接类型

<key>.connector.host

使用 SSH 连接节点时的地址

<key>.connector.port

使用 SSH 连接节点时的端口。默认值：22

<key>.connector.user

使用 SSH 连接节点时的用户名。默认值：root

<key>.connector.password

连接节点时的密码。local 连接时对应 sudo 密码，ssh 连接时对应 SSH 密码

<key>.connector.private_key

SSH 连接节点时的私钥文件路径。密码和密钥任选其一

<key>.connector.private_key_content

SSH 连接节点时的私钥文件内容。可使用密钥内容替代密钥文件路径

<key>.internal_ipv4

节点在集群中通信时使用的 IPv4 地址

<key>.internal_ipv6

节点在集群中通信时使用的 IPv6 地址

spec.groups 中的节点角色参数：

参数 描述

k8s_cluster

Kubernetes 集群节点分组。包含 kube_control_plane 和 kube_worker，无需额外配置

kube_control_plane

Kubernetes 集群中的控制平面节点。在 kube_control_plane.hosts 中配置 spec.hosts 中定义的节点名称

kube_worker

Kubernetes 集群中的工作节点。在 kube_worker.hosts 中配置 spec.hosts 中定义的节点名称

etcd

Kubernetes 集群中的 etcd 节点。在 etcd.hosts 中配置 spec.hosts 中定义的节点名称

image_registry

用于创建私有镜像仓库的节点。离线安装时通常需要配置

如果选择在创建集群时同时安装镜像仓库，需要在 inventory.yaml 中额外添加 image_registry 节点和分组。示例如下：

spec:
  hosts:
    harbor1:
      connector:
        type: ssh
        host: 172.16.0.1
        port: 22
        user: root
        password: 123456
      internal_ipv4: 172.16.0.1
  groups:
    image_registry:
      hosts:
        - harbor1

4. 创建安装配置文件

执行以下命令创建安装配置文件。以下示例使用 v1.32.11，该版本已包含在前文 config.yaml 示例的离线资源列表中：

./kk create config --with-kubernetes v1.32.11 -o .

将 v1.32.11 替换为实际需要的 Kubernetes 版本。请确保替换后的版本已包含在构建离线包时使用的 spec.download.kubernetes.kube_version 列表中。

命令执行完毕后，将生成安装配置文件 config-v1.32.11.yaml。

如果选择在创建集群时同时安装镜像仓库，需要在 config-v1.32.11.yaml 中补充镜像仓库配置：

apiVersion: kubekey.kubesphere.io/v1
kind: Config
spec:
  download:
    arch:  # 推送镜像的架构
     - amd64
     - arm64
    images:
      # 镜像检查策略。
      # warn: 如果镜像缺少某些CPU架构或操作系统，仅记录警告
      # strict: 拉取的镜像必须包含所有选定的CPU架构和操作系统，否则报错。（默认）
      policy: warn # 有些镜像可能只有amd64单架构，推送多架构镜像时请设置为 warn
  image_registry:
    auth:
      registry: dockerhub.kubekey.local # 私有镜像仓库地址
      username: admin # 私有镜像仓库登录用户名
      password: Harbor12345 # 私有镜像仓库登录密码
      skip_tls_verify: false # 是否跳过 TLS 证书验证，默认为 false
      plain_http: false # 是否使用 HTTP 明文传输，默认为 false

5. 安装集群

./kk create cluster -a kubekey-artifact.tgz -i inventory.yaml -c config-v1.32.11.yaml

6. 安装 KubeSphere

KubeKey v4.x 将 Kubernetes 和 KubeSphere 解耦安装，安装完 Kubernetes 后需手动执行以下 Helm 命令安装 KubeSphere。

说明

ks-core Helm Chart 包包含在 kubekey-artifact.tgz 中，解压 kubekey-artifact.tgz 后位于 charts/ 目录下。

 
tar -zxvf kubekey-artifact.tgz
helm upgrade --install \
  -n kubesphere-system \
  --create-namespace \
  ks-core \
  ./charts/ks-core-1.2.5.tgz \
  --debug \
  --wait \
  --reset-values \
  --set auditing.enable=true \
  --set ha.enabled=true \
  --set redisHA.enabled=true \
  --set global.imageRegistry=dockerhub.kubekey.local \
  --set extension.imageRegistry=dockerhub.kubekey.local
说明

  • 请将上文仓库地址替换为您实际的私有镜像仓库地址。

  • auditing.enable、ha.enabled、redisHA.enabled 为生产环境推荐启用的配置项，可根据实际需求调整。

  • Helm 版本需要 >= 3.17.0。

方法 2：Web Installer 安装

1. 进入离线包目录并解压工具

KubeKey 工具位于 tools/{arch}/ 目录下，请根据安装机器的架构解压对应工具。

查看机器架构：

uname -m

进入离线包目录：

cd artifact/

解压 KubeKey 到离线包目录：

tar -zxvf tools/$(uname -m)/kubekey-v4.x.x-linux-$(uname -m).tar.gz -C .

解压 kubekey-artifact.tgz 到工作目录。该文件包含安装时所需的所有资源：二进制文件、Helm Chart 包、镜像文件等。

mkdir kubekey
tar -zxvf kubekey-artifact.tgz -C kubekey

2. 启动 Web Installer

./kk web --port 8080 --schema-path web-installer/schema --ui-path web-installer/dist

如果显示如下信息，表示 Web Installer 启动成功：

Web server started successfully on port 8080

请勿关闭命令终端。

3. 通过 Web Installer 部署 Kubernetes 和 KubeSphere

在浏览器中访问 http://<部署节点 IP 地址>:8080，点击 开始安装，进入部署流程。

3.1 添加集群节点

  • Master：控制平面节点，负责集群调度与管理。Master 节点上会自动安装 etcd。

  • Worker：工作节点，运行实际业务容器。

  • Image：镜像仓库节点，用于自动部署私有镜像仓库。在线安装时通常无需配置此角色。

Web Installer 支持以下三种节点添加方式：

  • 手动添加：适用于添加单个节点。您需要填写主机名、IP 地址、SSH 地址、SSH 认证等信息。

  • 文件上传：适用于批量添加节点。请根据模板填写节点信息后上传文件。

  • 节点扫描：适用于自动发现节点。您可以通过 IP CIDR 扫描节点，并根据扫描结果选择需要添加的节点。

注意： 如果只添加一个节点，节点角色必须为 Master & Worker。

3.2 修改配置参数

配置部署 Kubernetes 和 KubeSphere 所需的参数。

Kubernetes 和 KubeSphere Core 标签页均支持 表单模式 和 YAML 模式。您可以在表单中填写配置信息（所有参数均需配置），也可以直接编辑 YAML 文件。如需了解更多配置信息，请参阅 配置示例。

说明

如果选择安装镜像仓库，需通过 YAML 模式 添加以下参数，跳过在线下载：

 
download:
  fetch: false

安装镜像仓库

如果需要在安装集群时同时部署私有镜像仓库，请在添加节点时添加 Image 角色的节点，并在 Kubernetes 配置参数中将镜像仓库类型设置为 harbor 或 docker-registry：

  • 单节点镜像仓库：添加 1 个 Image 角色节点，在 Kubernetes 配置参数中设置镜像仓库类型。

  • 高可用镜像仓库：添加多个 Image 角色节点（建议 ≥ 3 个），在 Kubernetes 配置参数中设置镜像仓库类型，并配置镜像仓库高可用虚拟 IP 作为访问入口。

配置完成后，点击 下一步。

3.3 安装预览

在 安装预览 页面，确认版本等信息无误后，点击 下一步：执行安装 开始安装。也可以返回上一步修改配置参数。

3.4 安装

耐心等待安装完成。安装完成后，系统会自动进入安装校验步骤。

若安装过程中出现异常，点击 查看日志 查看日志详情，退出或初始化后重新安装。

说明

若需要在 Web Installer 页面重新安装、修改配置参数或清除配置，点击左侧的 初始化 按钮，将重置 Kubernetes 节点上的所有任务并回到基本信息页面。初始化操作不可逆，请谨慎执行。
3.5 安装校验

  1. 在 安装校验 页面，点击 开始检测，系统将自动运行对应的检测脚本验证系统可用性。

  2. 若通过系统检测，点击 完成，可查看 KubeSphere 的访问地址、管理员用户名和默认密码。

  3. 在网页浏览器上输入访问地址，登录 KubeSphere Web 控制台，即可开始使用 KubeSphere。

说明

取决于您的网络环境，您可能需要配置流量转发规则并在防火墙中放行 30880 端口。

访问 KubeSphere Web 控制台

安装完成后，在浏览器中访问安装结果中显示的 KubeSphere 控制台地址。

使用安装结果中显示的管理员用户名和默认密码登录 KubeSphere Web 控制台。首次登录后，建议立即修改默认密码。