# KubeClipper 1.7.0 发布：Operation 优化与 Kubernetes 1.37 支持


![kubeclipper-release-1.7.0.jpg](https://img.lixueduan.com/kubernetes/cover/kubeclipper-release-1.7.0.jpg)

KubeClipper 1.7.0 发布了。

本次版本新增 API 驱动的 Operation v2，移除了旧的 NATS Operation 投递链路，集群创建、扩容、删除等操作统一使用新的 Operation v2。新增 `kcctl status` 和 `kcctl doctor` 平台诊断命令，新增了对 Kubernetes 1.37 版本的支持，并对镜像仓库管理、离线镜像加载和部署预检查进行了优化。

<!--more-->

KubeClipper 是一个轻量便捷的 Kubernetes 多集群全生命周期管理工具，旨在提供易使用、易运维、极轻量、生产级的 Kubernetes 多集群管理服务，让运维工程师从繁复的配置和晦涩的命令行中解放出来，实现一站式管理跨区域、跨基础设施的多 K8S 集群。

## 🚀 5分钟快速体验

第一次用 KubeClipper，可以先按下面这几步走一遍：

1. **安装工具**：`curl -sfLk https://oss.kubeclipper.io/get-kubeclipper.sh | bash -`
2. **部署服务**：`kcctl deploy`
3. **创建集群**：`kcctl create cluster --name demo --master YOUR_IP --untaint-master`
4. **打开控制台**：访问 `http://YOUR_IP`，默认账号 `admin/Thinkbig1`

四步，从零开始创建一个 Kubernetes 集群。部署完成后，还可以使用 `kcctl status` 和 `kcctl doctor` 检查平台状态。

## 1. KubeClipper 1.7.0 新特性详解

1.7.0 的主要变化集中在以下几个方面：Operation v2、平台诊断、镜像仓库管理和部署稳定性。

**本次更新的主要亮点：**

- 🆕 **Operation v2**：使用 API 和 etcd 管理集群操作，支持任务状态查询、重试、取消和重启恢复
- 🩺 **平台诊断命令**：新增 `kcctl status` 和 `kcctl doctor`
- 🔄 **Kubernetes 1.37 支持**：默认版本升级至 v1.37.0
- 📦 **Registry 与离线镜像**：支持选择 Registry 资源，离线模式支持加载节点本地镜像
- 🔧 **稳定性提升**：增加部署预检查，修复传输校验、操作清理和 Agent 运行等问题

### 1.1 Kubernetes 1.37 与组件升级

1.7.0 支持的版本如下：

| Kubernetes | Calico | Containerd |
|------------|--------|------------|
| v1.37.0（默认） | v3.31.5 | v2.2.4 |
| v1.36.4 | v3.31.5 | v2.2.4 |
| v1.35.8 | v3.31.5 | v2.2.4 |

1.6.0 的默认 Kubernetes 版本为 v1.36.1，1.7.0 已升级至 v1.37.0，v1.35 和 v1.36 也同步更新到最新维护版本。Calico 和 Containerd 继续使用 v3.31.5 和 v2.2.4。

### 1.2 Operation v2，集群操作更加可靠

1.7.0 新增 API 驱动的 Operation v2，Operation 和 OperationTask 作为 API 资源保存到 etcd，支持查看任务状态、重试、取消、超时处理和重启恢复，集群创建、扩缩容、删除、备份恢复等操作都统一使用这套机制。

同时修复了 Operation 状态持久化、集群状态并发更新冲突、操作历史清理和删除校验 panic 等问题，并优化了关键状态读取和事件分发效率。

### 1.3 `kcctl status` 和 `kcctl doctor`

1.7.0 新增了平台状态查看和诊断命令：

```bash
kcctl status
kcctl doctor
```

`kcctl status` 用于查看 `kc-server`、`kc-etcd` 和 `kc-agent` 的整体健康状态；`kcctl doctor` 用于进一步检查平台配置和服务状态，在异常时给出排查信息。`doctor` 只做诊断，不会自动修改或重启服务。

### 1.4 Registry 管理与离线镜像支持

1.7.0 将 `Cluster.imageRegistry` 调整为引用已配置的 Registry 资源，创建或升级集群时直接传入资源名称即可。KubeClipper 会自动读取 Registry 的地址、协议、认证和证书配置，并用于 Kubernetes、Containerd、Calico 等组件的镜像。

旧的 image repository/local registry 字段和 CLI 别名已移除。同时修复了 HTTP Registry 协议丢失的问题，离线模式且未指定 Registry 时，会直接加载离线安装包中随包分发到节点的镜像；在线模式未指定 Registry 时，各组件继续使用自己的默认镜像仓库。

### 1.5 部署与运行稳定性提升

这一版包含多项部署和运行稳定性修复：
- **部署预检查**：新增服务端口占用检查，预检查异常会明确显示节点 IP 和角色；部署 kc-server 前会等待 etcd Endpoint 通过健康检查。
- **部署配置**：支持通过 `--temp-dir` 指定安装包暂存目录
- **运行稳定性**：修复操作历史清理、Agent 命令输出缓冲、子进程管道阻塞和 watch 事件恢复等问题

## 2. 安装部署 KubeClipper 1.7.0

### 2.1 环境要求

- **CPU**：2 核及以上
- **内存**：4GB 及以上
- **操作系统**：推荐 Ubuntu 22.04 / Ubuntu 24.04
- **网络**：节点间网络互通，并可通过 SSH 连接
- **基础工具**：`sudo` / `curl` / `wget` / `tar`
- **架构**：amd64 / arm64

主机最好保持相对干净，避免已有容器运行时或系统配置与安装过程产生冲突。

### 2.2 安装 kcctl 工具

```bash
# 下载最新版本的 kcctl
curl -sfLk https://oss.kubeclipper.io/get-kubeclipper.sh | bash -

# 验证安装
kcctl version
```

如果需要安装指定版本，可以通过 `KC_VERSION` 指定：

```bash
curl -sfLk https://oss.kubeclipper.io/get-kubeclipper.sh | \
  KC_VERSION=v1.7.0 bash -
```

### 2.3 部署 KubeClipper

```bash
# 对于 AIO 环境使用 kcctl deploy 即可完成部署
kcctl deploy

# 更多参数参考 kcctl deploy -h
# kcctl deploy --server $IPADDR_SERVER --agent $IPADDR_AGENT \
#   --pk-file /root/.ssh/id_rsa --pkg $PKG \
#   --ip-detect=interface=ens3 --temp-dir /data/kc-tmp --v 5
```

看到下面的 banner 就说明部署完成了：

```
 _   __      _          _____ _ _
| | / /     | |        /  __ \ (_)
| |/ / _   _| |__   ___| /  \/ |_ _ __  _ __   ___ _ __
|    \| | | | '_ \ / _ \ |   | | | '_ \| '_ \ / _ \ '__|
| |\  \ |_| | |_) |  __/ \__/\ | |_) | |_) |  __/ |
\_| \_/\__,_|_.__/ \___|\____/_|_| .__/| .__/ \___|_|
                                 | |   | |
                                 |_|   |_|
```

> 安装过程中需要下载离线安装包，具体耗时取决于网络速度。

### 2.4 访问 Web UI

安装完成后，打开浏览器，访问 `http://$IP` 即可进入 KubeClipper 控制台。

![kc-console-login.jpg](https://img.lixueduan.com/kubernetes/kubeclipper/kc-console-login.jpg)

您可以使用默认帐号密码 `admin / Thinkbig1` 进行登录。

## 3. 快速上手体验

### 3.1 创建 K8s 集群

部署成功后可以使用 **kcctl 工具**或者通过**控制台**创建 K8s 集群，这里使用 kcctl 工具进行创建。

查看当前 Agent 节点：

```bash
kcctl get node
```

创建集群：

```bash
kcctl create cluster --name demo --master YOUR_IP --untaint-master
```

1.7.0 默认使用 Kubernetes v1.37.0、Calico v3.31.5 和 Containerd v2.2.4。创建过程中可以查看实时操作：

```bash
kcctl operation list -c demo
kcctl operation logs -c demo
```

如果操作失败，可以查看详情、重试或取消：

```bash
kcctl operation describe <OPERATION_ID>
kcctl operation retry <OPERATION_ID>
kcctl operation cancel <OPERATION_ID>
```

集群进入 Running 状态后，用 `kubectl` 查看集群健康状况：

```bash
kubectl get node -owide
kubectl get pods -A
```

几条命令，一个单节点 K8s 集群就创建完成了。

### 3.2 平台状态检查

部署和集群创建完成后，可以使用下面的命令检查 KubeClipper 平台状态：

```bash
kcctl status
kcctl doctor
```

`kcctl status` 用于查看平台整体健康状态，`kcctl doctor` 用于进一步定位配置、服务和节点问题。

### 3.3 KubeClipper 的工作负载管理功能

KubeClipper 的工作负载管理功能在 1.7.0 中仍然可以直接通过 Web UI 管理 Deployment、StatefulSet 等 Kubernetes 工作负载。

![kc-console-workload3.png](https://img.lixueduan.com/kubernetes/kubeclipper/kc-console-workload3.png)

## 4. 小结

这一版主要干了三件事：升级集群操作机制、补充平台诊断命令、优化镜像和部署流程。

**组件升级：**

- ✅ **Kubernetes 1.37**: 支持 v1.37.0、v1.36.4 和 v1.35.8
- ✅ **Containerd v2.2.4**: 延续 1.6.0 的默认版本
- ✅ **Calico v3.31.5**: 延续 1.6.0 的默认版本

**操作与诊断：**

- ✅ **Operation v2**: 使用 API 和 etcd 管理集群操作
- ✅ **kcctl status**: 查看平台整体健康状态
- ✅ **kcctl doctor**: 提供平台故障诊断信息

**稳定性提升：**

- ✅ **Registry 管理**: 使用 Registry 资源配置集群镜像仓库
- ✅ **离线镜像**: 离线模式未指定 Registry 时支持加载离线安装包中的本地镜像
- ✅ **部署优化**: 增加端口预检查和 etcd 健康检查，完善节点错误信息和传输失败处理
- ✅ **运行修复**: 修复操作清理、Agent Worker 和 watch 事件相关问题


---

> 作者: [意琦行](https://github.com/lixd)  
> URL: https://www.lixueduan.com/posts/kubernetes/66-kubeclipper-release-1.7.0/