从MicroK8s 升级 K3s的完整迁移方案（针对当前K8s环境、可直接执行）

从MicroK8s → K3s的完整迁移方案（针对当前K8s环境、可直接执行）

下面是MicroK8s → K3s的完整迁移方案，关键步骤、命令、校验、回滚策略都写齐了 —— 你可以按顺序执行。官方迁移 playbook 的细节会在相关步骤里引用。

一、总体思路（简要）

  1. 备份当前 MicroK8s 集群（configs、gepetto、secrets、Postgres dump）
  2. 在全新或指定控制节点上用新版 Ansible (ansible/k3s) 部署 K3s 控制平面（setup-control-plane）
  3. 运行迁移准备任务（收集 GPU/cost 信息、确保 CLI、修改 gepetto 等）
  4. 逐台（串行）迁移 Worker：从 MicroK8s 移除 → 重置 → 安装 K3s Agent → 加入新控制平面 → 重新注册到 chutes。迁移是 串行 的（失败会停止，便于排查）。
  5. 清理旧 microk8s 控制节点并完成收尾（部署最终 gepetto 配置、监控等）。

二、前置条件（必做项）

  • Ansible 2.15+ 可用（控制机）
  • 控制节点（将运行 K3s）是一台 新 主机（不能复用正在作为 microk8s control 的机器，参见官方注意）。
  • 所有节点均可 SSH（ansible 可 sudo）
  • chutes-miner-cli 在控制机或节点可用（根据 run_cli_locally 配置决定）
  • 已备份 Bittensor hotkey（hotkey 文件路径要可用）
  • Inventory 已包含 microk8s 组（详见下文）以便 playbook 正确识别旧控制平面与待迁移节点。

三、在你环境的具体备份步骤（强烈建议先做）

在当前旧版本（~/new/chutes-miner）控制节点上执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 建目录
mkdir -p ~/migration-backup
cd ~/migration-backup

# 导出 k8s 资源
microk8s kubectl get all -n chutes -o yaml > chutes_all_$(date +%F_%T).yaml

# 备份 gepetto configmap & miner secrets
microk8s kubectl get configmap gepetto-code -n chutes -o yaml > gepetto_code.yaml
microk8s kubectl get secret miner-credentials -n chutes -o yaml > miner_credentials.yaml

# 导出 Postgres 数据（示例）
POD=$(microk8s kubectl get pod -n chutes -l app=postgres -o jsonpath='{.items[0].metadata.name}')
microk8s kubectl exec -n chutes $POD -- pg_dumpall -U postgres > pg_dump_all.sql

# 打包备份（上传离线备份到你信任的地方）
tar czf ~/chutes_migration_backup_$(date +%F).tgz ~/migration-backup

备份完成后确认文件完整再继续。若需要恢复会用到这些文件。

四、准备 inventory.yml（关键）

官方要求：在 inventory 中加入 microk8s 组以识别旧 control（不和新 control 冲突）。下面给出已为你填写的模板（根据你先前给出的旧 inventory），请保存为 ~/chutes/inventory.yml（或放到 ansible/k3s 目录下使用）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
all:
  vars:
    ssh_keys:
      - "ssh-rsa AAAA... 10.0.0.2"
      - "ssh-rsa AAAA... 10.0.0.3"
      - "ssh-rsa AAAA... 10.0.0.4"
    user: root
    ansible_user: root
    ansible_ssh_private_key_file: ~/.ssh/id_rsa

    # 把 hotkey 放到 /etc/chutes-miner/hotkey.json 或本地路径（按你的偏好）
    remote_hotkey_path: /etc/chutes-miner/hotkey.json
    copy_hotkey_to_ansible_host: false

    # 迁移 playbook 配置
    run_cli_locally: false
    miner_api_port: 32000

  children:
    # 新 K3s control（必须是新的机器，不能是旧 microk8s control）
    control:
      hosts:
        chutes-miner-cpu-0:
          ansible_host: 10.0.0.1
          external_ip: 10.0.0.1
          wireguard_ip: 192.168.0.2

    # Existing GPU workers (from microk8s) will be migrated
    workers:
      hosts:
        chutes-miner-gpu-0:
          ansible_host: 10.0.0.2
          external_ip: 10.0.0.2
          wireguard_ip: 192.168.0.3
        chutes-miner-gpu-1:
          ansible_host: 10.0.0.3
          external_ip: 10.0.0.3
          wireguard_ip: 192.168.0.4


    # Note: group name for current microk8s control - DO NOT name it 'control'
    microk8s:
      hosts:
        microk8s-control-0:
          ansible_host: 10.0.0.1

重要：microk8s 组必须保留，以便迁移 playbook 能识别旧控制平面并执行安全迁移流程（官方强制约束）。

五、部署 K3s 控制平面（先在新 control 上运行）

从 ansible/k3s 目录运行：

1
2
cd ~/new/chutes-miner-new/ansible/k3s
ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --tags setup-control-plane

该步骤会：

  • 在 control 指定的主机上安装并配置 K3s
  • 部署 chutes-miner 的 helm charts（Postgres/Redis/API/Gepetto 等）
  • 配置监控（Prometheus/Grafana）与证书等。

