Node Pools

Upsert Node Pool

Create or replace a node pool's configuration.

Every field is optional and omitted fields take their defaults, so a request replaces the whole configuration. Unknown fields are rejected. Serverless pools are not supported. Nodes pick up the new configuration on their next connection. A namespace token needs a grant on pool with update.

PUT https://rivet.example.com/pools/{pool}

Examples

curl -X PUT "https://rivet.example.com/pools/default?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "drain_on_version_upgrade": true,
    "actor_eviction_delay": 0,
    "actor_eviction_period": 0,
    "actor_eviction_rate": 1
  }'

Authentication

Send the admin token, or a namespace token from Create Token whose grants cover the request, as a bearer token in the Authorization header. The x-rivet-token header is also accepted. Routes with a namespace query parameter use the default namespace when it is omitted. See Authentication.

Path Parameters

Name	Type	Required	Description
`pool`	`string`	Yes	Name of the node pool. A DNS label of 1 to 63 lowercase letters, digits and hyphens.

Query Parameters

Name	Type	Required	Description
`namespace`	`string`	No	Name of the namespace to operate in. Defaults to `default`.

Request Body

Content type: application/json.

Field	Type	Required	Description
`drain_on_version_upgrade`	`boolean`	No	Drain nodes running an older version when a newer version connects.
`actor_eviction_delay`	`integer`	No	Seconds to wait before evicting actors from a draining node.
`actor_eviction_period`	`integer`	No	Seconds over which actors are evicted from a draining node.
`actor_eviction_rate`	`number`	No	Rate at which actors are evicted from a draining node. Must be finite and greater than 0.
`metadata`	`any`	No	Opaque JSON stored with the pool, at most 16 KiB when serialized.

Responses

200

The stored node pool.

Field	Type	Description
`pool`	`object`
`pool.name`	`string`	Name of the node pool.
`pool.drain_on_version_upgrade`	`boolean`	Drain nodes running an older version when a newer version connects.
`pool.actor_eviction_delay`	`integer`	Seconds to wait before evicting actors from a draining node.
`pool.actor_eviction_period`	`integer`	Seconds over which actors are evicted from a draining node.
`pool.actor_eviction_rate`	`number`	Rate at which actors are evicted from a draining node. Must be finite and greater than 0.
`pool.metadata`	`any`	Opaque JSON stored with the pool, or `null` when unset.

{
  "pool": {
    "name": "default",
    "drain_on_version_upgrade": false,
    "actor_eviction_delay": 0,
    "actor_eviction_period": 0,
    "actor_eviction_rate": 0,
    "metadata": null
  }
}

400

pool.invalid: the body has an unknown field or a value out of range. pool.serverless_unsupported: the body sets serverless or kind: "serverless". envoy.invalid_pool_name: the pool name is not valid. envoy.invalid_namespace_name: the namespace value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens. A body that is not valid JSON is rejected with a plain-text 400.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "pool",
  "code": "invalid",
  "message": "Node pool configuration is invalid."
}

401

auth.invalid_token: the request carries no token, or the token is not valid. auth.token_expired: the token has expired.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

403

auth.insufficient_permissions: the token’s grants do not cover this request.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "insufficient_permissions",
  "message": "Insufficient permissions to access this resource."
}

404

namespace.not_found: the namespace does not exist.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "namespace",
  "code": "not_found",
  "message": "The namespace does not exist."
}

415

The request is missing the Content-Type: application/json header. Returned as plain text.

Content type: text/plain.

500

core.internal_error: an unexpected failure. Details are only logged on the server.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "core",
  "code": "internal_error",
  "message": "An internal error occurred"
}

503

auth.verification_unavailable: token verification keys are temporarily unavailable. Retry the request.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "verification_unavailable",
  "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
}