Rivet.Cloud reference

Cluster

Source: packages/rivet/src/Cloud/Cluster.ts

A Rivet Cloud cluster, read with the signed-in account: its engine endpoint and admin token. Rivet Cloud creates and deletes clusters in its dashboard; this resource only reads one, and destroying it leaves the cluster as it is. RivetCloud.ControlPlane uses it.

Cluster: Reading a cluster

const cluster = yield* RivetCloud.Cluster("Rivet", {});

ControlPlane

Source: packages/rivet/src/Cloud/ControlPlane.ts

A Rivet Cloud cluster, as a Rivet.Cluster Layer. Rivet runs the control plane; your pools of nodes run wherever their pool Layer puts them and connect out to it. Each stage gets a namespace of its own on the cluster.

Deploys sign in to Rivet Cloud with the RivetCloud profile (a browser sign-in, or a cluster token), or with RIVET_CLOUD_TOKEN and RIVET_CLOUD_CLUSTER in CI. Self-hosted control planes need neither.

ControlPlane: Connecting to Rivet Cloud

The cluster chosen at sign-in

export const Cluster = RivetCloud.ControlPlane("Rivet");
export const Default = RivetAWS.EcsPool("Default").pipe(Layer.provide(Cluster));

A cluster by its name

export const Cluster = RivetCloud.ControlPlane("Rivet", { cluster: "acme" });

Pool

Source: packages/rivet/src/Cloud/Pool.ts

Run a pool’s nodes on Rivet Cloud: a pool on the cluster’s control plane, and a Rivet Cloud runner pool whose nodes host every Rivet.DurableObject given this pool. Requires a RivetCloud.ControlPlane.

Each deploy whose classes changed builds a Docker image of the node program with the local docker CLI and uploads it to Rivet Cloud, so deploying needs Docker. Rivet Cloud runner pools take no environment of their own: the stage’s namespace and the classes’ environment, secrets included, are baked into the image Rivet stores.

Rivet Cloud runs one runner pool per cluster for now, so one stage at a time can host its nodes there: a second stage’s deploy is refused, as the runner pool belongs to another. Give other stages a cluster of their own, or a pool on another cloud.

Every Durable Object given the same pool shares its nodes: declare the pool once and provide it to each class.

Pool: Running Durable Objects on Rivet Cloud

Rivet runs the control plane and the nodes

export const Cluster = RivetCloud.ControlPlane("Rivet");
export const Default = RivetCloud.Pool("Default").pipe(Layer.provide(Cluster));

A bigger machine

export const Default = RivetCloud.Pool("Default", { machineType: "e2-medium" }).pipe(
  Layer.provide(Cluster),
);

RunnerPool

Source: packages/rivet/src/Cloud/RunnerPool.ts

Nodes Rivet Cloud runs for you: a runner pool on a Rivet Cloud cluster, booted from a Docker image of the node program. Each deploy whose program or environment changed builds the image with the local docker CLI, uploads it as a build, and rolls the pool out to it.

RivetCloud.Pool declares one for its Durable Objects; declare this directly only to run a node program of your own.

RunnerPool: Running nodes on Rivet Cloud

const pool = yield* RivetCloud.RunnerPool("Default", {
  cluster: "acme",
  main: "./dist/node.mjs",
  rivetkitVersion: "3.0.0",
  env: { RIVET_NAMESPACE: "acme-prod", RIVET_POOL: "acme-prod-default" },
});