# kube-sync

**Repository Path**: hexug/kube-sync

## Basic Information

- **Project Name**: kube-sync
- **Description**: kube-sync 是一个用于 同步和过滤 Kubernetes 资源 的命令行工具。
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/hexug/kube-sync
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-08
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Kubernetes, Go语言, sync

## README

# kube-sync

[![License](https://img.shields.io/badge/License-Apache_2.0-green?logo=apache&style=flat-square)](LICENSE)
[![Go Report Card](https://img.shields.io/badge/Go%20Report-A+-brightgreen?logo=go&style=flat-square)](https://goreportcard.com/report/gitee.com/hexug/kube-sync)
[![Gitee tag (latest SemVer)](https://img.shields.io/badge/dynamic/json?url=https://gitee.com/api/v5/repos/hexug/kube-sync/releases/latest&label=Version&query=$.name&color=brightgreen&logo=gitee&logoColor=ee1c25&style=flat-square)](https://gitee.com/hexug/kube-sync/releases/latest)
![Go Version](https://img.shields.io/badge/Go-1.24-blue?logo=go&style=flat-square)
![Kubernetes](https://img.shields.io/badge/Kubernetes-v1.21%2B-326CE5?logo=kubernetes&logoColor=white&style=flat-square)

`kube-sync` 是一个面向 Kubernetes 日常运维、迁移和排障场景的命令行工具。它可以把集群中的工作负载及其关联资源导出成干净的 YAML，也可以把资源克隆到另一个命名空间或另一个集群，还提供了增强版 `kubectl get` 查询能力。

简单理解：**它既是 Kubernetes 资源同步器，也是资源迁移器，还是一个更懂运维排障的查询工具。**

## 这个工具解决什么问题？

在 Kubernetes 中直接导出的资源 YAML 往往包含大量运行时字段，例如 `status`、`metadata.uid`、`resourceVersion`、`managedFields`、`clusterIP` 等。这些字段对重建资源没有帮助，甚至会导致迁移失败或 GitOps Diff 噪声很大。

`kube-sync` 的目标是：

- **导出可读、可复用的 YAML**：自动清理运行时字段，只保留真正有用的业务配置。
- **按工作负载收集关联资源**：以 Deployment、StatefulSet、DaemonSet、Job、CronJob 等工作负载为中心，自动带出关联的 Service、ConfigMap、Secret、PVC/PV、RBAC 等资源。
- **支持迁移和克隆**：可以同集群跨命名空间迁移，也可以跨集群迁移。
- **提供增强查询命令**：快速查看 Pod、节点资源、Service 端口、容器 requests/limits、工作负载关联资源、事件等信息。
- **降低命令输入成本**：提供 Bash、Zsh、Fish、PowerShell 补全，支持命名空间、资源名、标签、字段选择器等动态补全。

典型使用场景：

- 把某个命名空间的应用资源导出到 Git 仓库做备份或 GitOps 管理。
- 将一套应用从测试命名空间克隆到生产命名空间。
- 将一套业务从旧集群迁移到新集群。
- 快速排查哪些节点 CPU/内存请求率过高，哪些 Pod 使用了 GPU。
- 查询某个 Deployment 相关的 Pod、Service、Ingress、ConfigMap、Secret、PVC 等资源。
- 查询某个工作负载及其 Pod 的 Kubernetes Events，并支持 watch。

## 核心能力一览

| 能力 | 命令 | 说明 |
| --- | --- | --- |
| 同步资源到本地 YAML | `kube-sync sync` | 从集群读取工作负载及关联资源，清理字段后写入本地目录 |
| 迁移/克隆资源 | `kube-sync migrate` | 支持同集群跨命名空间、跨集群迁移，也支持只导出不部署 |
| 查询资源 | `kube-sync get` | 类似 `kubectl get`，但额外提供资源统计、关联查询、事件级联等能力 |
| Shell 补全 | `kube-sync completion` | 生成 Bash/Zsh/Fish/PowerShell 补全脚本 |
| 字段清洗规则 | `config.yaml` / 默认配置 | 通过 include/exclude 控制导出 YAML 中保留或删除的字段 |

## 项目结构

```text
kube-sync/
├── cmd/                  # CLI 命令定义
│   ├── root.go           # 根命令、全局参数、配置初始化、补全命令
│   ├── sync/             # sync 子命令
│   ├── migrate/          # migrate 子命令
│   ├── get/              # get 子命令及各种资源查询命令
│   └── completion/       # 动态补全逻辑
├── worker/               # 具体执行流程
│   ├── sync/             # 资源同步流程
│   ├── migrate/          # 资源迁移流程
│   └── get/              # 资源查询流程
├── apps/                 # 资源读取、字段清洗、文件写出等应用层能力
│   ├── resource/         # Kubernetes 资源读取与关联关系解析
│   ├── cleandata/        # include/exclude 字段清洗
│   └── tofile/           # YAML 文件写出
├── conf/                 # 配置模型、默认配置、配置注册
├── version/              # 版本信息
├── main.go               # 程序入口
├── config.yaml           # 配置文件示例
├── Makefile              # 构建脚本
└── README.md
```

## 安装

### 方式一：下载预编译二进制

推荐新手优先使用该方式。

前往 [Releases 页面](https://gitee.com/hexug/kube-sync/releases/latest) 下载对应平台的二进制文件，解压后放入 `PATH`。

安装后验证：

```bash
kube-sync -v
kube-sync -V
```

- `-v` / `--version`：输出简短版本信息。
- `-V` / `--Version`：输出完整构建信息，包括版本号、分支、Commit、构建时间、Go 版本等。

### 方式二：从源码构建

```bash
git clone https://gitee.com/hexug/kube-sync.git
cd kube-sync

go mod tidy
go build -o kube-sync .
```

使用 `Makefile` 构建：

```bash
make dep       # 整理依赖
make linux     # 构建 Linux amd64 二进制
make windows   # 构建 Windows amd64 二进制
make test      # 运行测试
make clean     # 清理构建产物
```

### 安装到系统（Linux）

```bash
make install-linux
# 或等价的别名
make install
```

该命令会：

1. 编译 Linux amd64 二进制。
2. 将二进制复制到 `/usr/bin/kube-sync` 并赋予可执行权限。
3. 若 `/etc/bash_completion.d` 目录存在，自动写入 Bash 补全脚本并提示重新加载；否则跳过补全安装。

### 安装到系统（Windows）

> 需要在 Git Bash / MSYS2 环境下执行 `make`，PowerShell 相关步骤会自动调用。

```bash
make install-windows
```

该命令会：

1. 编译 Windows amd64 二进制（`.exe`）。
2. 将二进制复制到 `C:\Go\bin\kube-sync.exe`（确保该目录已加入 `PATH`）。
3. 生成 PowerShell 补全脚本到 `C:\Go\bin\completion\kube-sync.ps1`。
4. 调用 `scripts/inject-completion.ps1`，幂等地将补全脚本的 dot-source 行注入 `$PROFILE`：
   - 若 `$PROFILE` 不存在，自动创建（含父目录）。
   - 若已包含相同引用行，跳过，不重复注入。

安装完成后，重新打开 PowerShell 或执行 `. $PROFILE` 即可启用补全。

### 管理 PowerShell 补全脚本

`scripts/clean-pwsh-profile.ps1` 是一个通用的补全脚本管理工具，适合以下场景：

- 首次配置：为多个 CLI 工具（`kubectl`、`kube-sync` 等）批量生成补全脚本并注入 `$PROFILE`。
- 补全脚本更新：工具升级后重新生成最新的补全脚本。
- `$PROFILE` 不存在时自动创建。

通过 Makefile 调用（使用默认工具列表 `kubectl`、`kube-sync`）：

```bash
make clean-pwsh-profile
```

直接调用 PowerShell 脚本：

```powershell
# 预览将要执行的操作（不做任何修改）
powershell -ExecutionPolicy Bypass -File scripts/clean-pwsh-profile.ps1 -DryRun

# 正式执行（默认处理 kubectl 和 kube-sync）
powershell -ExecutionPolicy Bypass -File scripts/clean-pwsh-profile.ps1

# 指定工具列表和补全脚本目录
powershell -ExecutionPolicy Bypass -File scripts/clean-pwsh-profile.ps1 `
    -Tools @('kubectl','kube-sync') `
    -CompletionDir 'D:\bin\completion'
```

脚本参数说明：

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `-CompletionDir` | `string` | `C:\Go\bin\completion` | 补全脚本存放目录 |
| `-Tools` | `string[]` | `@('kubectl','kube-sync')` | 要处理的工具列表，PATH 中找不到的工具自动跳过 |
| `-DryRun` | `switch` | 关闭 | 仅预览，不修改任何文件 |

执行逻辑：

1. 确保 `$PROFILE` 存在（不存在则自动创建）。
2. 确保 `CompletionDir` 目录存在。
3. 对每个在 PATH 中找到的工具，运行 `<tool> completion powershell` 生成/更新补全脚本。
4. 幂等地将 `. '<CompletionDir>\<tool>.ps1'` 注入 `$PROFILE`（已存在则跳过）。

## 使用前准备

`kube-sync` 需要访问 Kubernetes API Server，因此你需要满足以下任一条件：

- 本机默认 kubeconfig 可用，例如 `~/.kube/config`。
- 使用命令参数显式指定 kubeconfig。
- 在集群内运行时可通过 ServiceAccount 访问集群。

常用 kubeconfig 参数：

| 命令 | 参数 | 说明 |
| --- | --- | --- |
| `sync` | `-k, --kube-config` | 指定要同步的源集群 kubeconfig |
| `migrate` | `--src.kc` | 指定源集群 kubeconfig |
| `migrate` | `--dst.kc` | 指定目标集群 kubeconfig |
| `get` | `-k, --kube-config` | 指定查询使用的 kubeconfig |

如果不指定 kubeconfig，程序会尝试使用默认 Kubernetes 客户端配置。

## 快速开始

### 1. 同步一个命名空间的应用资源

```bash
kube-sync sync -n prod -o ./backup -f config.yaml
```

执行后会在 `./backup` 下生成类似目录：

```text
backup/
└── prod/
    └── Deployment-api/
        ├── api.yaml              # 工作负载 + Service，多文档 YAML
        ├── configmap-app.yaml    # 关联 ConfigMap
        ├── secret.yaml           # 关联 Secret
        ├── rbac.yaml             # 关联 RBAC
        └── pv-pvc.yaml           # 关联 PV/PVC
```

输出文件会按工作负载分组，便于阅读、提交 Git 或后续部署。

### 2. 只同步指定工作负载

```bash
kube-sync sync -n prod -i "prod:Deployment:api" -o ./backup
```

`-i` / `--includes` 的格式是：

```text
<namespace>:<KIND>:<name>
```

例如：

- `prod:Deployment:api`：只同步 `prod` 命名空间下名为 `api` 的 Deployment。
- `prod:StatefulSet:mysql`：只同步 `prod` 命名空间下名为 `mysql` 的 StatefulSet。
- `prod:Deployment:`：同步 `prod` 命名空间下所有 Deployment。

### 3. 排除某个工作负载

```bash
kube-sync sync -n prod -e "prod:Deployment:test-api" -o ./backup
```

`-e` / `--excludes` 和 `-i` / `--includes` 互斥：

- 使用 `--includes` 表示“只要这些”。
- 使用 `--excludes` 表示“除了这些都要”。

### 4. 同集群跨命名空间迁移

```bash
kube-sync migrate --src.ns old-prod --dst.ns new-prod
```

该命令会：

1. 从 `old-prod` 读取工作负载及关联资源。
2. 清理不适合迁移的运行时字段。
3. 将资源 namespace 调整为 `new-prod`。
4. 检查/创建目标命名空间。
5. 询问确认后部署到目标命名空间。

### 5. 跨集群迁移

```bash
kube-sync migrate \
  --src.ns prod \
  --src.kc ~/.kube/source \
  --dst.kc ~/.kube/target
```

未指定 `--dst.ns` 时，会迁移到目标集群中的同名命名空间。

如果需要迁移到目标集群的不同命名空间：

```bash
kube-sync migrate \
  --src.ns prod \
  --dst.ns prod-new \
  --src.kc ~/.kube/source \
  --dst.kc ~/.kube/target
```

### 6. 只导出迁移结果，不部署

```bash
kube-sync migrate --src.ns prod --dst.ns prod-new --sync -o ./migrate-yaml
```

`--sync` 表示只生成 YAML 文件，不向目标集群创建资源。

### 7. 查询资源

```bash
kube-sync get pod -n prod
kube-sync get deploy -A
kube-sync get node-resources
kube-sync get service-ports --node-port --sort
```

`get` 的设计风格接近 `kubectl get`，但提供了更多面向排障和资源分析的子命令。

## 全局参数

以下参数对所有子命令生效：

| 参数 | 简写 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `--version` | `-v` | `false` | 输出简短版本信息并退出 |
| `--Version` | `-V` | `false` | 输出完整版本信息并退出 |
| `--debug` | `-d` | `false` | 开启 debug 日志，便于排查配置加载、资源读取等问题 |
| `--config-type` | `-t` | `default` | 配置加载方式：`default`、`file`、`env`（默认 `default`） |
| `--config-path` | `-f` | 空 | 指定配置文件路径（指定后自动切换为 `file` 模式） |

配置加载方式说明：

- `default`：使用程序内置默认字段清洗规则，适合快速试用。
- `file`：从配置文件加载规则，最常见的是 `-f config.yaml`。
- `env`：从环境变量加载配置，适合容器化或平台化集成。

示例：

```bash
# 使用默认配置
kube-sync sync -n prod -o ./backup

# 使用指定配置文件；指定 -f 后会自动切换为 file 模式
kube-sync sync -n prod -o ./backup -f config.yaml

# 显式指定配置来源
kube-sync sync -n prod -o ./backup -t file -f config.yaml

# 开启 debug 日志，排查配置加载或资源读取问题
kube-sync sync -n prod -o ./backup -d
```

## 配置文件说明

`kube-sync` 的配置核心是字段清洗规则，也就是告诉工具：**导出 YAML 时哪些字段要保留，哪些字段要删除。**

配置结构如下：

```yaml
rules:
  config:
    deployment:
      include: []
      exclude: []
    service:
      include: []
      exclude: []
```

### include 和 exclude 的含义

| 字段 | 含义 | 适用场景 |
| --- | --- | --- |
| `include` | 白名单，只保留列出的字段路径 | 希望资源导出得非常精简时使用，例如 Secret、ConfigMap、RBAC |
| `exclude` | 黑名单，删除列出的字段路径 | 希望保留主体结构，只移除运行时噪声字段时使用，例如 Deployment、Service |

如果某个资源同时配置了 `include` 和 `exclude`，通常应优先用 `include` 明确保留关键字段，避免导出多余内容。

### 字段路径写法

字段路径使用 `/` 分隔，对应 Kubernetes YAML 的层级结构：

| 字段路径 | 对应 YAML 字段 |
| --- | --- |
| `metadata/name` | `.metadata.name` |
| `metadata/labels/app` | `.metadata.labels.app` |
| `spec/template/spec/containers/terminationMessagePath` | `.spec.template.spec.containers[*].terminationMessagePath` |
| `status` | 整个 `.status` 字段 |

当路径遇到数组时，工具会对数组中的对象应用相同字段规则。例如 `containers/terminationMessagePath` 会作用于所有容器。

### 推荐配置示例

```yaml
rules:
  config:
    deployment:
      include: []
      exclude:
        - "metadata/managedFields"
        - "metadata/creationTimestamp"
        - "metadata/generation"
        - "metadata/resourceVersion"
        - "metadata/uid"
        - "spec/progressDeadlineSeconds"
        - "spec/revisionHistoryLimit"
        - "spec/strategy"
        - "spec/template/metadata/creationTimestamp"
        - "spec/template/spec/containers/terminationMessagePath"
        - "spec/template/spec/containers/terminationMessagePolicy"
        - "spec/template/spec/restartPolicy"
        - "spec/template/spec/dnsPolicy"
        - "spec/template/spec/schedulerName"
        - "status"

    service:
      include: []
      exclude:
        - "metadata/creationTimestamp"
        - "metadata/managedFields"
        - "metadata/resourceVersion"
        - "metadata/uid"
        - "status"
        - "spec/clusterIP"
        - "spec/clusterIPs"
        - "spec/internalTrafficPolicy"
        - "spec/ipFamilies"
        - "spec/ipFamilyPolicy"
        - "spec/externalTrafficPolicy"

    configmap:
      include:
        - "apiVersion"
        - "kind"
        - "metadata/name"
        - "metadata/namespace"
        - "metadata/labels"
        - "data"
      exclude: []

    secret:
      include:
        - "apiVersion"
        - "kind"
        - "metadata/name"
        - "metadata/namespace"
        - "data"
        - "type"
      exclude: []
```

### 支持配置规则的资源类型

内置配置模型支持以下资源规则：

- 工作负载：`deployment`、`daemonset`、`statefulset`、`job`、`cronjob`
- 网络与配置：`service`、`configmap`、`secret`
- RBAC：`serviceaccount`、`role`、`rolebindings`、`clusterrole`、`clusterrolebindings`
- 存储：`pv`、`pvc`
- CRD：`rayservice`

### 常见字段为什么要排除？

| 字段 | 为什么通常要排除 |
| --- | --- |
| `metadata/uid` | 每个集群自动生成，迁移时不能复用 |
| `metadata/resourceVersion` | API Server 内部版本号，不应写回 |
| `metadata/managedFields` | Server-Side Apply 管理信息，内容很大且对迁移无意义 |
| `metadata/creationTimestamp` | 创建时间由目标集群生成 |
| `status` | 运行时状态，由控制器自动维护 |
| `spec/clusterIP` / `spec/clusterIPs` | Service 的集群内 IP 通常由目标集群重新分配 |
| `spec/template/spec/containers/terminationMessagePath` | Kubernetes 默认字段，常造成无意义 Diff |

## `sync`：同步资源到本地 YAML

`sync` 适合做备份、GitOps 初始化、资源审计，也可以作为迁移前的预览步骤。

```bash
kube-sync sync [参数]
```

### `sync` 会做什么？

执行流程可以概括为：

```mermaid
flowchart LR
  A[读取命名空间或 includes 指定的工作负载] --> B[查找关联 Service]
  B --> C[查找关联 ConfigMap / Secret]
  C --> D[查找关联 RBAC / PV / PVC]
  D --> E[按 include/exclude 清洗字段]
  E --> F[写入本地 YAML 文件]
```

当前会围绕工作负载收集并输出：

- 工作负载自身：`Deployment`、`StatefulSet`、`DaemonSet`、`Job`、`CronJob` 等。
- 关联 `Service`。
- 关联 `ConfigMap`。
- 关联 `Secret`。
- 关联 `ServiceAccount`、`Role`、`RoleBinding`、`ClusterRole`、`ClusterRoleBinding`。
- 关联 `PersistentVolumeClaim` 和 `PersistentVolume`。
- 部分 CRD 资源，例如 `RayService`，取决于集群是否安装对应 CRD 以及当前客户端是否能访问。

### 参数说明

| 参数 | 简写 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `--namespaces` | `-n` | `string[]` | 空 | 指定要同步的命名空间，可重复传入 |
| `--out` | `-o` | `string` | `./` | 输出目录 |
| `--includes` | `-i` | `string[]` | 空 | 只同步指定工作负载，格式 `<namespace>:<KIND>:<name>` |
| `--excludes` | `-e` | `string[]` | 空 | 排除指定工作负载，格式 `<namespace>:<KIND>:<name>` |
| `--skip-configmap` | `-c` | `bool` | `false` | 不导出关联 ConfigMap |
| `--skip-pv-pvc` | `-p` | `bool` | `false` | 不导出关联 PV/PVC |
| `--skip-secret` | `-s` | `bool` | `false` | 不导出关联 Secret |
| `--kube-config` | `-k` | `string` | 空 | 指定 kubeconfig 文件 |

### includes / excludes 格式

格式：

```text
<namespace>:<KIND>:<name>
```

示例：

```bash
# 只同步一个 Deployment
kube-sync sync -i "prod:Deployment:api" -o ./backup

# 同步 prod 命名空间下所有 Deployment
kube-sync sync -i "prod:Deployment:" -o ./backup

# 指定 -n 后，namespace 可留空，表示在 -n 指定的命名空间中匹配
kube-sync sync -n prod -i ":Deployment:api" -o ./backup

# 排除测试服务
kube-sync sync -n prod -e "prod:Deployment:test-api" -o ./backup
```

注意：

- `--includes` 与 `--excludes` 只能二选一。
- `--includes` 的第三段名称可以为空，表示匹配该类型下所有资源。
- 如果既没有 `--namespaces`，也没有 `--includes`，命令会报错，因为工具不知道要从哪里同步。

### 常用示例

```bash
# 同步单个命名空间
kube-sync sync -n prod -o ./backup

# 同步多个命名空间
kube-sync sync -n prod -n staging -o ./backup

# 使用自定义字段清洗配置
kube-sync sync -n prod -o ./backup -f config.yaml

# 跳过 Secret，适合不希望敏感数据落盘的场景
kube-sync sync -n prod -o ./backup -s

# 跳过 ConfigMap 和 PV/PVC
kube-sync sync -n prod -o ./backup -c -p

# 使用指定 kubeconfig
kube-sync sync -n prod -k ~/.kube/source -o ./backup

# 打开 debug 日志
kube-sync sync -n prod -o ./backup -d
```

### 输出目录规则

以 `Deployment api` 为例，默认输出结构如下：

```text
<out>/<namespace>/<KIND>-<name>/
├── <name>.yaml
├── configmap-<configmap-name>.yaml
├── secret.yaml
├── rbac.yaml
└── pv-pvc.yaml
```

说明：

- `<name>.yaml` 通常包含工作负载自身和关联 Service，使用 `---` 分隔多文档。
- `configmap-*.yaml` 每个 ConfigMap 一个文件。
- `secret.yaml` 包含工作负载关联的 Secret。
- `rbac.yaml` 包含 ServiceAccount、Role、RoleBinding、ClusterRole、ClusterRoleBinding。
- `pv-pvc.yaml` 包含关联的 PV/PVC。

## `migrate`：迁移或克隆资源

`migrate` 适合将一套应用复制到另一个命名空间或另一个集群。它会复用与 `sync` 类似的资源发现和字段清洗能力，但可以进一步将资源部署到目标集群。

```bash
kube-sync migrate [参数]
```

### 迁移模式

| 场景 | 命令示例 | 行为 |
| --- | --- | --- |
| 同集群、同命名空间 | `kube-sync migrate --src.ns prod` | 不允许直接部署，会自动转为只导出文件 |
| 同集群、跨命名空间 | `kube-sync migrate --src.ns prod --dst.ns prod-new` | 迁移到同集群的新命名空间 |
| 跨集群、同名命名空间 | `kube-sync migrate --src.ns prod --dst.kc ~/.kube/target` | 迁移到目标集群的 `prod` 命名空间 |
| 跨集群、改名命名空间 | `kube-sync migrate --src.ns prod --dst.ns prod-new --dst.kc ~/.kube/target` | 迁移到目标集群的 `prod-new` 命名空间 |
| 只导出不部署 | `kube-sync migrate --src.ns prod --dst.ns prod-new --sync -o ./out` | 只生成 YAML 文件 |

### 参数说明

| 参数 | 简写 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `--src.ns` | 无 | `string[]` | 空 | 源命名空间，通常必填，可重复传入 |
| `--dst.ns` | 无 | `string[]` | 空 | 目标命名空间，可重复传入 |
| `--src.kc` | 无 | `string` | 空 | 源集群 kubeconfig |
| `--dst.kc` | 无 | `string` | 空 | 目标集群 kubeconfig；为空表示同集群迁移 |
| `--out` | `-o` | `string` | `./` | `--sync` 或取消部署后选择本地同步时的输出目录 |
| `--includes` | `-i` | `string[]` | 空 | 只迁移指定工作负载，格式 `<namespace>:<KIND>:<name>` |
| `--excludes` | `-e` | `string[]` | 空 | 排除指定工作负载，格式 `<namespace>:<KIND>:<name>` |
| `--sync` | 无 | `bool` | `false` | 只导出 YAML，不部署到目标集群 |
| `--skip-configmap` | `-c` | `bool` | `false` | 跳过 ConfigMap，可能导致工作负载无法正常启动 |
| `--skip-pv-pvc` | `-p` | `bool` | `false` | 跳过 PV/PVC |
| `--skip-secret` | `-s` | `bool` | `false` | 跳过 Secret |

### 部署确认机制

当 `migrate` 将要向目标集群部署资源时，会在终端询问确认：

```text
是否允许部署到 <cluster> 集群的 <namespace> 命名空间下？(默认允许，输入n或no表示不允许):
```

- 直接回车：允许部署。
- 输入 `n` 或 `no`：不部署。
- 不部署后，命令还会询问是否要同步到本地。

### 迁移时会自动处理什么？

- 清理运行时字段，避免把源集群的内部字段写入目标集群。
- 根据 `--dst.ns` 调整资源命名空间。
- 当目标命名空间不存在时，尝试创建命名空间。
- 按资源类型组织创建请求，包括 ConfigMap、Secret、PV/PVC、RBAC、工作负载、Service 等。

### 常用示例

```bash
# 同集群跨命名空间迁移
kube-sync migrate --src.ns prod --dst.ns prod-new

# 跨集群迁移，保持命名空间名称不变
kube-sync migrate --src.ns prod --src.kc ~/.kube/source --dst.kc ~/.kube/target

# 跨集群迁移，并修改目标命名空间
kube-sync migrate \
  --src.ns prod \
  --dst.ns prod-new \
  --src.kc ~/.kube/source \
  --dst.kc ~/.kube/target

# 只迁移一个工作负载
kube-sync migrate --src.ns prod --dst.ns prod-new -i "prod:Deployment:api"

# 排除某个工作负载
kube-sync migrate --src.ns prod --dst.ns prod-new -e "prod:Deployment:test-api"

# 只导出 YAML，不部署
kube-sync migrate --src.ns prod --dst.ns prod-new --sync -o ./migrate-yaml

# 跳过敏感 Secret
kube-sync migrate --src.ns prod --dst.ns prod-new --skip-secret
```

## `get`：增强资源查询

`get` 提供类似 `kubectl get` 的体验，同时扩展了资源统计、端口分析、关联资源查询、事件级联等能力。

```bash
kube-sync get <子命令> [NAME...] [参数]
```

`get` 自身支持：

| 参数 | 简写 | 说明 |
| --- | --- | --- |
| `--kube-config` | `-k` | 指定 kubeconfig 文件，作用于所有 `get` 子命令 |

### 通用查询参数

大多数命名空间级资源支持以下参数：

| 参数 | 简写 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `--namespace` | `-n` | `default` | 指定命名空间，可重复传入 |
| `--all-namespaces` | `-A` | `false` | 查询所有命名空间，类似 `kubectl -A` |
| `--selector` | `-l` | 空 | 标签选择器，语义与 `kubectl -l` 一致 |
| `--field-selector` | 无 | 空 | 字段选择器，语义与 `kubectl --field-selector` 一致 |
| `--output` | `-o` | 空 | 输出格式：`wide`、`json`、`yaml`、`name`、`jsonpath=<template>` |
| `--show-labels` | 无 | `false` | 显示资源标签；默认树状视图，`-o wide/json/yaml/name/jsonpath` 有不同输出形态 |

集群级资源，例如 `node`、`namespace`、`persistentvolume`、`node-resources`、`node-pods`，不使用 `-n` / `-A`，但仍支持选择器和输出格式中的一部分。

### 基础资源子命令

| 子命令 | 缩写 | 级别 | 说明 |
| --- | --- | --- | --- |
| `pod` | `po` | 命名空间 | 查询 Pod |
| `deployment` | `deploy` | 命名空间 | 查询 Deployment |
| `statefulset` | `sts` | 命名空间 | 查询 StatefulSet |
| `daemonset` | `ds` | 命名空间 | 查询 DaemonSet |
| `service` | `svc` | 命名空间 | 查询 Service |
| `configmap` | `cm` | 命名空间 | 查询 ConfigMap |
| `secret` | `sec` | 命名空间 | 查询 Secret |
| `persistentvolumeclaim` | `pvc` | 命名空间 | 查询 PVC |
| `serviceaccount` | `sa` | 命名空间 | 查询 ServiceAccount |
| `cronjob` | `cj` | 命名空间 | 查询 CronJob |
| `job` | `j` | 命名空间 | 查询 Job |
| `ingress` | `ing` | 命名空间 | 查询 Ingress |
| `namespace` | `ns` | 集群 | 查询 Namespace |
| `node` | `no` | 集群 | 查询 Node |
| `persistentvolume` | `pv` | 集群 | 查询 PV |
| `events` | `event` / `ev` | 命名空间 | 查询或监听 Kubernetes Events |

示例：

```bash
# 查询 default 命名空间 Pod
kube-sync get pod

# 查询 prod 命名空间 Pod
kube-sync get pod -n prod

# 查询多个命名空间
kube-sync get pod -n prod -n staging

# 查询所有命名空间 Deployment
kube-sync get deploy -A

# 查询指定资源
kube-sync get svc -n prod api-service

# YAML 输出
kube-sync get deploy -n prod api -o yaml

# 只输出资源名
kube-sync get pod -n prod -o name

# JSONPath 输出
kube-sync get pod -n prod -o 'jsonpath={range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}'
```

### 标签选择器

`-l` / `--selector` 与 Kubernetes 官方标签选择器一致。

| 写法 | 含义 |
| --- | --- |
| `key=value` 或 `key==value` | 标签等于某值 |
| `key!=value` | 标签不等于某值，包含没有该 key 的对象 |
| `key in (v1,v2)` | 标签值在集合中 |
| `key notin (v1,v2)` | 标签值不在集合中，包含没有该 key 的对象 |
| `key` | 存在该标签 |
| `!key` | 不存在该标签 |
| `,` | AND 关系 |

示例：

```bash
# 查询 app=api 的 Pod
kube-sync get pod -A -l app=api

# 查询 env 为 prod 或 staging，且没有 debug 标签的 Pod
kube-sync get pod -A -l 'env in (prod,staging),!debug'

# 查询有 owner 标签但 tier 不在 frontend/backend 的 Deployment
kube-sync get deploy -A -l 'owner,tier notin (frontend,backend)'
```

注意：Kubernetes 标签选择器不支持跨 key 的 OR。如果要表达 OR，需要拆成多次查询后合并。

### 字段选择器

`--field-selector` 与 Kubernetes 官方字段选择器一致，常用于按资源状态或节点过滤。

示例：

```bash
# Running Pod
kube-sync get pod -A --field-selector status.phase=Running

# 排除 Failed 和 Succeeded Pod
kube-sync get pod -A --field-selector 'status.phase!=Failed,status.phase!=Succeeded'

# 查询调度到指定节点的 Pod
kube-sync get pod -A --field-selector spec.nodeName=node-1

# 标签 + 字段组合过滤
kube-sync get pod -A -l env=prod --field-selector 'spec.nodeName=node-1,status.phase=Running'

# 查询 Node
kube-sync get node --field-selector spec.unschedulable=false
```

字段选择器只支持 `=`、`==`、`!=`，不支持集合和存在性语法。可用字段由 Kubernetes API Server 决定，不同资源类型不同。

### 资源统计类命令

| 子命令 | 缩写 | 说明 |
| --- | --- | --- |
| `deployment-resources` | `deployres` | 查询 Deployment 容器 CPU/内存/GPU requests 和 limits |
| `daemonset-resources` | `dsres` | 查询 DaemonSet 容器资源配置 |
| `statefulset-resources` | `stsres` | 查询 StatefulSet 容器资源配置 |
| `pod-resources` | `pores` | 查询 Pod 容器资源配置 |
| `cronjob-resources` | `cjres` | 查询 CronJob 容器资源配置 |
| `job-resources` | `jres` | 查询 Job 容器资源配置 |
| `node-resources` | `nores` | 查询节点容量、可分配量和已请求量 |
| `node-pods` | `nopods` | 查询节点上运行的 Pod 及其资源请求/限制 |

示例：

```bash
# 查询所有 Pod 的资源配置
kube-sync get pores -A

# 查询 Deployment 资源配置
kube-sync get deployres -n prod

# 查询节点资源使用情况
kube-sync get nores

# 按 CPU 使用量/使用率排序节点
kube-sync get nores --sort-by cpu
kube-sync get nores --sort-by cpu-usage

# 查询节点上的 Pod，按 CPU 请求量排序
kube-sync get nopods --sort-by cpu
kube-sync get nopods node-1 -o wide
```

`node-resources` 的 `--sort-by` 支持：

- `cpu`
- `memory`
- `cpu-usage`
- `memory-usage`

`node-pods` 的 `--sort-by` 支持：

- `cpu`
- `mem`
- `gpu`

### `--filter` 高级资源过滤

`*-resources` 系列命令支持 `--filter` / `-F`，用于按 CPU、内存、GPU、副本数、节点空闲资源等条件过滤。

> ⚠️ **重要：表达式中含 `>` 或 `<` 时必须用单引号包裹整个表达式！**
>
> `>` / `<` 是 shell 的重定向符号，不加引号会被 shell 截走，过滤完全失效，输出还会被悄悄写入到一个名为右值（如 `0`、`2`）的文件里。
>
> | 写法 | 结果 |
> | --- | --- |
> | `-F cpu-free>0` | ❌ shell 把 `>0` 当成重定向，过滤无效，输出被写到文件 `0` |
> | `-F 'cpu-free>0'` | ✅ 正确（**推荐**） |
> | `-F "cpu-free>0"` | ✅ 双引号也可以 |
> | `--filter='cpu-free>0'` | ✅ `=` 形式 |
>
> **建议：所有过滤表达式始终用单引号包裹，养成习惯不踩坑。**

语法：

```text
--filter '<field><op><value>'      # 整个表达式必须加引号
```

多个 `--filter` 是 AND 关系。

操作符：

| 操作符 | 含义 |
| --- | --- |
| `>` | 大于 |
| `>=` | 大于等于 |
| `<` | 小于 |
| `<=` | 小于等于 |
| `==` | 等于 |
| `!=` | 不等于 |

#### 比较基准：request 还是 limit？

对 Pod/Workload 的 CPU、内存、GPU 来说，一项资源通常同时有 request 和 limit。`kube-sync` 的默认规则是：

| 操作符 | 默认比较基准 | 直觉含义 |
| --- | --- | --- |
| `>` / `>=` | `limit` | 看上限是否超过某个值 |
| `<` / `<=` | `request` | 看申请量是否低于某个值 |
| `==` / `!=` | `limit` | 默认按 limit，但建议显式写前缀 |

你也可以显式指定：

```text
limit:<field><op><value>
request:<field><op><value>
```

示例：

```bash
# 单容器 CPU limit > 10 核
kube-sync get pores -A --filter 'cpu>10'

# 单容器 GPU limit >= 1
kube-sync get pores -A --filter 'gpu>=1'

# 内存 request < 2Gi
kube-sync get pores -A --filter 'mem<2Gi'

# 明确按 limit 判断 CPU 是否等于 2 核
kube-sync get pores -A --filter 'limit:cpu==2'

# 明确按 request 判断内存是否不等于 4Gi
kube-sync get pores -A --filter 'request:mem!=4Gi'
```

#### 支持字段

Pod / CronJob / Job：

| 字段 | 别名 | 含义 | 示例值 |
| --- | --- | --- | --- |
| `cpu` | 无 | 单容器 CPU | `100m`、`2`、`1.5` |
| `memory` | `mem` | 单容器内存 | `512Mi`、`2Gi`、`1G` |
| `gpu` | 无 | 单容器 GPU | `1` |

Deployment / DaemonSet / StatefulSet 额外支持：

| 字段 | 别名 | 含义 | 示例值 |
| --- | --- | --- | --- |
| `replicas` | `replica` | 副本数 | `3` |
| `total-cpu` | 无 | 总 CPU = 单副本 × 副本数 | `20` |
| `total-memory` | `total-mem` | 总内存 = 单副本 × 副本数 | `200Gi` |
| `total-gpu` | 无 | 总 GPU = 单副本 × 副本数 | `8` |

Node：

| 字段 | 别名 | 含义 | 是否支持百分比 |
| --- | --- | --- | --- |
| `cpu-request` | `cpu-req` | 已请求 CPU | 是 |
| `cpu-free` | 无 | 剩余 CPU | 是 |
| `memory-request` | `mem-req`、`memory-req`、`mem-request` | 已请求内存 | 是 |
| `memory-free` | `mem-free` | 剩余内存 | 是 |
| `gpu-request` | `gpu-req` | 已请求 GPU | 否 |
| `gpu-free` | 无 | 剩余 GPU | 否 |

节点维度没有 request/limit 前缀，不能写 `limit:` 或 `request:`。

#### 高级过滤示例

```bash
# 使用 GPU 的 Pod
kube-sync get pores -A --filter 'gpu>=1'

# 内存请求低于 2Gi 的 Pod
kube-sync get pores -A --filter 'request:mem<2Gi'

# 副本数 >=3 且总内存 limit >=200Gi 的 Deployment
kube-sync get deployres -A --filter 'replicas>=3' --filter 'total-mem>=200Gi'

# 单副本 GPU >=1 且总 GPU >=8 的 Deployment
kube-sync get deployres -A --filter 'gpu>=1' --filter 'total-gpu>=8'

# CPU 请求率超过 80% 的节点
kube-sync get nores --filter 'cpu-req>=80%'

# 剩余 CPU 大于 2 核且剩余内存大于 50Gi 的节点
kube-sync get nores --filter 'cpu-free>2' --filter 'mem-free>50Gi'

# 剩余 CPU 大于 0.5 核（毫核单位）
kube-sync get nores --filter 'cpu-free>500m'

# 剩余内存大于 512Mi
kube-sync get nores --filter 'mem-free>512Mi'

# 空闲 GPU >=2 的节点
kube-sync get nores --filter 'gpu-free>=2'
```

#### 取值单位速查

| 类型 | 写法示例 | 含义 |
| --- | --- | --- |
| CPU（核） | `2`、`1.5` | 2 核、1.5 核 |
| CPU（毫核） | `100m`、`500m` | 0.1 核、0.5 核 |
| 内存（二进制） | `512Mi`、`2Gi`、`1Ti` | 二进制单位（推荐） |
| 内存（十进制） | `512M`、`2G`、`1T` | 十进制单位 |
| 内存（字节） | `1073741824` | 纯字节 |
| GPU / 副本数 | `1`、`2`、`4` | 整数 |
| 百分比 | `50%`、`80%` | 仅 node-resources 的 `cpu-*` / `mem-*` 字段支持 |

### Service 端口分析

`service-ports` 用于查看 Service 端口使用情况，尤其适合排查 NodePort 冲突或盘点服务端口。

```bash
kube-sync get service-ports
kube-sync get service-ports --node-port --sort
kube-sync get service-ports --cluster-port --sort
```

参数：

| 参数 | 说明 |
| --- | --- |
| `--node-port` | 显示 NodePort 使用详情 |
| `--cluster-port` | 显示所有 Service 暴露端口详情 |
| `--sort` | 按端口号升序排序 |
| `--node-port-min` | 指定 NodePort 最小值，默认自动检测，失败则使用 `30000` |
| `--node-port-max` | 指定 NodePort 最大值，默认自动检测，失败则使用 `32767` |

### 工作负载关联资源查询

关联查询用于从一个工作负载出发，快速查看它依赖或关联的资源。

| 子命令 | 缩写 | 说明 |
| --- | --- | --- |
| `deployment-related` | `deployr` | 查询 Deployment 关联资源 |
| `daemonset-related` | `dsr` | 查询 DaemonSet 关联资源 |
| `statefulset-related` | `stsr` | 查询 StatefulSet 关联资源 |
| `service-related` | `svcr` | 查询 Service 关联 Pod |
| `rayservice-related` | `rsvcr` | 查询 RayService 关联资源 |

示例：

```bash
# 查询 Deployment 关联资源
kube-sync get deployment-related -n prod api
kube-sync get deployr -n prod api

# 查询 StatefulSet 关联资源
kube-sync get stsr -n prod mysql

# 查询 Service 关联 Pod
kube-sync get svcr -n prod api-service

# 查询 RayService 关联资源
kube-sync get rsvcr -n prod ray-api
```

### CRD 和 Ray 资源查询

通用 CRD 查询：

```bash
# 按 Kind 查询 CRD 资源
kube-sync get crd RayCluster -n prod

# 指定 group/version/resource，适合 Kind 无法自动识别或需要更精确查询时
kube-sync get crd RayCluster -n prod --group ray.io --version v1 --resource rayclusters

# 自定义列输出
kube-sync get crd RayCluster -n prod --columns 'NAME:.metadata.name,PHASE:.status.state'
```

Ray 专属命令：

```bash
# RayCluster
kube-sync get ray cluster -n prod
kube-sync get ray rcl -n prod

# RayService
kube-sync get ray service -n prod
kube-sync get rayservice -n prod
kube-sync get rsvc -n prod

# RayJob
kube-sync get ray job -n prod
kube-sync get ray rjob -n prod
```

相关别名：

- `crd`：`cr`
- `ray cluster`：`clusters`、`rcl`
- `ray service`：`services`
- `ray job`：`jobs`、`rjob`
- `rayservice`：`rayservices`、`rsvc`

### Events 事件查询

`kube-sync get events` 提供比普通 `kubectl get events` 更适合排障的能力：

- 支持 `--for <kind>/<name>` 查询某个对象相关事件。
- 对 Deployment、StatefulSet、DaemonSet、Job、CronJob、RayService、RayCluster 等工作负载默认级联查询其 Pod 事件。
- 支持按 `type`、`reason`、时间范围过滤。
- 支持 watch 实时监听。
- 支持聚合输出，减少刷屏。

基础示例：

```bash
# 查询 default 命名空间事件
kube-sync get events

# 查询所有命名空间 Warning 事件
kube-sync get events -A --type Warning

# 查询 prod 和 staging 命名空间事件
kube-sync get events -n prod -n staging
```

按对象查询：

```bash
# 查询 Deployment 及其 Pod 的事件，默认 include-pods=true
kube-sync get events --for deploy/api -n prod

# 只看 Deployment 自身事件，不级联 Pod
kube-sync get events --for deploy/api -n prod --include-pods=false

# 查询某个 Pod 的事件
kube-sync get events --for pod/api-7d9-x9k -n prod

# 查询某类对象的事件
kube-sync get events --for pod -n prod
kube-sync get events --for deploy -n prod
```

过滤事件：

```bash
# Event.type 只有 Normal / Warning
kube-sync get events --type Warning -A

# 错误原因应该用 reason 过滤
kube-sync get events --reason FailedScheduling -A
kube-sync get events --reason ErrImagePull --reason ImagePullBackOff -n prod

# 最近 30 分钟
kube-sync get events -A --since 30m

# 指定起始时间
kube-sync get events -A --since-time 2024-01-01T00:00:00Z

# 指定截止时间，仅 List 模式支持
kube-sync get events -A --until 2024-01-02T00:00:00Z

# 使用标签过滤，必须配合 --for
kube-sync get events --for deploy -n prod -l app=api
```

排序与输出：

```bash
# 默认按最近发生时间倒序
kube-sync get events -A --sort-by last

# 按首次发生时间倒序
kube-sync get events -A --sort-by first

# 按出现次数倒序
kube-sync get events -A --sort-by count

# 宽表格
kube-sync get events -A -o wide

# JSON / YAML
kube-sync get events --for deploy/api -n prod -o json
kube-sync get events --for deploy/api -n prod -o yaml

# 隐藏表头，适合脚本处理
kube-sync get events -A --no-headers
```

实时监听：

```bash
# 持续监听所有命名空间事件
kube-sync get events -A -w

# 监听某个 Deployment 及其 Pod 的事件
kube-sync get events --for deploy/api -n prod -w

# 监听 Warning 事件
kube-sync get events -A -w --type Warning

# 聚合模式，相同 kind/name/reason 的事件刷新 count，不刷屏
kube-sync get events -A -w --aggregate
```

`events` 参数速查：

| 参数 | 简写 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `--namespace` | `-n` | `default` | 命名空间，可重复指定 |
| `--all-namespaces` | `-A` | `false` | 查询所有命名空间 |
| `--for` | 无 | 空 | 按 involvedObject 过滤，格式 `<kind>` 或 `<kind>/<name>` |
| `--include-pods` | 无 | `true` | `--for` 为工作负载时自动级联 Pod 事件 |
| `--type` | 无 | 空 | 事件类型，支持 `Normal`、`Warning`，可重复指定 |
| `--reason` | 无 | 空 | 按事件 reason 过滤，可重复指定 |
| `--since` | 无 | 空 | 最近一段时间，例如 `10m`、`2h`、`1d` |
| `--since-time` | 无 | 空 | RFC3339 起始时间，与 `--since` 互斥 |
| `--until` | 无 | 空 | RFC3339 截止时间，仅 List 模式支持 |
| `--watch` | `-w` | `false` | 持续监听新事件 |
| `--aggregate` | 无 | `false` | watch 模式下聚合相同事件 |
| `--sort-by` | 无 | `last` | `last`、`first`、`count` |
| `--no-headers` | 无 | `false` | 隐藏表头 |
| `--output` | `-o` | 空 | `wide`、`json`、`yaml`、`name`、`jsonpath=<template>` |
| `--field-selector` | 无 | 空 | events 原生字段选择器 |
| `--selector` | `-l` | 空 | 标签选择器，必须配合 `--for` 使用 |

## Shell 补全

`kube-sync` 支持 Bash、Zsh、Fish、PowerShell 补全。补全内容不仅包括命令和参数，还包括动态资源，例如命名空间、Pod 名称、节点名称、标签 key/value、字段选择器、`--filter` 字段等。

### Bash

临时生效：

```bash
source <(kube-sync completion bash)
```

永久生效：

```bash
kube-sync completion bash > /etc/bash_completion.d/kube-sync
source /etc/bash_completion.d/kube-sync
```

macOS 用户通常需要先安装新版 bash-completion：

```bash
brew install bash bash-completion@2
```

### Zsh

临时生效：

```zsh
source <(kube-sync completion zsh)
```

永久生效：

```zsh
kube-sync completion zsh > "${fpath[1]}/_kube-sync"
```

如果提示 `compdef` 不存在，请在 `~/.zshrc` 中启用：

```zsh
autoload -Uz compinit
compinit
```

### Fish

```fish
kube-sync completion fish | source
```

永久生效：

```fish
kube-sync completion fish > ~/.config/fish/completions/kube-sync.fish
```

### PowerShell

临时生效：

```powershell
kube-sync completion powershell | Out-String | Invoke-Expression
```

永久生效（推荐：独立文件方式，避免污染 `$PROFILE`）：

```powershell
# 1. 生成补全脚本到独立文件
mkdir -Force C:\Go\bin\completion
kube-sync completion powershell > C:\Go\bin\completion\kube-sync.ps1

# 2. 将 dot-source 行注入 $PROFILE（幂等，重复执行不会重复添加）
powershell -ExecutionPolicy Bypass -File scripts/inject-completion.ps1 -Tool kube-sync -CompletionDir 'C:\Go\bin\completion'
```

或者直接追加到 `$PROFILE`（简单方式）：

```powershell
kube-sync completion powershell >> $PROFILE
```

如果使用 `make install-windows`，以上步骤会自动完成。

如果需要同时为 `kubectl`、`kube-sync` 等多个工具配置补全，可以使用批量管理脚本：

```powershell
# 预览
powershell -ExecutionPolicy Bypass -File scripts/clean-pwsh-profile.ps1 -DryRun

# 执行
powershell -ExecutionPolicy Bypass -File scripts/clean-pwsh-profile.ps1
```

> **注意**：Windows 上 `$PROFILE` 文件默认可能不存在，`inject-completion.ps1` 和 `clean-pwsh-profile.ps1` 均会在需要时自动创建该文件及其父目录。

### 补全示例

```bash
# 补全顶层命令
kube-sync <TAB>

# 补全参数，注意需要先输入 - 或 --
kube-sync sync -<TAB>
kube-sync get pod --<TAB>

# 补全命名空间
kube-sync get pod -n <TAB>

# 补全资源名称
kube-sync get pod -n prod <TAB>

# 补全标签选择器
kube-sync get deploy -n prod -l <TAB>

# 补全字段选择器
kube-sync get pod -A --field-selector st<TAB>

# 补全 includes/excludes 三段式参数
kube-sync sync -n prod -i "prod:"<TAB>

# 补全资源过滤字段
kube-sync get pores -A --filter <TAB>
```

Bash 补全脚本中已经针对 `:` 和 `=` 做了兼容处理，因此 `prod:Deployment:api`、`app=api`、`--flag=value` 这类输入也可以正常补全。

## 常见工作流

### 工作流一：把线上应用纳入 GitOps

```bash
# 1. 导出资源
kube-sync sync -n prod -o ./gitops/prod -f config.yaml

# 2. 检查 YAML
find ./gitops/prod -name '*.yaml' -maxdepth 4

# 3. 提交 Git
cd ./gitops
git add prod
git commit -m "backup prod workloads"
```

建议：

- 将 `Secret` 是否落盘作为安全策略单独评估。
- 对 `config.yaml` 做团队统一维护，减少每个人导出的 YAML 不一致。

### 工作流二：迁移前先预览

```bash
# 只导出，不部署
kube-sync migrate --src.ns prod --dst.ns prod-new --sync -o ./preview -f config.yaml

# 人工检查 YAML
find ./preview -name '*.yaml' -type f
```

确认无误后再执行真实迁移：

```bash
kube-sync migrate --src.ns prod --dst.ns prod-new -f config.yaml
```

### 工作流三：排查资源水位

```bash
# 找出 CPU 请求率超过 80% 的节点
kube-sync get nores --filter 'cpu-req>=80%'

# 找出仍有至少 2 张 GPU 空闲的节点
kube-sync get nores --filter 'gpu-free>=2'

# 找出总 GPU 使用较高的 Deployment
kube-sync get deployres -A --filter 'total-gpu>=8'
```

### 工作流四：排查应用事件

```bash
# 查看 Deployment 及其 Pod 事件
kube-sync get events --for deploy/api -n prod

# 只看 Warning
kube-sync get events --for deploy/api -n prod --type Warning

# 实时观察滚动发布事件
kube-sync get events --for deploy/api -n prod -w --aggregate
```

## 注意事项

- **权限要求**：工具需要读取工作负载及关联资源。迁移部署还需要在目标集群创建 Namespace、ConfigMap、Secret、PV/PVC、RBAC、工作负载、Service 等资源的权限。
- **Secret 安全**：默认会导出关联 Secret。如果不希望敏感数据落盘，请使用 `--skip-secret`。
- **PV/PVC 迁移需谨慎**：PV 通常与底层存储强绑定，跨集群迁移前请确认 StorageClass、CSI、访问模式和数据迁移方案。
- **Service ClusterIP 会被清理**：这是为了让目标集群重新分配合法 IP，避免写入源集群 IP 导致创建失败。
- **同集群同命名空间不会直接部署**：这是为了避免把资源覆盖到原位置；该场景会转为本地导出。
- **`--includes` 与 `--excludes` 不要同时使用**：二者语义相反，同时使用会造成难以理解的选择结果。
- **Shell 特殊字符要加引号**：标签选择器、字段选择器和 `--filter` 中常包含空格、括号、`>`、`<`、`!`，建议统一使用单引号包裹。

## 故障排查

### 配置后补全不生效

- 确认已经重新加载 Shell 配置。
- Bash 用户确认安装了 `bash-completion`。
- Zsh 用户确认启用了 `compinit`。
- 确认加载的是 `kube-sync completion <shell>` 生成的最新脚本。

### 提示无法连接 Kubernetes 集群

检查：

```bash
kubectl --kubeconfig ~/.kube/config get ns
kube-sync get ns -k ~/.kube/config
```

如果 `kubectl` 能访问但 `kube-sync` 不能，优先显式指定 `-k`、`--src.kc` 或 `--dst.kc`。

### 同步结果里缺少 ConfigMap / Secret

可能原因：

- 工作负载没有通过 env、envFrom、volume 等方式引用对应资源。
- 执行命令时使用了 `--skip-configmap` 或 `--skip-secret`。
- 当前账号没有读取 ConfigMap 或 Secret 的权限。

### 迁移后工作负载启动失败

优先检查：

```bash
kube-sync get events --for deploy/<name> -n <namespace> --type Warning
kube-sync get pod -n <namespace> -l app=<app> -o wide
```

常见原因：

- 跳过了 ConfigMap 或 Secret。
- 镜像拉取权限在目标集群不可用。
- PVC/PV 或 StorageClass 不兼容。
- RBAC 权限不完整。
- 目标集群缺少对应 CRD。

### `--filter` 没有返回预期结果

检查：

- **表达式是否加了引号**，例如 `--filter 'cpu>10'`。**这是最常见的坑**：`>` / `<` 是 shell 重定向符号，不加引号会被 shell 截走，过滤无效，输出还会被悄悄写到名为右值（如 `0`、`2`）的文件里。可以执行 `ls -l 0` 看是否存在该文件来确认是否踩了这个坑。
- 字段是否属于当前命令支持的字段。
- **取值单位是否符合预期**：`cpu>2` 表示 2 核（不是 2 毫核也不是 2%），`cpu>500m` 才表示 0.5 核；`mem>512Mi` 必须带单位。
- 是否混淆了 request 和 limit。对于 `==` / `!=`，建议显式写 `limit:` 或 `request:`。
- Node 过滤不支持 `limit:` / `request:` 前缀。

## License

本项目基于 [Apache 2.0 License](./LICENSE) 开源。

## 致谢

感谢 Gitee 提供稳定的代码托管平台。

Built with ❤️ by [hexug](https://gitee.com/hexug)

如果你觉得这个项目对你有帮助，欢迎 Star 支持。