rivet-deploy-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy an image to a Rivet cluster

将 image 部署到 Rivet cluster

A deploy is a local build, one upload, and two Code Mode operations run through the

execute

tool. It needs Docker and a shell. It does not need the Rivet CLI or any other login.

一次部署包括一次本地 build、一次上传，以及通过

execute

工具执行的两项 Code Mode 操作。它需要 Docker 和 shell，不需要 Rivet CLI 或任何其他登录凭据。

Before starting

开始之前

Confirm the session can deploy. If
```
search
```
does not list
```
rivet.deploy.prepare
```
, the session is read-only or is pinned to a project or namespace, and the deploy cannot run from here. Say so instead of retrying.
Pick the cluster. Run
```
return (await rivet.cloud.v2.clusters.list()).items;
```
in
```
execute
```
and use the
```
cluster
```
field of the one to deploy to, which is its name. On a connection pinned to a cluster,
```
rivet.context()
```
reports it, and
```
cluster
```
is left out of every call below.

确认 session 可以执行部署。如果
```
search
```
未列出
```
rivet.deploy.prepare
```
，说明该 session 是只读的，或已固定到某个 project 或 namespace，无法从此处执行部署。应直接说明情况，不要重试。
选择 cluster。在
```
execute
```
中运行
```
return (await rivet.cloud.v2.clusters.list()).items;
```
，并使用目标 cluster 的
```
cluster
```
字段，其值即 cluster 名称。如果连接已固定到某个 cluster，
```
rivet.context()
```
会报告该 cluster，此时以下所有调用均省略
```
cluster
```
。

Steps

步骤

Build and measure the image in the shell. The platform must be

linux/amd64

docker build --platform linux/amd64 -t app .
docker image save app -o image.tar
wc -c < image.tar                        # content_length
openssl md5 -binary image.tar | base64   # content_md5

The tarball must be 5 GiB or smaller. Measure the exact file that will be uploaded, because the build fails verification when either value differs.

return await rivet.deploy.prepare({
	cluster: "my-cluster",
	image: "app:latest",
	content_length: 48213504,
	content_md5: "1B2M2Y8AsgTpgAmY7PhCfg==",
});

content_length

is a number, not a string. Pass

file

when the tarball is not named

image.tar

. Keep the returned

build_id

Run the returned
```
upload
```
command in the shell, unchanged. It is a curl command against a presigned URL that is good for that one tarball until
```
expires_at
```
, so it carries no Rivet credentials.
Roll out, repeating until
```
done
```
is
```
true
```
.
js
```
return await rivet.deploy.rollout({ cluster: "my-cluster", build_id: "<build_id>" });
```
Each call advances one step and returns immediately, so call it again while
```
done
```
is
```
false
```
. See
```
references/rollout.md
```
for each step, the errors, and how to roll back.
Report the
```
build_id
```
and the
```
endpoints
```
from the final result to the user. The
```
build_id
```
is what a later rollback needs.

在 shell 中构建 image 并测量大小。平台必须为

linux/amd64

。

docker build --platform linux/amd64 -t app .
docker image save app -o image.tar
wc -c < image.tar                        # content_length
openssl md5 -binary image.tar | base64   # content_md5

tar 包大小必须不超过 5 GiB。请测量将要上传的确切文件，因为任一值不一致都会导致构建验证失败。

return await rivet.deploy.prepare({
	cluster: "my-cluster",
	image: "app:latest",
	content_length: 48213504,
	content_md5: "1B2M2Y8AsgTpgAmY7PhCfg==",
});

content_length

是数字，不是字符串。如果 tar 包不名为

image.tar

，请传入

file

。保留返回的

build_id

。

在 shell 中原样运行返回的
```
upload
```
命令。这是一条针对预签名 URL 的 curl 命令，该 URL 在
```
expires_at
```
之前仅适用于对应的 tar 包，因此不包含 Rivet 凭据。
执行 rollout，重复调用直到
```
done
```
为
```
true
```
。
js
```
return await rivet.deploy.rollout({ cluster: "my-cluster", build_id: "<build_id>" });
```
每次调用都会推进一个步骤并立即返回，因此当
```
done
```
为
```
false
```
时应再次调用。有关每个步骤、错误及回滚方式，请参阅
```
references/rollout.md
```
。
向用户报告
```
build_id
```
和最终结果中的
```
endpoints
```
。后续回滚需要使用该
```
build_id
```
。

Rules

规则

Never rebuild or re-upload to retry a rollout. Call
```
rivet.deploy.rollout
```
again with the same
```
build_id
```
.
Use
```
rivet.deploy.*
```
for the whole deploy. Do not drive
```
rivet.cloud.v2.builds.*
```
or
```
rivet.cloud.v2.runnerPools.upsert
```
by hand, because an upsert replaces the pool's settings wholesale and would drop its allowlist.
Do not guess a
```
cluster
```
,
```
region
```
, or
```
pool
```
name. List them first.

rollout 失败时，绝不要重新构建或重新上传。使用相同的
```
build_id
```
再次调用
```
rivet.deploy.rollout
```
。
整个部署过程都应使用
```
rivet.deploy.*
```
。不要手动调用
```
rivet.cloud.v2.builds.*
```
或
```
rivet.cloud.v2.runnerPools.upsert
```
，因为 upsert 会整体替换 pool 的设置，从而丢失其 allowlist。
不要猜测
```
cluster
```
、
```
region
```
或
```
pool
```
的名称。请先列出它们。