runpod-cloud-migrate
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMigrate to Runpod from another platform
从其他平台迁移到 Runpod
Moves a project that runs on another cloud or GPU platform onto Runpod. This skill owns the
migration procedure and the per-platform maps. It does not own how Runpod works or how
to operate it: for those it hands off to the lanes (router).
| Need | Owner |
|---|---|
| What the other platform's thing becomes on Runpod | the platform playbook in |
| Pods vs Serverless, storage, GPU choice, networking | runpod-usage |
| Creating and managing Runpod resources | runpod-mcp or runpodctl, per the router's matrix |
Python apps without a Dockerfile ( | runpod-flash |
| A Dockerfile and handler for a custom image | runpod-build-template |
| Serving an LLM with an OpenAI-compatible route | runpod-vllm |
| Ordering, flags and traps for a deploy | the golden paths |
将运行在其他云或 GPU 平台上的项目迁移到 Runpod。此 skill 负责迁移流程和各平台映射,但不负责 Runpod 的工作原理或操作方式:这些内容会转交给对应的 lane(router)。
| 需求 | 负责方 |
|---|---|
| 其他平台上的组件在 Runpod 中对应什么 | |
| Pod 与 Serverless、存储、GPU 选择、网络 | runpod-usage |
| 创建和管理 Runpod 资源 | runpod-mcp 或 runpodctl,具体取决于 router 的矩阵 |
不含 Dockerfile 的 Python 应用( | runpod-flash |
| 用于自定义镜像的 Dockerfile 和 handler | runpod-build-template |
| 通过 OpenAI 兼容路由提供 LLM 服务 | runpod-vllm |
| 部署的顺序、参数和常见陷阱 | golden paths |
Rules that hold for the whole migration
适用于整个迁移的规则
- Inventory before anything else. Never plan from the user's description alone: the repo usually depends on more than they remember.
- The source platform is read-only until the user says otherwise. List and describe freely. Never stop, scale down, delete or modify a resource on the source platform without an explicit instruction naming that resource. A migration that breaks production on the old platform before the new one is verified is a failed migration.
- Nothing billable on Runpod without an approved plan. Show the plan and an hourly cost bound first (step 3), then create only what the plan lists.
- One workload at a time, smallest first. Verify it with a real request before starting the next.
- Credentials move as secrets, never as text. Carry credential names across. Ask the user to set values as Runpod secrets or environment variables; do not read a value out of the source platform, print one, or commit one.
- Keep the old path callable. Put the new endpoint behind a config switch (an env var for the base URL or provider) so cutover and rollback are one setting.
- State gaps, do not paper over them. Each playbook ends with a "Gaps: stop and ask the user" section. Those are decisions only the user can make.
- The playbooks are a snapshot. Each names the date its platform docs were checked. Before relying on a detail of the other platform that the migration hinges on, confirm it in that platform's docs or CLI help. For Runpod, the tool in front of you wins (why).
- 先盘点,再做任何其他事情。 绝不能仅凭用户的描述制定计划:仓库通常依赖的内容比他们记得的更多。
- 在用户另行说明前,源平台一律只读。 可以自由列出和查看资源。未经明确指示并指明具体资源,不得停止、缩容、删除或修改源平台上的资源。如果在新部署验证之前就破坏了旧平台上的生产环境,则此次迁移属于失败。
- 未经批准的计划,不得在 Runpod 上创建任何计费资源。 先展示计划和小时成本上限(第 3 步),然后只创建计划中列出的资源。
- 每次只迁移一个工作负载,并从最小的工作负载开始。 使用真实请求验证当前工作负载后,才能开始下一个。
- 凭据必须以 secret 形式迁移,绝不能以明文形式迁移。 跨平台保留凭据名称。请用户将凭据值设置为 Runpod secrets 或环境变量;不要从源平台读取凭据值、打印凭据值或将其提交到版本库。
- 保持旧调用路径可用。 将新 endpoint 置于配置开关之后(通过环境变量切换 base URL 或 provider),使切换和回滚只需更改一个配置项。
- 明确说明缺口,不要掩盖问题。 每份 playbook 都以“Gaps: stop and ask the user”部分结尾。这些都是只有用户才能做出的决策。
- playbook 是快照。 每份 playbook 都会注明其平台文档的核查日期。在依赖源平台的迁移关键细节前,应在该平台的文档或 CLI help 中确认。对于 Runpod,以当前所用工具为准(原因)。
The workflow
工作流程
1. Inventory
1. 盘点
The scanner ships beside this file, in the installed skill directory, not in the user's
repo. Resolve it first:
bash
SCAN="$CLAUDE_PLUGIN_ROOT/skills/runpod-cloud-migrate/scripts/scan_cloud_usage.py"
[ -f "$SCAN" ] || SCAN="<directory containing this SKILL.md>/scripts/scan_cloud_usage.py"
[ -f "$SCAN" ] || SCAN=$(find ~/.claude ~/.agents ~/.codex ~/.config -name scan_cloud_usage.py 2>/dev/null | head -1)
python3 "$SCAN" --help >/dev/null || echo "scanner not found: resolve it before continuing"Then, from the root of the user's repo:
bash
python3 "$SCAN" . # Markdown summary per platform and kind
python3 "$SCAN" . --json # every hit, for a large repoIt reads files only: no network, no credentials, no edits. Hits are grouped by kind (,
, , , , , ). A hit is evidence, so open the file
before deciding what it means. Show the user the summary table.
sdkcliapiconfigiacruntimecredentialThe repo is half the picture. Ask the user to run the playbook's "list what's running"
commands on the source platform (or run them yourself when its CLI is authenticated and
the commands are read-only), because consoles hold resources no file mentions.
No hits means the project deploys by hand or keeps infrastructure code elsewhere. Ask
what runs where. Do not guess a platform.
扫描器随本文件一起提供,位于已安装的 skill 目录中,而不是用户仓库中。首先定位它:
bash
SCAN="$CLAUDE_PLUGIN_ROOT/skills/runpod-cloud-migrate/scripts/scan_cloud_usage.py"
[ -f "$SCAN" ] || SCAN="<directory containing this SKILL.md>/scripts/scan_cloud_usage.py"
[ -f "$SCAN" ] || SCAN=$(find ~/.claude ~/.agents ~/.codex ~/.config -name scan_cloud_usage.py 2>/dev/null | head -1)
python3 "$SCAN" --help >/dev/null || echo "scanner not found: resolve it before continuing"然后,在用户仓库的根目录运行:
bash
python3 "$SCAN" . # Markdown summary per platform and kind
python3 "$SCAN" . --json # every hit, for a large repo它只读取文件:不访问网络、不使用凭据、不进行编辑。命中项按类型(、、、、、、)分组。命中项只是证据,因此在判断其含义前应打开对应文件。向用户展示汇总表。
sdkcliapiconfigiacruntimecredential仓库只能反映一部分情况。请用户在源平台上运行 playbook 中“列出正在运行的内容”的命令;如果源平台 CLI 已完成认证且这些命令为只读,也可以自行运行,因为控制台中可能存在文件未提及的资源。
没有命中项意味着项目是手动部署的,或基础设施代码存放在其他位置。询问实际有哪些内容运行在哪里。不要猜测平台。
2. Open the playbook for each platform found
2. 针对发现的每个平台打开 playbook
| Platform | Playbook |
|---|---|
| Vast.ai | reference/vast-ai.md |
| Lambda | reference/lambda.md |
| CoreWeave, and Kubernetes GPU workloads on any cloud | reference/coreweave.md |
| Paperspace and DigitalOcean GPU | reference/paperspace.md |
| Modal | reference/modal.md |
| Replicate and Cog | reference/replicate.md |
| Baseten and Truss | reference/baseten.md |
| Together AI | reference/together-ai.md |
| Fireworks AI | reference/fireworks-ai.md |
| fal | reference/fal.md |
| Hugging Face Inference Endpoints, Spaces | reference/hugging-face.md |
| AWS (EC2, SageMaker, Bedrock, Batch) | reference/aws.md |
| Google Cloud (Compute Engine, Vertex AI, Cloud Run) | reference/google-cloud.md |
| Azure (GPU VMs, Azure Machine Learning, Azure OpenAI) | reference/azure.md |
Read only the playbooks the inventory calls for. A platform with no playbook still
migrates: classify each workload by shape with the table in step 3 and translate from
that platform's own docs.
The scanner's rows mark clients that already take a base URL, which
makes them a configuration change rather than a rewrite. Its rows mean part of the
project is on Runpod already: read those files first and reuse their conventions.
openai-compatiblerunpod| 平台 | Playbook |
|---|---|
| Vast.ai | reference/vast-ai.md |
| Lambda | reference/lambda.md |
| CoreWeave,以及任意云上的 Kubernetes GPU 工作负载 | reference/coreweave.md |
| Paperspace 和 DigitalOcean GPU | reference/paperspace.md |
| Modal | reference/modal.md |
| Replicate 和 Cog | reference/replicate.md |
| Baseten 和 Truss | reference/baseten.md |
| Together AI | reference/together-ai.md |
| Fireworks AI | reference/fireworks-ai.md |
| fal | reference/fal.md |
| Hugging Face Inference Endpoints、Spaces | reference/hugging-face.md |
| AWS(EC2、SageMaker、Bedrock、Batch) | reference/aws.md |
| Google Cloud(Compute Engine、Vertex AI、Cloud Run) | reference/google-cloud.md |
| Azure(GPU VM、Azure Machine Learning、Azure OpenAI) | reference/azure.md |
只读取盘点结果所指向的 playbook。即使某平台没有 playbook,也仍然可以迁移:使用第 3 步中的表格按形态对每个工作负载分类,并根据该平台自己的文档完成转换。
扫描器中的 行表示客户端已经支持配置 base URL,因此只需更改配置,无需重写。 行表示项目的一部分已经部署在 Runpod 上:应先读取这些文件并复用其中已有的约定。
openai-compatiblerunpod3. Plan, and get the plan approved
3. 制定计划并获得批准
Classify every workload by its shape, not by the product name it had:
| Workload shape | Runpod target |
|---|---|
| Calls a hosted model someone else runs | A Public Endpoint when Runpod hosts that model, else your own endpoint |
| Request in, response out, idle between requests | Serverless queue-based endpoint |
| Your own HTTP server, low latency, custom routes | Serverless load-balancing endpoint |
| An LLM behind an OpenAI-compatible API | Serverless endpoint running the vLLM worker |
| A job that runs to completion (training, batch) | A Pod, or one ephemeral Pod per call from the Runpod SDK |
| Interactive machine (notebook, SSH, IDE) | Pod |
| Always-on service with a stable address | Pod |
| Multi-node training or HPC with Slurm | Instant Cluster |
The reasoning behind each row is in
runpod-usage concepts.
Write the plan as one table and show it before acting:
| Column | Content |
|---|---|
| Workload | Name on the source platform, and the files that define it |
| Target | Row from the table above, and the lane that will create it |
| Compute | GPU type or pool sized to the model's memory needs, worker bounds |
| Image and code | Reused as is, rebuilt for |
| Data | What moves, how large, from where to which storage layer |
| Callers | Files that call the workload and what changes in each |
| Gaps | Rows from the playbook's gaps section that apply, with the options |
| Cost bound | Hourly rate of what will run and for how long during the test |
Read live GPU stock before naming a GPU or data center
(gpu-selection); stock varies, so the plan
names a fallback. Ask the questions the gaps raise in one batch, with the plan in front of
the user. Proceed when they approve.
根据工作负载的形态进行分类,而不是根据它原来所属的产品名称:
| 工作负载形态 | Runpod 目标 |
|---|---|
| 调用由他人运行的托管模型 | 如果 Runpod 托管该模型,则使用 Public Endpoint;否则使用自己的 endpoint |
| 接收请求、返回响应,请求之间处于空闲状态 | 基于 Serverless 队列的 endpoint |
| 自有 HTTP 服务器、低延迟、自定义路由 | Serverless 负载均衡 endpoint |
| 位于 OpenAI 兼容 API 之后的 LLM | 运行 vLLM worker 的 Serverless endpoint |
| 运行至完成的作业(训练、批处理) | Pod,或通过 Runpod SDK 为每次调用创建一个临时 Pod |
| 交互式机器(notebook、SSH、IDE) | Pod |
| 始终运行且具有稳定地址的服务 | Pod |
| 使用 Slurm 的多节点训练或 HPC | Instant Cluster |
每一行背后的判断依据见 runpod-usage concepts。
将计划写成一张表,并在执行前展示:
| 列 | 内容 |
|---|---|
| 工作负载 | 源平台上的名称,以及定义它的文件 |
| 目标 | 上表中的对应行,以及负责创建资源的 lane |
| 计算资源 | 根据模型内存需求选择的 GPU 型号或资源池,以及 worker 上下限 |
| 镜像和代码 | 原样复用、重建为 |
| 数据 | 需要迁移的内容、大小、来源以及目标存储层 |
| 调用方 | 调用该工作负载的文件,以及每个文件中的变更 |
| 缺口 | playbook 缺口部分中适用的条目及其可选项 |
| 成本上限 | 测试期间所运行资源的每小时费率及其运行时长 |
在指定 GPU 或数据中心之前,读取实时 GPU 库存(gpu-selection);库存会变化,因此计划中应列出备用选项。带着计划,一次性提出所有由缺口引发的问题。用户批准后再继续。
4. Translate (no cloud calls)
4. 转换(不发起云调用)
Do everything that costs nothing first, on a branch, one commit per workload:
- Port the container contract or app code using the playbook's code translation section.
- Rewrite the infrastructure definitions (Terraform, CI deploy steps).
- Add the config switch for callers (rule 6) and the new credential names.
- Leave the source platform's files in place. Removing them is the last step.
先完成所有不产生费用的工作,在分支上进行,每个工作负载使用一个 commit:
- 使用 playbook 中的代码转换部分移植容器契约或应用代码。
- 重写基础设施定义(Terraform、CI 部署步骤)。
- 按规则 6 为调用方添加配置开关,并添加新的凭据名称。
- 保留源平台的相关文件。删除它们是最后一步。
5. Provision one workload and move its data
5. 配置一个工作负载并迁移数据
Hand off to the lane the plan names, and follow the matching golden path for ordering.
Move data before the compute that needs it. Storage placement follows
storage: a network volume lives in one data
center, so choose the data center from GPU stock and create the volume there.
移交给计划指定的 lane,并遵循匹配的 golden path 来确定操作顺序。先迁移数据,再创建依赖数据的计算资源。存储布局遵循 storage 指南:network volume 只能存在于一个数据中心,因此应根据 GPU 库存选择数据中心,并在该处创建 volume。
6. Verify with a real request
6. 使用真实请求进行验证
A resource that reports ready is not a workload that serves. Send the same input to the
old and the new deployment from outside both platforms, then compare: output, latency
of a cold and a warm request, and error handling. Use the playbook's "Verify" section for
platform-specific checks. Fix and repeat until the outputs agree, then report the numbers.
显示 ready 的资源并不等于能够提供服务的负载。从两个平台之外向旧部署和新部署发送相同输入,然后比较:输出结果、冷启动和热启动请求的延迟,以及错误处理。使用 playbook 中的“Verify”部分执行平台特定检查。修复并重复,直到输出一致,然后报告各项数值。
7. Cut over, then repeat
7. 切换,然后重复
Switch callers with the config switch. Keep the old deployment running until the user
confirms the new one under real traffic. Then return to step 4 for the next workload.
通过配置开关切换调用方。在用户确认真实流量下新部署运行正常之前,保持旧部署继续运行。然后返回第 4 步处理下一个工作负载。
8. Report, and shut the source down only on request
8. 汇报,并且仅应用户要求关闭源平台
Finish with: what moved, where each thing lives on Runpod (IDs and URLs), what still runs
on the source platform, the open gaps, what is billing on Runpod now, and how to roll
back. Each platform also has a step-by-step guide for people at
: link it in the report.
The playbook's "Shut down" section lists the commands that stop billing on the
source platform, including the resources people forget. Offer them. Run one only after the
user approves that specific resource.
https://docs.runpod.io/migrate/<playbook file name without .md>最终汇报应包括:迁移了什么、各项资源在 Runpod 中的位置(ID 和 URL)、源平台上仍在运行什么、尚未解决的缺口、Runpod 当前正在计费什么,以及如何回滚。每个平台还为用户提供了分步指南,地址为 ;请在报告中附上该链接。
https://docs.runpod.io/migrate/<playbook file name without .md>playbook 中的“Shut down”部分列出了停止在源平台上计费的命令,其中包括人们容易遗漏的资源。向用户提供这些命令。只有在用户批准某个具体资源后,才能执行其中一条命令。
When the user wants only part of this
当用户只想要其中一部分时
| The user says | Do |
|---|---|
| "What would it take to move off X?" | Steps 1 to 3, then stop at the plan |
| "Compare X and Runpod for this project" | Steps 1 and 2, then the playbook's product map and gaps. No prices for the other platform: point at both pricing pages |
| "Port this file" | Step 4 for that file, and say which other files the inventory found |
| "Move our Terraform" | Step 1 with attention to |
| "We already moved the compute, fix the callers" | Step 1, then the playbook's client and API call map |
| 用户说 | 执行 |
|---|---|
| “从 X 迁移出去需要做什么?” | 执行第 1 至第 3 步,然后停在计划阶段 |
| “比较这个项目中的 X 和 Runpod” | 执行第 1 和第 2 步,然后给出 playbook 的产品映射和缺口。不要提供另一个平台的价格:指向双方的定价页面 |
| “移植这个文件” | 对该文件执行第 4 步,并说明盘点还发现了哪些其他文件 |
| “迁移我们的 Terraform” | 执行第 1 步并重点检查 |
| “我们已经迁移了计算资源,修复调用方” | 执行第 1 步,然后使用 playbook 中的客户端和 API 调用映射 |