Repos / kudig-io / KUME OWN

KUME

KUMEK — Kubernetes Universal Migration Expert

在 GitHub 查看 ↗

KUMEK — Kubernetes Universal Migration Expert

声明式跨云迁移编排引擎。KUMEK 做总指挥，不做搬运工。

KUMEK orchestrates proven open-source tools (Velero, image-syncer, pv-migrate,
Terraform, ExternalDNS) through a declarative control plane to move stateful
workloads across Kubernetes clusters and clouds. First-class route: AWS EKS →
Alibaba ACK.

Design proposal (KEP-0000) · Apache-2.0 · Go 1.25+ · controller-runtime

Why KUMEK

Velero / ACK 备份中心 KUMEK
定位 数据搬运（备份/恢复） 跨云迁移总指挥
边界 同一 API 体系内 跨厂商、跨 API 语义（EKS ↔ ACK）
差异处理 无 声明式规则引擎（ALB→ALB、IRSA→RRSA、ECR→ACR）
切换 全量恢复 检查点 + 门禁 + 加权 DNS 停机切换/回滚
表达 命令式调用 Migration as Code（Git 版本化）

Core invariants:

  • I-1 Sync 阶段对源集群只读。
  • I-2 单写者：只有 MigrationRun Reconciler 推进状态机。
  • I-3 目标集群资源全部携带 migration.kumek.io/managed=true。
  • I-4 门禁语义 + 检查点：Verify 不过不切换；检查点锚定回滚。
  • I-5 幂等重入：任何 reconcile 中断后重放收敛。

Architecture

                 ┌───────────────────────────────────────────┐
                 │            Management Cluster             │
                 │  MigrationPlan ──► MigrationRun (state)   │
                 │        │               │                  │
                 │  TransformationRuleSet │ Tool Jobs/CRs    │
                 └────────┼───────────────┼──────────────────┘
                          │               │
        kubeconfig Secret │               │ rendered objects
                          ▼               ▼
                   ┌────────────┐  ┌────────────┐
                   │ Source EKS │  │ Target ACK │
                   │ (read-only)│  │ (managed)  │
                   └────────────┘  └────────────┘
  • Pipeline as data: six stages (Assess → Prepare → Sync → Verify →
    Cutover → Rollback → Finalize) are a table in
    internal/controller/pipeline.go, not
    if-else.
  • Plugin boundaries: provider.Provider (cloud differences) and
    tool.Adapter (tool integrations) are compile-time registries — implement
    the interface, init()-register, done.
  • Orchestrate, not implement: adapters render the tool's native objects
    (Velero BSLs, image-syncer Jobs) and observe them back. KUMEK never moves
    bytes itself.

Quick start

# 1. Install CRDs and the control plane
kubectl apply -k config/crd
kubectl apply -k config/default

# 2. Register both clusters via kubeconfig Secrets
kubectl -n kumek-system create secret generic eks-kubeconfig \
  --from-file=kubeconfig=./eks.kubeconfig
kubectl -n kumek-system create secret generic ack-kubeconfig \
  --from-file=kubeconfig=./ack.kubeconfig

# 3. Declare the migration (see examples/eks-to-ack/)
kubectl apply -f examples/eks-to-ack/

# 4. A Drill (rehearsal) run is created automatically and walks the whole
#    pipeline read-only against source. Watch it:
kubectl -n kumek-system get mrun -w

# 5. Validate plans offline anytime
go run ./cmd/kumekctl plan validate examples/eks-to-ack/migrationplan.yaml
go run ./cmd/kumekctl run describe eks-to-ack-shop-run1

When the rehearsal is green and gates pass, apply the same plan in
Cutover mode:

apiVersion: migration.kumek.io/v1alpha1
kind: MigrationRun
metadata:
  name: eks-to-ack-shop-go
  namespace: kumek-system
  labels:
    migration.kumek.io/plan: eks-to-ack-shop