执行后校验：

1
2
kubectl --context chutes-miner-cpu-0 get pods -n chutes
kubectl --context chutes-miner-cpu-0 get svc -n monitoring

六、迁移准备（采集信息与调整 gepetto）

为避免 gepetto 在迁移过程中自动回滚/重排，需要运行准备任务：

1
ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --tags migrate-prep

这一步会：

  • 校验 chutes-miner-cli 是否可用
  • 禁用 audit-exporter cronjob（避免干扰）
  • 临时覆盖 gepetto configmap 避免 reconciliation loop
  • 收集节点的 GPU type / hourly_cost 等，生成 vars/chutes_nodes.yml（供后续 re-add 使用）

七、串行迁移 Worker 节点（按节点执行，遇错停止以排查）

对每个 worker 节点单独运行（示例先迁移 chutes-miner-gpu-0）：

1
2
# 迁移单节点（串行）
ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --limit chutes-miner-gpu-0 --tags migrate-nodes

对每台节点的过程（官方说明）：

  1. 从 Chutes inventory 中删除节点并从 microk8s cluster 中 drain/remove（.removed marker）
  2. 停止 microk8s、清理系统（reset），并 reboot（.reset marker）
  3. 通用系统设置（install deps 等）（.setup marker）
  4. 安装 K3s agent（.k3s marker）
  5. Karmada / 新 control join（.karmada marker）
  6. 将节点重新 add 到 Chutes inventory（.added）并完成 .migrated 标记。

注意：迁移 playbook 已实现幂等和 resume 能力（marker 文件在 /etc/ansible），若中途失败，下次运行会跳过已完成步骤。详见 Migration Markers。

八、清理旧 microk8s 控制平面（在确认所有 node 都迁移成功后）

  1. 从 inventory 中移除 microk8s 组
  2. 删除旧 microk8s control 的 Chutes 命名空间或整机清理（谨慎）
  3. 在新 cluster 上恢复最终版 gepetto（把你要用的 gepetto.py 重新写入 configmap 并 rollout）：
1
2
kubectl create configmap gepetto-code --from-file=gepetto.py -n chutes --context chutes-miner-cpu-0
kubectl rollout restart deployment/gepetto -n chutes --context chutes-miner-cpu-0

九、验证（Migration Verification）

控制平面验证：

1
2
3
kubectl --context chutes-miner-cpu-0 get pods -n chutes
kubectl --context chutes-miner-cpu-0 get svc -n monitoring
curl -s http://<control-ip>:32000/health   # miner API health check

Worker 验证：

1
2
ansible -i ~/chutes/inventory.yml workers -b -m command -a "systemctl status k3s-agent"
kubectl --context chutes-miner-cpu-0 get nodes --show-labels

节点在 Chutes 中已重新注册：

  • 使用 chutes-miner-cli 或 API 确认 chutes-miner inventory 上显示节点（playbook 会自动 re-add）。

十、监控与可观测性

  • Grafana：http://<control-ip>:30080（默认 playbook 已部署）
  • Prometheus：http://<control-ip>:30090
  • Node-exporter metrics 在 9100 端口

十一、回滚与恢复方案（若迁移失败）

官方给出的回滚步骤要点如下：

  1. 如果单节点迁移失败，可清除该节点上的迁移 markers 并重试：
1
ansible -i ~/chutes/inventory.yml workers -b -m file -a "path=/etc/ansible/.migrated state=absent"
  1. 要完全回滚并把节点恢复到 microk8s 状态，可运行 reset playbook（或用 microk8s 的 ansible 重新安装）：
1
ansible-playbook -i ~/chutes/inventory.yml playbooks/reset.yml
  1. 若要回退到旧集群（整个集群回滚），务必使用你在第一步做的 pg_dump & config backups 恢复数据与 config。

十二、常见问题与注意事项（实战要点）

  • 必须在 inventory.yml 中保留 microk8s 组且不能把新 control 设置为旧 microk8s（官方强调）。
  • 迁移是串行的：一台一台迁移，便于问题排查与最小化得分影响（这是官方设计）。
  • 若你希望从 Ansible 控制机直接执行 chutes-miner CLI：设置 run_cli_locally: true（否则 CLI 必须在控制机或远端 host 可用）。
  • 确认 registry_port、minerApi.port、Grafana 密码等在 inventory.yml 与 values.yaml 中一致（端口/secret 对齐）。

十三、为你准备的快速执行列表（照着跑就行）

  1. 备份（参见第三节）

  2. 把我给你的 ~/chutes/inventory.yml 保存好，并把 hotkey 路径确认可访问

  3. 在 ~/new/chutes-miner-new/ansible/k3s 目录运行：

    1
    2
    ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --tags setup-control-plane
    ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --tags migrate-prep

  4. 串行迁移每台 GPU（示例）：

    1
    2
    3
    ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --limit chutes-miner-gpu-0 --tags migrate-nodes
    ansible-playbook -i ~/chutes/inventory.yml playbooks/migrate.yml --limit chutes-miner-gpu-1 --tags migrate-nodes
    ...

  5. 完成后清理 microk8s 组并重启 gepetto（见第八节）

  6. 验证（见第九节）