KubeClipper – 文档

Docs: 创建集群

Mon, 01 Jan 0001 00:00:00 +0000

创建集群前，确认 KubeClipper 平台可用、节点已注册并就绪、组件资源的版本和架构匹配。建议先完成快速开始，验证一条完整的部署路径。

控制台创建

登录控制台，在集群页面创建集群。填写名称，选择控制节点、工作节点及组件版本，再按实际网络规划设置 Pod / Service CIDR。生产集群需提前规划控制平面高可用、API 访问地址和存储；单节点实验配置不能直接用于生产。

1.7 的推荐组件组合参见版本说明。资源不在平台中时先上传组件包。私有仓库相关字段参见 Registry；镜像仓库和组件包是两种独立资源。

CLI 创建与验证

离线创建集群提供带明确版本的 CLI 示例。创建请求提交后，在Operation中查看执行结果，并检查集群状态、节点 Ready、系统 Pod 和 Kubernetes API 健康状态。失败时先保留日志并排查，不要通过重置状态跳过失败步骤。

Docs: 高可用部署

Mon, 01 Jan 0001 00:00:00 +0000

本文部署 KubeClipper 平台的高可用控制面。平台 Server 的高可用与受管 Kubernetes 集群的高可用是两件事，需分别规划。

准备节点与网络

准备三个 Linux Server 节点，以及需要纳管的 Agent 节点。部署用户通过同一 SSH 私钥访问所有节点，并具备 sudo 权限。时间同步和端口要求见架构与网络。

Server 节点部署平台 etcd，节点数量和故障容忍按 etcd 仲裁要求规划。生产环境建议将平台 Server 与运行 Kubernetes 工作负载的节点分开。

安装和下载

按照快速开始安装 v1.7.0 kcctl，下载与目标架构匹配的完整 kc-amd64.tar.gz 或 kc-arm64.tar.gz 部署包。不要将 GitHub Release 的客户端二进制包传给 --pkg。

部署三个 Server 和 Agent

将示例 IP、私钥和部署包路径替换为实际值。--server 使用逗号分隔地址，--agent 可按区域填写。

read -r -s -p '设置 admin 密码: ' KC_ADMIN_PASSWORD
printf '\n'
kcctl deploy \
 --server 192.168.10.11,192.168.10.12,192.168.10.13 \
 --agent default:192.168.10.21,192.168.10.22 \
 --user root --pk-file "$HOME/.ssh/id_rsa" \
 --pkg "$PWD/kc-amd64.tar.gz" \
 --initial-password "$KC_ADMIN_PASSWORD"
unset KC_ADMIN_PASSWORD

保持 TLS 开启。多网卡环境通过 --ip-detect 与 --node-ip-detect 显式选择可达地址；可使用 kcctl deploy -h 核对参数。默认平台 etcd 端口为 12379、12380、12381。

验证结果

kcctl login --host https://192.168.10.11:8080 --username admin
kcctl status
kcctl doctor
kcctl get node

检查三个 Server 的服务状态、平台 etcd 成员和 Agent 是否正常。在其他 Server 地址重复检查 API 可达性。需要统一域名或 VIP 时，另行配置入口负载均衡和证书；部署三个 Server 不会自动创建入口 VIP。

浏览器默认访问各 Server 的 HTTP 80 控制台入口；CLI 使用 HTTPS 8080 API。生产入口应配置 HTTPS，并按实际网络限制管理端口访问。

添加和移除 Agent

kcctl join --agent default:192.168.10.23
kcctl get node

确认节点没有需要保留的集群和工作负载后，再执行移除：

kcctl drain --agent 192.168.10.23

先查看正常 drain 的错误原因，再决定后续处理；不要默认使用强制参数。升级前参见升级检查。

Docs: 集群创建排障

Mon, 01 Jan 0001 00:00:00 +0000

本页适用于 1.7。旧版 v1.2.1 的 Calico 下载问题及临时处理方法保留在1.2 历史文档，不应直接应用于 1.7。

提交后集群没有就绪

kcctl operation list -c demo
kcctl get cluster demo -o yaml
kcctl get node

继续查看 Operation 详情和日志。请求已接受、Operation 已结束和 Kubernetes 节点就绪需要分别确认。