spec:
  planRef:
    kind: MigrationPlan
    name: eks-to-ack-shop
    namespace: kumek-system
  mode: Cutover

API surface (v1alpha1)

Resource Purpose
MigrationPlan Declarative desired state: clusters, scope, storage/image mappings, rules, hooks, cutover gates. Git-versioned.
MigrationRun One execution instance: stage/task state, checkpoints, verification results, conditions.
TransformationRuleSet Ordered declarative ops (setAnnotation, replaceAnnotationPrefix, setField, rewriteImage, …).
ProviderConfig Cloud credentials + defaults consumed by provider factories.

Stage task matrix (MVP implementation status):

Stage Task Tool Status
Assess inventory inventory ✅ implemented
Assess feasibility feasibility ✅ capability warnings
Prepare infra terraform-runner ⏳ skipped (optional)
Prepare bootstrap velero (BSL) ✅ render+observe
Prepare transform rules-engine ✅ implemented
Sync images image-syncer ✅ render+observe
Sync pv velero (file-level backup) ✅ render+observe
Sync manifests rules-engine ✅ implemented
Verify static verifier ✅ object-count diff
Verify data verifier ✅ pv-checksum
Verify probe probe-runner ⏳ skipped (optional)
Cutover freeze hooks (Job) ✅ render+observe
Cutover delta velero (backup→restore) ✅ render+observe
Cutover traffic dns-weights (Route53) ✅ render+observe
Rollback reverse hooks (Job) ✅ render+observe
Rollback traffic dns-weights (Route53) ✅ render+observe
Finalize report reporter (ConfigMap) ✅ render+observe

Optional tasks whose adapters report tool.ErrNotImplemented are recorded as
Skipped so the pipeline completes end-to-end while integrations land. Gate
semantics: a skipped verification counts as pass-with-warning in v1alpha1
(caveat documented in the design proposal §4.3).

Extending KUMEK

Add a cloud provider:

// internal/provider/gcp/provider.go
func (GCP) Name() string { return "gcp" }
func init() {
  provider.Register("gcp", func(cfg *v1alpha1.ProviderConfig) (provider.Provider, error) { ... })
}

Add a tool adapter — render native objects, observe them back:

// internal/tool/pvmigrate/pvmigrate.go
func (PvMigrate) Render(tc tool.TaskContext) ([]tool.RenderedObject, error) { /* native Job/CRs */ }
func (PvMigrate) Observe(tc tool.TaskContext) (v1alpha1.TaskStatus, error) { /* tool state → TaskStatus */ }
func init() { tool.Register(PvMigrate{}) }

Blank-import the package in cmd/manager/main.go and it joins the registry.

Development

make test       # unit tests (engine, rules, gates, verify, registries)
make manifests  # controller-gen: deepcopy + CRDs
make build      # manager + kumekctl binaries
make docker-build IMG=ghcr.io/kudig-io/kumek TAG=dev

Layout: api/v1alpha1 (CRD types) · internal/engine (pure state machine,
gates, rules) · internal/controller (Plan/Run reconcilers, pipeline table) ·
internal/provider + internal/tool (plugin boundaries) · internal/kube
(multi-cluster clients, scrubbing) · cmd/ (manager, kumekctl).

Roadmap

  • MVP (now): inventory + feasibility assessment, rules engine, manifest
    shadow-sync, Velero backup/restore orchestration (PV sync + freeze-point
    delta), cutover hooks, weighted DNS cutover, verification gates, report,
    drill pipeline end-to-end.
  • Next: pv-migrate / CSI data mover as an alternative PV data plane;
    Terraform infra stage; synthetic probes; registry credential wiring
    (ECR/ACR) for image-syncer.
  • V1.0: provider plugins for GCP/Azure/Huawei; UI; rollback playbooks.

See docs/DESIGN.md for the full proposal, trade-offs and
open questions.

License

Apache License 2.0 — see LICENSE.