runpod-cloud-migrate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate 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).
NeedOwner
What the other platform's thing becomes on Runpodthe platform playbook in
reference/
(table below)
Pods vs Serverless, storage, GPU choice, networkingrunpod-usage
Creating and managing Runpod resourcesrunpod-mcp or runpodctl, per the router's matrix
Python apps without a Dockerfile (
runpod.App
)
runpod-flash
A Dockerfile and handler for a custom imagerunpod-build-template
Serving an LLM with an OpenAI-compatible routerunpod-vllm
Ordering, flags and traps for a deploythe golden paths
将运行在其他云或 GPU 平台上的项目迁移到 Runpod。此 skill 负责迁移流程和各平台映射,但不负责 Runpod 的工作原理或操作方式:这些内容会转交给对应的 lane(router)。
需求负责方
其他平台上的组件在 Runpod 中对应什么
reference/
中的平台 playbook(见下表)
Pod 与 Serverless、存储、GPU 选择、网络runpod-usage
创建和管理 Runpod 资源runpod-mcp 或 runpodctl,具体取决于 router 的矩阵
不含 Dockerfile 的 Python 应用(
runpod.App
)
runpod-flash
用于自定义镜像的 Dockerfile 和 handlerrunpod-build-template
通过 OpenAI 兼容路由提供 LLM 服务runpod-vllm
部署的顺序、参数和常见陷阱golden paths

Rules that hold for the whole migration

适用于整个迁移的规则

  1. Inventory before anything else. Never plan from the user's description alone: the repo usually depends on more than they remember.
  2. 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.
  3. 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.
  4. One workload at a time, smallest first. Verify it with a real request before starting the next.
  5. 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.
  6. 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.
  7. 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.
  8. 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).
  1. 先盘点,再做任何其他事情。 绝不能仅凭用户的描述制定计划:仓库通常依赖的内容比他们记得的更多。
  2. 在用户另行说明前,源平台一律只读。 可以自由列出和查看资源。未经明确指示并指明具体资源,不得停止、缩容、删除或修改源平台上的资源。如果在新部署验证之前就破坏了旧平台上的生产环境,则此次迁移属于失败。
  3. 未经批准的计划,不得在 Runpod 上创建任何计费资源。 先展示计划和小时成本上限(第 3 步),然后只创建计划中列出的资源。
  4. 每次只迁移一个工作负载,并从最小的工作负载开始。 使用真实请求验证当前工作负载后,才能开始下一个。
  5. 凭据必须以 secret 形式迁移,绝不能以明文形式迁移。 跨平台保留凭据名称。请用户将凭据值设置为 Runpod secrets 或环境变量;不要从源平台读取凭据值、打印凭据值或将其提交到版本库。
  6. 保持旧调用路径可用。 将新 endpoint 置于配置开关之后(通过环境变量切换 base URL 或 provider),使切换和回滚只需更改一个配置项。
  7. 明确说明缺口,不要掩盖问题。 每份 playbook 都以“Gaps: stop and ask the user”部分结尾。这些都是只有用户才能做出的决策。
  8. 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 repo
It reads files only: no network, no credentials, no edits. Hits are grouped by kind (
sdk
,
cli
,
api
,
config
,
iac
,
runtime
,
credential
). A hit is evidence, so open the file before deciding what it means. Show the user the summary table.
The 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
它只读取文件:不访问网络、不使用凭据、不进行编辑。命中项按类型(
sdk
、
cli
、
api
、
config
、
iac
、
runtime
、
credential
)分组。命中项只是证据,因此在判断其含义前应打开对应文件。向用户展示汇总表。
仓库只能反映一部分情况。请用户在源平台上运行 playbook 中“列出正在运行的内容”的命令;如果源平台 CLI 已完成认证且这些命令为只读,也可以自行运行,因为控制台中可能存在文件未提及的资源。
没有命中项意味着项目是手动部署的,或基础设施代码存放在其他位置。询问实际有哪些内容运行在哪里。不要猜测平台。