离线包或镜像错误

用 kcctl resource list 核对版本和架构；通过失败步骤日志确认镜像路径、认证和网络。参考离线创建集群。

平台或 Agent 异常

运行 kcctl status、kcctl doctor，检查 API 入口、服务和 SSH 访问。平台使用的 SSH 凭据应为私钥；不要把公钥路径填入私钥字段。

排查顺序和日志命令见平台诊断；重试和取消见操作与日志。

Docs: 1.7 发布说明

Mon, 01 Jan 0001 00:00:00 +0000

本套文档对应 KubeClipper v1.7.0，发布于 2026 年 9 月 8 日。官方发布记录：v1.7.0。

主要变化

Operation v2 通过 API 管理操作、任务和执行状态，Agent 与 Server 使用 mTLS 通信。
kcctl operation 提供操作列表、详情、日志、重试和取消。
kcctl status 与 kcctl doctor 提供平台状态检查和诊断。
Registry 资源可用于选择 Kubernetes 镜像仓库和配置 containerd 镜像拉取。
部署预检查给出节点、角色和错误原因；Server 安装前等待平台 etcd 健康。

组件版本

Kubernetes	containerd	Calico
v1.37.0	2.2.4	v3.31.5
v1.36.4	2.2.4	v3.31.5
v1.35.8	2.2.4	v3.31.5

默认 Kubernetes 版本为 v1.37.0。实际可选项以平台组件资源为准；离线环境还需准备对应 CPU 架构的包。版本来源：v1.7.0 支持矩阵。

版本边界

本文描述 v1.7.0 已发布能力。生产使用前查看 Release、安全公告和所用二进制版本。升级前参考升级检查。

版本菜单保留 1.6～1.1 历史文档。1.6 文档按 v1.6.0 发布标签整理。

Docs: 部署 AIO

Mon, 01 Jan 0001 00:00:00 +0000

All-in-One 将 Server 和 Agent 部署在同一台 Linux 主机上，适合体验和实验。

完整步骤见快速开始：准备主机、安装 v1.7.0 kcctl、下载完整部署包、部署平台并创建实验集群。

生产环境请先规划独立的 Server 和工作节点，参考高可用部署。

Docs: 升级检查

Mon, 01 Jan 0001 00:00:00 +0000

平台升级与受管 Kubernetes 集群升级分别处理。本文介绍 KubeClipper 平台升级前后的检查，不承诺任意旧版本都可直接升级到 1.7。

升级前

记录 Server、Agent、kcctl 和 Console 的版本及节点拓扑，确认目标包的 CPU 架构。
查看目标版本的 Release、安全公告和配置变化。1.7 改用 Operation v2，旧操作记录和任务状态需要在测试环境核对。
在没有运行中安装、升级、备份等操作的窗口执行。先处理未完成或失败的操作。
备份平台 etcd、Server/Agent 配置、证书与持久化认证密钥，并验证恢复方法。受管集群的数据备份需要单独安排。
在可恢复的测试环境演练目标升级路径，记录服务中断和恢复步骤。

kcctl version
kcctl status
kcctl doctor
kcctl operation list
kcctl upgrade -h

执行升级

kcctl upgrade 支持整个平台或组件升级。目标包应满足命令帮助中的目录结构，并已经在测试环境验证；不要把客户端包当成平台升级包。

UPGRADE_PACKAGE=/path/to/validated-upgrade-package.tar.gz
kcctl upgrade all --pkg "$UPGRADE_PACKAGE"

只有 Release 或已验证部署流程明确支持时，才使用在线升级或组件独立替换。不要把替换一个二进制文件视为整个升级完成。

升级后

再次检查 kcctl status、kcctl doctor，核对各节点实际运行版本。验证登录、节点信息、操作详情与日志、受管集群访问及 Console 基本流程。测试一个受控的生命周期操作，确认 Operation 和实际集群状态一致。

升级失败时保留错误和日志，按事先验证的恢复步骤处理。恢复旧二进制前先判断数据和配置是否仍兼容，不要在未知状态下反复覆盖服务。

Docs: 集群托管

Tue, 29 Nov 2022 00:00:00 +0000

Kubeadm 集群托管

