lifecycle-crud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lifecycle CRUD

生命周期CRUD

You own the lifecycle of Runpod's reusable resources: templates, network volumes, container registry credentials, account secrets, registered SSH public keys, and multi-node clusters. The goal is a correctly provisioned resource the user can rely on: provision cleanly, confirm by reading the resource back, and leave it standing. Tear down only when the user asked for a create-then-clean-up demo or explicit cleanup. Read the existing resources first so you never collide with or clobber something the user already has.

你负责管理Runpod可复用资源的生命周期：模板、网络卷、容器镜像仓库凭证、账户密钥、已注册的SSH公钥以及多节点集群。目标是提供用户可信赖的、配置正确的资源：干净利落地完成配置，通过回读资源进行确认，然后保持资源运行。仅当用户要求「创建后清理」的演示或明确提出清理请求时，才拆除资源。请先读取现有资源，避免与用户已有的资源冲突或覆盖它们。

Required capabilities

所需能力

Named as capabilities; the tool serving each one on this server is in the tool binding below.

List / inspect / create / update / delete templates.
List / inspect / create / update / delete network volumes.
List / inspect / create / delete container registry credentials.
List / inspect / create / update / delete account secrets.
Read and replace the account's registered SSH public keys.
List / inspect / create / rename / delete multi-node clusters, and list a cluster's member pods.
Read data centers and their per-GPU availability, to place a volume in a GPU-co-located DC.

以能力名称列出；本服务端中对应每项能力的工具见下方工具绑定表。

列出/查看/创建/更新/删除模板。
列出/查看/创建/更新/删除网络卷。
列出/查看/创建/删除容器镜像仓库凭证。
列出/查看/创建/更新/删除账户密钥。
读取和替换账户已注册的SSH公钥。
列出/查看/创建/重命名/删除多节点集群，以及列出集群的成员Pod。
读取数据中心及其各GPU的可用情况，以便将卷放置在与GPU同机房的位置。

Shared discipline (every resource)

通用规范（所有资源适用）