2. Open the playbook for each platform found

2. 针对发现的每个平台打开 playbook

PlatformPlaybook
Vast.aireference/vast-ai.md
Lambdareference/lambda.md
CoreWeave, and Kubernetes GPU workloads on any cloudreference/coreweave.md
Paperspace and DigitalOcean GPUreference/paperspace.md
Modalreference/modal.md
Replicate and Cogreference/replicate.md
Baseten and Trussreference/baseten.md
Together AIreference/together-ai.md
Fireworks AIreference/fireworks-ai.md
falreference/fal.md
Hugging Face Inference Endpoints, Spacesreference/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
openai-compatible
rows mark clients that already take a base URL, which makes them a configuration change rather than a rewrite. Its
runpod
rows mean part of the project is on Runpod already: read those files first and reuse their conventions.
平台Playbook
Vast.aireference/vast-ai.md
Lambdareference/lambda.md
CoreWeave,以及任意云上的 Kubernetes GPU 工作负载reference/coreweave.md
Paperspace 和 DigitalOcean GPUreference/paperspace.md
Modalreference/modal.md
Replicate 和 Cogreference/replicate.md
Baseten 和 Trussreference/baseten.md
Together AIreference/together-ai.md
Fireworks AIreference/fireworks-ai.md
falreference/fal.md
Hugging Face Inference Endpoints、Spacesreference/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 步中的表格按形态对每个工作负载分类,并根据该平台自己的文档完成转换。
扫描器中的
openai-compatible
行表示客户端已经支持配置 base URL,因此只需更改配置,无需重写。
runpod
行表示项目的一部分已经部署在 Runpod 上:应先读取这些文件并复用其中已有的约定。

3. Plan, and get the plan approved

3. 制定计划并获得批准

Classify every workload by its shape, not by the product name it had:
Workload shapeRunpod target
Calls a hosted model someone else runsA Public Endpoint when Runpod hosts that model, else your own endpoint
Request in, response out, idle between requestsServerless queue-based endpoint
Your own HTTP server, low latency, custom routesServerless load-balancing endpoint
An LLM behind an OpenAI-compatible APIServerless 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 addressPod
Multi-node training or HPC with SlurmInstant Cluster
The reasoning behind each row is in runpod-usage concepts.
Write the plan as one table and show it before acting:
ColumnContent
WorkloadName on the source platform, and the files that define it
TargetRow from the table above, and the lane that will create it
ComputeGPU type or pool sized to the model's memory needs, worker bounds
Image and codeReused as is, rebuilt for
linux/amd64
, or ported (which contract changes)
DataWhat moves, how large, from where to which storage layer
CallersFiles that call the workload and what changes in each
GapsRows from the playbook's gaps section that apply, with the options
Cost boundHourly 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 的多节点训练或 HPCInstant Cluster
每一行背后的判断依据见 runpod-usage concepts。
将计划写成一张表,并在执行前展示:
列内容
工作负载源平台上的名称,以及定义它的文件
目标上表中的对应行,以及负责创建资源的 lane
计算资源根据模型内存需求选择的 GPU 型号或资源池,以及 worker 上下限
镜像和代码原样复用、重建为
linux/amd64
,或进行移植(以及哪些契约会发生变化)
数据需要迁移的内容、大小、来源以及目标存储层
调用方调用该工作负载的文件,以及每个文件中的变更
缺口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
https://docs.runpod.io/migrate/<playbook file name without .md>
: 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.
最终汇报应包括:迁移了什么、各项资源在 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 saysDo
"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
iac
hits, then the playbook's Terraform rows
"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 步并重点检查
iac
命中项,然后使用 playbook 中的 Terraform 相关条目
“我们已经迁移了计算资源,修复调用方”执行第 1 步,然后使用 playbook 中的客户端和 API 调用映射