托管由 kubeadm 创建和管理的 kubernetes 集群，kubeclipper 会通过 kubeconfig 文件，获取集群和节点信息，并导入到 kubeclipper 平台中。

点击“集群管理”>“集群托管”按钮进入集群托管页面，点击左上角“添加”按钮，在添加提供商弹窗中，填写提供商名称（如 kubeadm-demo）和描述后，填写以下信息：

区域：提供商下的集群和节点在 kubeclipper 平台中的所属区域。
提供商类型：选择 kubeadm。
节点连接方式：集群节点的连接方式，可以选择“私钥”或者“密码”，您需要确保可以通过所选方式 ssh 到集群节点。
- 选择“私钥”，需要输入节点用户名和私钥信息。
- 选择“密码”，需要输入节点用户名和密码信息。
集群名称：作为在本平台的展示名称，不能与其他集群重复。
KubeConfig：托管集群的 KubeConfig 文件。

填写完成后点击“确定”按钮，将集群和节点导入到平台中。点击提供商名称（kubeadm-demo），进入提供商详情页，您可以查看提供商下的集群，并对提供商执行以下操作：

同步：系统将每隔4小时定期同步集群信息，您也可以点击“同步”按钮手动执行。
编辑：编辑提供商的名称、描述、访问信息、节点连接方式。
移除：解除平台对该集群的管理，保留 Kubernetes 集群本体。清理还会移除导入时安装的 kc-agent，以及平台创建的 ServiceAccount、ClusterRoleBinding 和 kubectl 终端服务；原本已纳管的节点有不同的保留逻辑。移除前核对节点归属并保存 kubeconfig。

托管集群管理

您可以点击“集群管理”>“集群”进入集群列表页面，查看包括托管集群和本地集群在内的所有集群列表，对于不同集群，支持的管理操作如下表所示：

插件和外接存储的镜像来源以所选组件包及其配置为准。离线环境须提前准备镜像，并确认各节点能够从配置的仓库拉取；需要认证或自签名证书时，先配置 CRI 镜像仓库。

功能	Kubeclipper 创建的集群	托管的 kubeadm 集群
查看日志	✔︎	✔︎
任务失败后重试	✔︎	✔︎
访问 kubectl	✔︎	✔︎
编辑	✔︎	✔︎
保存为模版	✔︎	✘
CRI 镜像仓库配置	✔︎	✔︎
添加/移除集群节点	✔︎	✔︎
备份和恢复管理	✔︎	✔︎
版本升级	✔︎	✘
删除集群	✔︎	✘
移除集群（提供商）	/	✔︎
重置状态	✔︎	✔︎
集群插件管理	✔︎	✔︎
更新集群证书	✔︎	✔︎
查看 kubeconfig	✔︎	✔︎

Docs: 离线创建集群

Mon, 01 Jan 0001 00:00:00 +0000

离线安装需要先准备平台部署包，以及 Kubernetes、CRI、CNI 等组件资源。Registry 资源只描述镜像仓库，不能替代离线包。

检查资源

完成平台部署后登录并检查：

kcctl resource list
kcctl get node

确认目标节点架构与资源包一致。1.7 推荐矩阵为 Kubernetes v1.37.0 / v1.36.4 / v1.35.8、containerd 2.2.4、Calico v3.31.5。需要补充组件包时参考准备离线组件包。

创建集群

kcctl create cluster 默认离线安装。示例使用一个实验节点：

kcctl create cluster --name offline-demo --master 192.168.10.21 --untaint-master \
 --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
 --cni calico --cni-version v3.31.5
kcctl operation list -c offline-demo
kcctl get cluster offline-demo -o yaml

在 Console 创建时同样选择已准备好的组件版本、目标节点和离线方式。需要镜像仓库时先准备镜像并配置Registry 资源。存储插件按实际需求单独选择，不把某一种 NFS 插件当作创建集群的必选步骤。

确认安装结果

结合 Operation 和节点日志定位失败原因。取得 kubeconfig 后检查节点 Ready、系统 Pod 和 API readiness。离线资源缺失、架构不一致或镜像地址不可达时，先修正资源再重试，参见操作与日志。

Docs: 集群管理

Mon, 01 Jan 0001 00:00:00 +0000