Read first. List existing resources before creating; confirm the name you intend to use is not already taken.
Touch nothing outside the resources this conversation created or the user named. Never delete or update a resource this conversation did not create unless the user named it by id or an unambiguous name and asked for exactly that change. A user-named resource is deleted only on the user's ask for that delete. A name that merely looks disposable, or one you found by listing, is not attribution (the router's mutations-bind rule).
Confirm by read-back. After a create or update, inspect the resource and verify the fields you set came back as you set them. A write call's own response is not a read, so confirm from a fresh one. (An update is a PATCH: only the fields you send change, and omitted fields are left untouched, so send only what the user authorized.)
When the user asked for cleanup, or framed the create as a round trip to be removed afterwards, tear down what the journey created in dependency order (a registry credential won't delete while a Pod is pulling with it, but a template that references it is not checked and silently loses it), confirming each deletion with a final read-back showing it is gone. Otherwise leave resources standing and say what exists and what it bills.
State cost before creating a billable resource. A network volume bills storage per GB-month for as long as it exists. Say the size, and that it bills until deleted, before you create it. A cluster is GPU compute: it rents
```
podCount
```
×
```
gpuCountPerPod
```
GPUs from creation, so state that total hourly price (per-GPU price × the GPU count, from the catalog reads) before creating one.

先读取再操作。 创建前先列出现有资源；确认你打算使用的名称尚未被占用。
不得触碰本次对话创建的资源或用户指定资源之外的任何内容。 除非用户通过ID或明确名称指定并要求进行对应修改，否则永远不要删除或更新本次对话未创建的资源。用户指定的资源仅在用户明确要求删除时才删除。仅看起来像是临时使用的名称，或你通过列表查到的名称，都不能作为操作依据（路由的mutations-bind规则）。
通过回读确认。 创建或更新后，检查资源并验证你设置的字段与预期一致。写入调用的自身响应不算读取结果，因此需要通过全新的读取请求来确认。（更新是
```
PATCH
```
操作：只有你发送的字段会被修改，未提及的字段保持不变，因此仅发送用户授权修改的内容。）
当用户要求清理，或将创建表述为后续需删除的往返流程时，按依赖顺序拆除本次流程创建的资源（镜像仓库凭证在有Pod正在使用它拉取镜像时无法删除，但引用该凭证的模板不会被检查，会静默失去凭证引用），每次删除后都通过最终回读确认资源已消失。否则请保持资源运行，并说明现有资源及其计费情况。
创建计费资源前需说明成本。 网络卷按存储容量以GB/月计费，只要存在就会持续计费。创建前请说明卷的大小，以及它会持续计费直到被删除。集群属于GPU计算资源：从创建起就会按
```
podCount
```
×
```
gpuCountPerPod
```
的GPU数量租赁，因此创建前请说明总小时价格（单GPU价格 × GPU总数，从目录查询中获取）。

Journeys

典型场景流程

Reusable template CRUD. List templates, create the template with the name and image/disk/ports/env the user specified, read it back to confirm; when they asked for a create-then-clean-up round-trip, delete it and confirm removal. A template referenced by a Pod or bound to an endpoint will refuse deletion; surface that, do not force it.
Network volume lifecycle. List volumes, create the volume with the requested size (10 to 4096 GB) in a data center the user (or the workload) needs and that offers network storage (a non-empty
```
networkVolumeTypes
```
on the data-center read). State the storage cost. Read it back and leave it to serve its purpose. It bills until deleted, so say so; delete and confirm only on an explicit cleanup ask. A volume's size may only increase; a shrink is rejected.
Volume-backed model files. Keep large model files on a network volume co-located with the GPU that will consume them. Read the data centers with their per-GPU availability (
```
include:["GPU_AVAILABILITY"]
```
) to pick a data center that has the target GPU in stock for the product you will run there, and create the volume there. Explain the wiring: mount path into the Pod/worker, weights downloaded once and reused, and the cold-start effect (first job pays the download, later jobs mount the cached weights). Place, don't guess: the volume must live in the same data center as the compute or the mount won't attach, and network volumes attach to Secure Cloud compute only. On a Pod the mount path is the one you set in
```
mounts
```
(no default); a Serverless worker always sees the volume at
```
/runpod-volume
```
, so weights staged from a Pod are read by the endpoint handler at
```
/runpod-volume
```
, not the pod path.
Cleanup asks. When asked to clean up resources and this conversation created nothing (or its creations are already gone), the honest answer is reads only: list the account, say that nothing this conversation created remains, and list the resources that look unused (ids, names, the evidence from the reads) for the user to decide. Never delete on a name-guess; that report is the complete answer.
Private registry creds + pull-fail diagnosis. Create the registry credential for the private image. Credentials are write-only: the read-back will never return the username/password, and you must never echo the values you sent into the transcript or logs. When an image pull fails, diagnose the two distinct causes: an auth failure (wrong/expired credential, or none attached; the fix is a valid registry cred) versus Docker Hub anonymous rate-limiting (an unauthenticated pull of a public image hitting the pull-rate cap; the fix is authenticating even for the public pull). Name which one from the error text; do not conflate them.
Missing credential values. A registry credential is only useful with the user's real values: when none were supplied, ask for them, since the user is the only source. Never invent placeholder values for a credential meant to be used, and never echo the values back once given.
Account secret CRUD. List the secrets first: the
```
name
```
is unique across the account and immutable, so a colliding create is rejected with
```
409
```
. Create it with the user's real value (they are the only source; never invent one), read it back to confirm the metadata, and tell the user how it is consumed: set an env var on the template, pod, or endpoint to
```
{{ RUNPOD_SECRET_<name> }}
```
and Runpod substitutes the stored value when the pod or worker boots. The value itself is write-only: no read returns it, and you never echo it into the transcript. When the user has not given the value yet, give the whole plan first (the secret name you will use, that the endpoint or template reads it as
```
{{ RUNPOD_SECRET_<name> }}
```
, and that the value is never shown back), then ask for the value. Rotating is
```
update-secret
```
; the new value reaches pods and workers at their next boot, so say that a running instance keeps the value it started with. Deleting a secret is not blocked while it is in use: the references stop resolving and the next pod or worker start that needs them fails, so point the user at the references before a delete.
SSH keys on the account.
```
update-ssh-keys
```
is a replace-all PUT, not an append: read the current keys first, send them back together with the new one, and confirm with a read. Sending only the new key silently removes every other key on the account, and
```
[]
```
removes all of them. Keys apply to pods created afterwards with
```
startSsh
```
; a running pod is not updated.
Multi-node cluster lifecycle. A cluster is billable compute, not plumbing: every GPU in it bills from the moment it exists, at the catalog price per GPU times the GPU count. Read the account's clusters, the GPU's stock (
```
include:["AVAILABILITY"]
```
with
```
product:["CLUSTER"]
```
, because cluster stock differs from pod stock) and the price first. Then put the exact shape (nodes, GPUs per node, data center) and the total hourly price (
```
podCount
```
×
```
gpuCountPerPod
```
GPUs of the chosen type, priced from the catalog) in front of the user and ask for the go. Only an explicit go in this conversation unlocks
```
create-cluster
```
; a request to create or provision a cluster is the request for that plan, not the go. When the read shows no stock for that GPU, say so and propose the closest shape the read shows in stock. The cluster type, GPU type and GPUs per pod are fixed at creation and
```
update-cluster
```
only renames; pods are added or removed from the console (Scale cluster), not through these tools. So get the shape right the first time and hand a resize to the console. Cluster pods can carry a higher rate than the pod GPU price, so after creation confirm the real rate with
```
list-cluster-billing
```
.
```
templateId
```
provisions every member pod from a pod template and is the only private-image path (a bare
```
registry
```
on the create body is rejected). Read the cluster back with
```
get-cluster
```
for the aggregate pod summary, and
```
list-cluster-pods
```
for the member pods themselves;
```
list-cluster-billing
```
is the spend read.

可复用模板CRUD。 列出模板，按照用户指定的名称、镜像/磁盘/端口/环境变量创建模板，回读确认；如果用户要求创建后清理的往返流程，则删除模板并确认已移除。被Pod引用或绑定到Endpoint的模板会拒绝删除；请告知用户该情况，不要强制删除。
网络卷生命周期。 列出卷，在用户（或工作负载）需要的、提供网络存储的可用数据中心（数据中心查询结果中
```
networkVolumeTypes
```
非空）中创建指定大小（10到4096 GB）的卷。说明存储成本。回读确认后保留卷以提供服务。它会持续计费直到删除，请明确告知；仅在用户明确要求清理时才删除并确认。卷的大小只能增加；缩小请求会被拒绝。
卷承载的模型文件。 将大模型文件保存在与使用它们的GPU同机房部署的网络卷上。查询包含各GPU可用情况的数据中心列表（
```
include:["GPU_AVAILABILITY"]
```
），选择有目标GPU库存、可运行对应产品的数据中心，并在那里创建卷。说明使用逻辑：挂载到Pod/worker的路径、权重只需下载一次即可复用，以及冷启动效应（第一个任务需要承担下载时间，后续任务直接挂载缓存的权重）。必须准确放置，不能猜测：卷必须与计算资源位于同一数据中心，否则无法挂载；且网络卷仅能挂载到Secure Cloud计算资源上。在Pod上，挂载路径是你在
```
mounts
```
中设置的路径（无默认值）；Serverless worker始终在
```
/runpod-volume
```
路径下访问卷，因此从Pod暂存的权重文件，Endpoint处理程序需从
```
/runpod-volume
```
读取，而非Pod的挂载路径。
清理请求。 当用户要求清理资源，但本次对话没有创建任何资源（或创建的资源已被删除）时，诚实的回答是仅做读取：列出账户资源，说明本次对话创建的资源已全部不存在，并列出看起来未使用的资源（ID、名称、读取到的依据）供用户决定。永远不要根据名称猜测删除；上述报告就是完整的答复。
私有镜像仓库凭证 + 拉取失败诊断。 为私有镜像创建镜像仓库凭证。凭证是只写的：回读永远不会返回用户名/密码，你也绝对不能将发送的凭证值回显到对话记录或日志中。当镜像拉取失败时，区分两种不同的原因进行诊断：认证失败（凭证错误/过期，或未绑定凭证；解决方案是提供有效的镜像仓库凭证）与Docker Hub匿名拉取限流（未认证拉取公共镜像达到拉取速率上限；解决方案是即使拉取公共镜像也要进行认证）。根据错误文本明确指出是哪一种，不要混淆。
凭证值缺失。 镜像仓库凭证只有填入用户的真实值才有用：如果用户没有提供，就向用户询问，因为用户是唯一的信息来源。永远不要为需要实际使用的凭证编造占位值，也不要在收到值后回显。
账户密钥CRUD。 先列出密钥：
```
name
```
在整个账户中唯一且不可变，因此名称冲突的创建请求会被返回
```
409
```
拒绝。使用用户提供的真实值创建（用户是唯一来源；永远不要编造），回读确认元数据，并告知用户使用方式：在模板、Pod或Endpoint上设置环境变量为
```
{{ RUNPOD_SECRET_<name> }}
```
，Runpod会在Pod或worker启动时替换为存储的值。值本身是只写的：任何读取都不会返回，你也永远不要回显到对话中。如果用户还没有提供值，先说明完整方案（你将使用的密钥名称、Endpoint或模板将通过
```
{{ RUNPOD_SECRET_<name> }}
```
读取它、值永远不会被回显），然后再向用户询问值。轮换密钥使用
```
update-secret
```
；新值会在Pod和worker下次启动时生效，因此请说明运行中的实例会继续使用启动时的旧值。删除密钥不会因为正在被使用而被阻止：引用会无法解析，下一个需要该密钥的Pod或worker启动会失败，因此删除前请告知用户相关的引用情况。
账户SSH密钥。
```
update-ssh-keys
```
是全量替换的PUT操作，不是追加：先读取当前密钥，将现有密钥与新密钥一起发送，然后通过读取确认。仅发送新密钥会静默删除账户上的所有其他密钥，发送
```
[]
```
会删除所有密钥。密钥仅对之后创建的、开启
```
startSsh
```
的Pod生效；正在运行的Pod不会更新。
多节点集群生命周期。 集群是计费计算资源，而非基础设施：其中的每个GPU从集群存在起就开始计费，费用为目录中单GPU价格乘以GPU总数。先读取账户的集群列表、GPU库存（
```
include:["AVAILABILITY"]
```
且
```
product:["CLUSTER"]
```
，因为集群库存与Pod库存不同）以及价格。然后将确切的配置规格（节点数、每节点GPU数、数据中心）和总小时价格（所选类型的
```
podCount
```
×
```
gpuCountPerPod
```
个GPU，按目录价格计算）告知用户，并请求确认。只有本次对话中的明确确认才能触发
```
create-cluster
```
；创建或配置集群的请求只是对方案的请求，而非确认指令。如果查询显示该GPU无库存，请说明情况，并建议查询结果中有库存的最接近配置规格。集群类型、GPU类型和每Pod GPU数在创建时固定，
```
update-cluster
```
仅支持重命名；Pod的增减需要通过控制台（Scale cluster）操作，无法通过这些工具完成。因此请在首次创建时就确定好配置，扩缩容操作引导用户到控制台。集群的GPU单价可能高于Pod GPU价格，因此创建后请通过
```
list-cluster-billing
```
确认实际费率。
```
templateId
```
用于通过Pod模板配置所有成员Pod，也是使用私有镜像的唯一方式（创建请求中直接写裸
```
registry
```
字段会被拒绝）。通过
```
get-cluster
```
回读集群获取Pod汇总信息，通过
```
list-cluster-pods
```
获取成员Pod详情；
```
list-cluster-billing
```
用于查询消费情况。

Hard rules

硬性规则

Never touch a resource outside this journey's own creations, except the one the user named for the change they asked for.
Never echo a registry credential value (username/password/token) or a secret value into chat, a log, or a committed file. Both are write-only by design; keep them that way.
Read the registered SSH keys before replacing them.
```
update-ssh-keys
```
overwrites the whole set; a send that omits an existing key deletes it.
Verify every create/update by reading the resource back; verify every delete by a read-back showing absence.
State the storage cost before creating a network volume and the total hourly price before creating a cluster. For a cluster, wait for the user's explicit go as well.
A delete rejected because the resource is in use is a correct API response. Report it and stop; do not force-detach or delete the dependent resource the user did not name.

永远不要触碰本次流程创建的资源之外的任何内容，除非用户明确指定了要修改的资源和修改内容。
永远不要将镜像仓库凭证值（用户名/密码/令牌）或密钥值回显到聊天、日志或提交的文件中。两者设计上都是只写的；请保持这一特性。
替换已注册的SSH密钥前先读取。
```
update-ssh-keys
```
会覆盖整个密钥集合；发送时遗漏现有密钥会导致其被删除。
每次创建/更新都通过回读资源验证；每次删除都通过回读确认资源已不存在。
创建网络卷前说明存储成本，创建集群前说明总小时价格。对于集群，还需要等待用户的明确确认。
因资源正在使用而被拒绝的删除是正确的API响应。请报告该情况并停止操作；不要强制分离或删除用户未指定的依赖资源。

Error handling

错误处理

A delete returns
```
204
```
with no body. That is success; confirm with a follow-up read.
A volume or registry-credential delete rejected with an in-use error means a Pod is still using it. Name the blocker; do not cascade. A template's reference does not block a credential delete; the template is cleared instead, so check templates before deleting a credential they use.
A registry read that omits
```
username
```
/
```
password
```
is expected (write-only), not a bug.
A secret read that omits the value is expected (write-only), not a bug; a create rejected with
```
409
```
means the name is taken. Names are immutable, so pick another or rotate the existing secret with
```
update-secret
```
.
```
update-secret
```
carrying both a value and a description is not atomic: if the description write fails after the value rotated, the error response comes back with the new value already in effect. Send the two in separate calls when that partial outcome matters.
A cluster update that tries to change compute, type, or container config is rejected, because that endpoint renames only. Report it, offer the console's Scale cluster for the pod count, and delete-and-recreate for anything else, with the price restated.

删除操作返回
```
204
```
且无响应体。这表示成功；请通过后续读取确认。
卷或镜像仓库凭证删除因「正在使用」错误被拒绝，意味着有Pod仍在使用它。请指出阻塞项；不要进行级联操作。模板的引用不会阻止凭证删除；模板会被清空引用，因此删除凭证前请检查是否有模板在使用它。
镜像仓库查询不返回
```
username
```
/
```
password
```
是预期行为（只写），不是bug。
密钥查询不返回值是预期行为（只写），不是bug；创建请求被返回
```
409
```
拒绝表示名称已被占用。名称不可变，因此请选择其他名称，或使用
```
update-secret
```
轮换现有密钥。
同时携带值和描述的
```
update-secret
```
操作不是原子的：如果值轮换成功后描述写入失败，错误响应返回时新值已经生效。如果在意这种部分生效的情况，请分两次调用分别发送。
尝试修改计算配置、类型或容器配置的集群更新请求会被拒绝，因为该端点仅支持重命名。请报告该情况，建议使用控制台的Scale cluster调整Pod数量，其他修改则需要删除后重建，并重新说明价格。

Tool binding

工具绑定

Capability	Tool
Templates (list/get/create/update/delete)	`list-templates` , `get-template` , `create-template` , `update-template` , `delete-template`
Network volumes (list/get/create/update/delete)	`list-network-volumes` , `get-network-volume` , `create-network-volume` , `update-network-volume` , `delete-network-volume`
Registry credentials (list/get/create/delete)	`list-registries` , `get-registry` , `create-registry` , `delete-registry`
Data centers with per-GPU availability (for placement)	`list-data-centers` / `get-data-center` ( `include:["GPU_AVAILABILITY"]` ); `list-gpu-types` ( `include:["AVAILABILITY"]` with `product` )
CUDA versions with capacity, per GPU type	the GPU read's `cudaVersions` ; `get-capacity` for the matrix view
Account secrets (list/get/create/update/delete)	`list-secrets` , `get-secret` , `create-secret` , `update-secret` , `delete-secret`
Registered SSH public keys (read/replace)	`get-ssh-keys` , `update-ssh-keys`
Clusters (list/get/create/rename/delete, member pods, billing)	`list-clusters` , `get-cluster` , `create-cluster` , `update-cluster` , `delete-cluster` , `list-cluster-pods` , `list-cluster-billing`

If a tool named here is missing from the session's tool list, say so and use the nearest read instead of inventing a result.

能力	工具
模板（列出/获取/创建/更新/删除）	`list-templates` , `get-template` , `create-template` , `update-template` , `delete-template`
网络卷（列出/获取/创建/更新/删除）	`list-network-volumes` , `get-network-volume` , `create-network-volume` , `update-network-volume` , `delete-network-volume`
镜像仓库凭证（列出/获取/创建/删除）	`list-registries` , `get-registry` , `create-registry` , `delete-registry`
带各GPU可用情况的数据中心（用于放置资源）	`list-data-centers` / `get-data-center` （ `include:["GPU_AVAILABILITY"]` ）； `list-gpu-types` （ `include:["AVAILABILITY"]` 配合 `product` ）
各GPU类型支持的CUDA版本与容量	GPU查询结果的 `cudaVersions` ； `get-capacity` 用于矩阵视图
账户密钥（列出/获取/创建/更新/删除）	`list-secrets` , `get-secret` , `create-secret` , `update-secret` , `delete-secret`
已注册的SSH公钥（读取/替换）	`get-ssh-keys` , `update-ssh-keys`
集群（列出/获取/创建/重命名/删除、成员Pod、计费）	`list-clusters` , `get-cluster` , `create-cluster` , `update-cluster` , `delete-cluster` , `list-cluster-pods` , `list-cluster-billing`

如果此处列出的某个工具不在当前会话的工具列表中，请说明情况，并使用最接近的读取工具，切勿编造结果。

Report template — resource inventory

报告模板 — 资源清单

When asked what exists on the account (inventory, audit, "what's running"): list pods, endpoints, templates, and network volumes; a table per non-empty kind works well (name, id, status, GPU/size, $/hr where the read provides it), with empty kinds noted in a line ("templates: none"). Close with the totals (counts per kind, summed $/hr of running pods) and, if the user implied a concern (cost, stuck resources), the verdict in one sentence.

当被询问账户上有什么（清单、审计、「正在运行什么」）时：列出Pod、Endpoint、模板和网络卷；每种非空资源用表格展示（名称、ID、状态、GPU/大小、小时费用（如果查询结果提供）），空的资源类型用一行说明（例如「模板：无」）。最后附上总计（每种资源的数量、运行中Pod的总小时费用），如果用户暗示了担忧（成本、资源卡住），用一句话给出结论。

Contract

合约

The cross-journey answer contract (definite facts from reads, commit-don't-hedge, mutations bind to this conversation's creations, a standalone final message, honest failure, granted tools only) is defined in the

runpod-mcp

skill and applies to every reply from this journey. If the

runpod-mcp

skill has not been loaded in this conversation, load it now, before the next tool call: its rules on which resources you may change, when a request is the go, and when to stop for the user are not repeated here.

跨流程的答复合约（基于读取的确定事实、给出明确结论不模棱两可、变更仅绑定本次对话创建的资源、独立的最终消息、诚实反馈失败、仅使用已授权工具）在

runpod-mcp

技能中定义，适用于本流程的每一次回复。如果本次对话尚未加载

runpod-mcp

技能，请在下一次工具调用前先加载它：它关于哪些资源可以修改、何时请求算确认、何时需要停下等待用户的规则，此处不再重复。