KubeClipper 1.7 的集群生命周期操作由 Operation v2 执行。先查看集群对象，再用操作详情和节点实际状态确认结果。

kcctl get cluster
kcctl get cluster demo -o yaml
kcctl operation list -c demo

日志、重试和取消

完整命令见操作与日志。失败后先处理根因再重试；重置集群状态不会修复失败的节点或撤销已执行操作。

访问集群

在 Console 的集群详情页获取 kubeconfig，设置 KUBECONFIG 后执行：

kubectl get nodes -o wide
kubectl get pods -A
kubectl get --raw='/readyz?verbose'

平台状态正常不代表所有受管集群都正常。升级、扩缩容、备份和恢复后，都要检查对应集群中的节点、系统 Pod 和业务数据。

扩缩容与镜像仓库

先用 kcctl join 将新增机器纳入平台，确认节点就绪、区域与目标集群一致，再在集群详情中添加节点。移除节点前迁移工作负载并检查容量；平台的 kcctl drain 用于移除平台 Agent，不等同于集群缩容。节点接入步骤见节点管理。

Kubernetes 镜像仓库与 containerd 拉取仓库分别配置，具体步骤见镜像仓库。变更后检查实际镜像拉取结果。

备份与恢复

配置备份空间，并在编辑集群时关联该备份空间。使用目录备份空间时，先在相关节点创建并挂载约定路径，确认可写。
在集群中发起备份，或通过定时备份设置执行时间和保留数量；确认备份记录成功且文件可读取。
恢复时选择该集群的备份记录，跟踪恢复 Operation，完成后检查 API、节点、系统 Pod 和业务状态。

这里的集群备份以 Kubernetes etcd 快照为核心，不包含业务持久卷中的文件；应用数据需要另行备份。恢复会改变集群状态，先在隔离环境演练，不能仅凭备份记录存在判断可恢复。

Kubernetes 版本升级

这与 KubeClipper 平台升级是两项操作。先备份并验证恢复方案，检查目标版本的组件资源、镜像和工作负载兼容性，再从集群的升级入口选择目标版本。托管的 kubeadm 集群不提供此升级入口。

CLI 参数可用下列命令查看：

kcctl cluster upgrade --help

升级命令使用 --cluster-name 和 --version 指定集群与目标版本，默认采用离线方式；--online 改为在线方式，--image-registry 选择已配置的 Registry 资源。目标版本必须在平台可用资源中，不能将支持矩阵当作任意版本间升级成功的保证。提交后跟踪 Operation，并执行上面的集群健康检查。

删除集群

先确认工作负载和数据已备份，再发起删除并跟踪 Operation：

kcctl delete cluster demo
kcctl operation list -c demo
kcctl get cluster

确认删除结束后再复用节点。失败时保留日志和节点状态，参考平台诊断，不要用强制删除掩盖未完成的清理。

Docs: 准备离线组件包

Mon, 01 Jan 0001 00:00:00 +0000

1.7.0 的完整部署包和额外的 Kubernetes / CRI / CNI 组件包用途不同。先使用快速开始中的完整部署包部署平台，再按实际需求补充组件资源。

选择版本和架构

以 1.7 版本说明中的矩阵为准。以下示例下载 Kubernetes v1.37.0 的 amd64 组件；arm64 节点需准备 arm64 包，不要混用架构。

在联网机器下载并打包

以下命令在 Bash 中执行，使用项目 OSS 原生域名。curl -fL 会在下载失败时退出；不要忽略证书或 HTTP 错误后继续打包。

set -e
ARCH=amd64
VERSION=v1.37.0
PKG_DIR="$(mktemp -d)"
COMPONENT_DIR="k8s/${VERSION}/${ARCH}"
mkdir -p "${PKG_DIR}/${COMPONENT_DIR}"
for FILE in manifest.json configs.tar.gz images.tar.gz; do
 curl -fL -o "${PKG_DIR}/${COMPONENT_DIR}/${FILE}" \
 "https://kubeclipper.oss-ap-southeast-1.aliyuncs.com/packages/${COMPONENT_DIR}/${FILE}"
done
tar -czf "k8s-${VERSION}-${ARCH}.tar.gz" -C "$PKG_DIR" k8s
tar -tzf "k8s-${VERSION}-${ARCH}.tar.gz"

归档中需保留 k8s/版本/架构/ 层级，不能只压缩文件本身。下载目录保留在 $PKG_DIR，核对后可自行清理。

其他组件使用相同层级，按下表准备文件，再压缩对应组件目录：

组件目录	版本	必需文件	上传类型
k8s	v1.37.0	manifest.json、configs.tar.gz、images.tar.gz	k8s
containerd	2.2.4	manifest.json、configs.tar.gz	cri
calico	v3.31.5	manifest.json、images.tar.gz、charts.tgz	cni

例如 Calico 路径为 packages/calico/v3.31.5/amd64/manifest.json。这些是已有组件资源的打包方式，不代表任意自定义版本都已被平台支持。

传入离线环境并上传

把归档传到能访问平台的部署机。该机器需保留部署配置和可登录 Server 的 SSH 凭据。

kcctl resource push --pkg k8s-v1.37.0-amd64.tar.gz --type k8s
kcctl resource list

上传 containerd 和 Calico 时分别使用 --type cri、--type cni。确认平台能列出匹配的版本和架构，再按离线创建集群验证。镜像仓库的配置参见 Registry。

Docs: 节点管理

Tue, 29 Nov 2022 00:00:00 +0000

区域管理

平台支持多区域管理，即为平台管理的所有节点和集群进行物理或逻辑的区域划分。您可以在“区域管理”页面查看平台内管理的所有区域，点击区域名称，进入区域详情页面，可以查看区域下的所有集群列表和节点列表。

节点管理

您可以在“节点信息”页面查看平台中管理的全部节点列表，和节点规格、状态等信息。点击节点名称进入节点详情页面，可以查看详细的节点基本信息和系统信息。

KubeClipper 中的节点状态表示 kc-agent 对节点的管理状态。正常情况下，节点状态显示为“就绪”，默认节点健康监控宽限期为 4 分钟，每 10 秒检查一次；超过宽限期后，状态会更新为“未知”，实际显示时间还会受到调度和通信延迟影响。此时先排查 Agent、网络和 Server 连通性，恢复就绪后再安排新的集群部署或扩容。

添加节点

在部署 KubeClipper 时，您就可以添加初始的 server 节点和 agent 节点，其中，server 节点用于部署 KubeClipper 自身服务，agent 节点可用于部署 kubernetes 集群。在用于实验或开发的 KubeClipper 环境，您可以将 server 节点同时添加为 agent 节点。但如果用于生产环境，建议不要将 server 节点复用为 agent 节点。

您也可以使用 kcctl join 命令为 KubeClipper 添加 agent 节点。同时，您可以为每个 agent 节点标记一个区域，区域可以是物理的或逻辑的位置，您可以使用同一区域的节点创建 kubernetes 集群，但不可以使用跨区域的节点创建集群。未标记区域的节点默认属于 default 区域。

命令行示例：

kcctl join --agent beijing:1.2.3.4 --agent shanghai:2.3.4.5

移除节点

当您不再需要某些节点，可以使用 kcctl drain 命令将节点从平台中移除。

命令行示例：

kcctl drain --agent 192.168.10.19

连接终端

在节点列表页面，您可以点击目标节点右侧的“连接终端”按钮，在连接终端的弹窗中输入节点端口和用户名密码信息后，访问节点 SSH 控制台并执行命令。

启用/禁用节点

您可以点击节点右侧“禁用”按钮暂时禁用节点，禁用状态下的节点不允许创建或添加到集群。

Docs: 访问控制

Tue, 29 Nov 2022 00:00:00 +0000

用户管理

安装 KubeClipper 之后，您需要创建所需角色的用户。一开始，系统默认只有一个用户 admin，具有平台管理员角色。

点击“访问控制”>“用户”，进入用户管理页面，点击左上角“创建用户”按钮，在弹窗中填写用户名、密码、手机号码、邮箱等信息，并指定用户角色，点击“确认”按钮。系统内置四个角色如下：

平台管理员：拥有集群管理、用户管理、审计管理等全部平台查看和操作权限。
集群管理员：拥有所有集群管理权限。
用户管理员：拥有所有用户管理权限。
平台只读用户：拥有全部平台查看权限。

用户创建完成后，您可以在用户详情页面查看用户详情信息，并执行以下操作：

编辑：编辑用户别名、角色、手机号、邮箱信息。
编辑密码：编辑用户登录密码。
删除：删除用户。

在用户详情页面，您还可以查看当前用户的登录日志列表。

您可以编辑平台 /etc/kubeclipper-server/kubeclipper-server.yaml 文件，根据需要设置用户登录日志的最大保留条数和保留期限，清理逻辑仅在该用户的日志总数超过最大条数时触发：先删除超额的旧记录，再清理剩余的过期记录；未超过最大条数时，不会仅因过期而删除。

自定义角色

除了系统内置角色，您也可以创建自定义角色，以满足业务需要。

点击“访问控制”>“角色”，进入角色管理页面，您可以点击左上角“创建角色”按钮，创建自定义角色。

在创建角色页面，您需要填写角色名称和描述，并勾选自定义角色所需权限，一些权限依赖于其他权限，在选择这些权限时，将自动选中依赖的权限。

创建自定义角色完成后，您可以在角色详情页面查看角色基本信息、角色权限列表、授权用户列表，并对自定义角色执行以下操作：

编辑：编辑自定义角色描述。
编辑权限：编辑自定义角色下的权限。
删除：删除自定义角色，需确保没有用户使用待删除角色。

接入外部用户

KubeClipper 可以通过 OIDC 协议使用外部用户登录。

首先，平台管理员需要登录平台 server 节点，在 kubeclipper-server.yaml 文件中的 authentication 下插入以下信息：

oauthOptions:
 identityProviders:
 - name: keycloak
 type: OIDC
 mappingMethod: auto
 provider:
 clientID: kc
 clientSecret: REPLACE_WITH_CLIENT_SECRET
 issuer: https://idp.example.com/realms/kubeclipper
 scopes:
 - openid
 - email
 redirectURL: https://console.example.com/oauth2/redirect/keycloak

这是 authentication 下的配置片段，需合并到现有配置。将示例域名和 REPLACE_WITH_CLIENT_SECRET 替换为实际值；IdP 注册的回调地址必须与 redirectURL 完全一致，路径末尾的 keycloak 与提供商 name 一致。各 Server 更新配置后，按节点滚动重启 kc-server。

其中，“provider” 下需要您填写自己的 OAuth2 服务的clientID、clientSecret、issuer信息，以 keycloak 为例，如下图所示。

redirectURL示例：https://console.example.com/oauth2/redirect/keycloak

OAuth2 用户可以通过以下步骤访问和使用 KubeClipper 平台：

点击登录页的 “OAuth2 登录”按钮，进入 OAuth2 登录页面，输入用户名密码登录，进入 KubeClipper 平台，首次登录，您会因未被授予权限而无法访问平台。
平台管理员或其他拥有用户管理权限的用户登录 KubeClipper，在用户管理页面，找到目标 OAuth2 用户，通过编辑用户指定用户角色。
OAuth2 用户重复第一步，登录 KubeClipper，就可以正常访问平台并执行角色权限内操作。

Docs: 操作与日志

Mon, 01 Jan 0001 00:00:00 +0000

KubeClipper 1.7 将安装、升级、备份、删除等工作建模为 Operation，并按步骤和节点执行 Task。提交命令成功只表示请求已被接受，最终结果需要继续查询。

查找操作

kcctl operation list
kcctl operation list -c demo

从列表复制实际操作 ID 后查看详情和日志：

OPERATION_ID='<实际操作 ID>'
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow

通过日志定位失败步骤和节点。在交互式终端中，可按集群打开 TUI 日志视图：

kcctl operation logs --cluster demo

脚本和非交互终端使用带操作 ID 的纯文本日志命令。

处理失败

先保留操作详情、失败节点日志和集群状态，处理包缺失、镜像下载、节点网络或服务异常等原因，再重试：

kcctl operation retry "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"
kcctl operation logs "$OPERATION_ID" --follow

重试后再次检查实际集群和节点，不能只看 retry 命令返回值。若参数本身错误，先核对任务配置，不要用反复重试代替修正。

取消操作

kcctl operation cancel "$OPERATION_ID"
kcctl operation describe "$OPERATION_ID"

取消不等于回滚已经执行的安装或数据操作。继续确认任务是否停止，以及节点上已经产生的变更；清理前先确定资源归属。

确认成功

结合 Operation 结果、kcctl get cluster demo -o yaml、Kubernetes 节点与 Pod 状态确认结果。集群删除后还要检查平台列表和节点残留。平台问题参考诊断指南。

Docs: 平台诊断

Mon, 01 Jan 0001 00:00:00 +0000

先确定故障发生在平台、Agent、资源下载还是 Kubernetes 集群，再针对对应层排查。

现象	先检查
控制台打不开或 API 连接失败	平台状态，确认控制台与 API 使用了正确地址和端口
Agent 或节点未就绪	节点服务，检查对应节点的服务日志和连通性
安装预检查失败或资源包下载失败	部署失败，按报错中的节点和检查项处理
创建集群的任务失败	集群任务失败，先找到 Operation 和失败步骤

平台状态

kcctl version
kcctl status
kcctl status -o json
kcctl doctor

status 汇总 kc-server、kc-etcd 和 kc-agent 的健康状态。doctor 检查本地访问、服务、平台 etcd 和 Agent，并输出失败证据。非健康结果会返回非零退出码，适合用于检查脚本；两个命令都不会自动修复环境。

若平台 API 无法访问，检查 kcctl login 使用的地址是否为 HTTPS API 入口，默认端口 8080。检查本地登录和部署配置，以及部署机到各节点的 SSH 连通性。

节点服务

在对应的 Linux 节点执行：

sudo systemctl status kc-server kc-etcd kc-agent --no-pager
sudo journalctl -u kc-server -n 100 --no-pager
sudo journalctl -u kc-agent -n 100 --no-pager

只部署 Agent 的节点不应要求存在 Server 或平台 etcd 服务。结合实际节点角色解读结果，并检查磁盘、时间同步、管理地址和防火墙。

部署失败

预检查错误会指出检查项和节点。若服务已存在，先确认该节点是否属于正在使用的平台；不要删除服务来绕过检查。下载错误应核对地址、证书、文件大小和包内容，不能用关闭证书校验掩盖错误。

集群任务失败

kcctl operation list -c demo
kcctl get cluster demo -o yaml
kcctl get node
kcctl resource list

通过操作与日志定位具体步骤和节点。离线安装核对版本、架构和资源包；镜像拉取失败核对镜像仓库地址、认证和网络。提交 Issue 时提供版本、拓扑、脱敏后的错误和操作 ID，移除密码、token、私钥与 kubeconfig 凭据。

Docs: 镜像仓库

Mon, 01 Jan 0001 00:00:00 +0000

Registry 资源用于描述 Kubernetes 镜像仓库或给 containerd 添加镜像拉取配置。它与平台离线资源包不是同一种对象，创建 Registry 也不会自动把镜像同步到仓库。

创建 Registry 资源

以下是管理网络中 HTTP 镜像仓库的例子。生产仓库应按实际情况配置 HTTPS、CA 和认证；完整参数见命令帮助。

kcctl create registry --name internal --host registry.example.com:5000 --scheme http
kcctl get registry
kcctl create registry -h

需要认证时可通过 --auth-username 和 --auth-password 配置，注意命令历史和终端日志中的凭据暴露。使用 HTTPS 时核对 --ca 与 --skip-tls-verify，不要直接沿用 HTTP 示例配置。

为集群选择仓库

kcctl create cluster --name demo --master 192.168.10.21 \
 --k8s-version v1.37.0 --cri containerd --cri-version 2.2.4 \
 --cni calico --cni-version v3.31.5 \
 --image-registry internal --cri-registry internal

--image-registry 选择用于 Kubernetes 镜像的 Registry 资源。
--cri-registry 将 Registry 资源的配置加入 containerd；可按需要指定多个资源。
未指定镜像仓库时，各组件采用各自的默认值和适用的 Agent 镜像源配置。不要假定 Kubernetes、Calico 等组件都从同一个默认仓库拉取。

创建前把所需镜像放入仓库，并检查集群节点实际可访问的镜像路径、认证和证书。离线安装还要满足资源包要求。