docs(self-host): document autoscaling for every platform

Author: Nathan Flurry

src/content/self-host/control-plane/aws-ecs.mdx

@@ -145,6 +145,8 @@ Use `normal` for long-lived workers. See <SelfHostLink to="workers">Runner confi
 
 EFS-backed file system storage is single-node: RocksDB cannot be shared between tasks. Before raising the desired count above one, move to RDS PostgreSQL and add NATS for pub/sub. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
 
+Once on RDS, ECS Service Auto Scaling can drive the desired count. Use target tracking on average CPU at 60%, matching the <SelfHostLink to="control-plane/kubernetes">Kubernetes</SelfHostLink> manifests, and keep a minimum of two tasks so the service survives losing one. Leave the desired count at one for as long as the task is on EFS.
+
 ## Next steps
 
 - <SelfHostLink to="control-plane/production-checklist">Production checklist</SelfHostLink>

src/content/self-host/control-plane/custom.mdx

@@ -48,7 +48,7 @@ docker run -d \
   rivetdev/engine:2.3.3
 ```
 
-For multi-node, drop the file system variable and set `RIVET__POSTGRES__URL` instead. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
+For multi-node, drop the file system variable, set `RIVET__POSTGRES__URL` instead, and add NATS for pub/sub. Do not replicate or autoscale a node that is still on the file system backend: RocksDB is single-node. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
 
 </Step>
 

src/content/self-host/control-plane/docker-compose.mdx

@@ -147,7 +147,7 @@ volumes:
   postgres-data:
 ```
 
-Multi-node deployments also need NATS. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
+This file still runs a single engine container, so it is not yet a multi-node deployment. It is the prerequisite for one: the file system backend is single-node RocksDB and cannot be shared, while PostgreSQL can. Multi-node deployments also need NATS. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
 
 ## Using a config file
 

src/content/self-host/control-plane/kubernetes.mdx

@@ -114,6 +114,18 @@ To use Amazon RDS, Cloud SQL, or Azure Database instead of the bundled Postgres:
 
 Use the direct connection string, not a pooled one. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
 
+## Autoscaling
+
+`05-rivet-engine-hpa.yaml` is a HorizontalPodAutoscaler on the engine Deployment. It scales between **2 and 10 replicas**, targeting **60% average CPU** and **80% average memory**.
+
+```bash
+kubectl -n rivet-engine get hpa rivet-engine
+```
+
+It needs the metrics server from the requirements above. Without it the targets read `<unknown>` and the HPA never scales.
+
+Autoscaling is only safe here because this bundle runs on PostgreSQL and NATS. The file system (RocksDB) backend is single-node, so an engine using it must stay at one replica. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
+
 ## Applying configuration changes
 
 The ConfigMap is read at startup, so a change needs a restart:

src/content/self-host/control-plane/production-checklist.mdx

@@ -23,7 +23,7 @@ We recommend passing this page to your coding agent to verify your configuration
 
 - **Run two or more nodes.** A single control plane node is a single point of failure. Deploy at least two behind a load balancer.
 - **Do not run multiple file system nodes.** RocksDB is single-node. Multi-node deployments need PostgreSQL or FoundationDB. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
-- **Configure autoscaling.** Target 70% CPU and 80% memory to leave headroom for traffic spikes. In Kubernetes this is a Horizontal Pod Autoscaler.
+- **Configure autoscaling, on a shared backend only.** Target 60% CPU and 80% memory to leave headroom for traffic spikes. In Kubernetes this is a Horizontal Pod Autoscaler, and the shipped manifests include one at 2 to 10 replicas. Never autoscale a node on the file system backend: adding replicas to a single-node RocksDB deployment corrupts it.
 - **Check the rate limit on your serverless worker platform.** Actor start requests all originate from your control plane nodes, so they come from a small set of IPs. Per-IP rate limits throttle the control plane long before they would throttle end-user traffic. Size the limit to your peak actor create and wake rate.
 
 ## Storage

src/content/self-host/control-plane/railway.mdx

@@ -84,6 +84,10 @@ If your start command is a wrapper (`npm start`, `yarn start`, a shell script),
 
 Railway's HTTP proxy supports WebSockets. If you add your own reverse proxy inside the service, raise its idle and read timeouts to `3600`. See <SelfHostLink to="control-plane/ports">Ports</SelfHostLink>.
 
+## Scaling past one instance
+
+Both templates provision a single control plane service on PostgreSQL, which is a fine starting point. Before raising the replica count, add NATS for pub/sub so replicas coordinate. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
+
 ## Next steps
 
 - <SelfHostLink to="control-plane/production-checklist">Production checklist</SelfHostLink>

src/content/self-host/control-plane/render.mdx

@@ -137,6 +137,8 @@ Render's proxy supports WebSockets but closes connections that sit idle past its
 
 The blueprint above is a single instance on managed PostgreSQL, which is a fine starting point. Before scaling out, add NATS for pub/sub so instances coordinate. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>.
 
+With NATS in place, instance count can be raised or handed to Render's autoscaling on a CPU target. Target 60% CPU, matching the <SelfHostLink to="control-plane/kubernetes">Kubernetes</SelfHostLink> manifests, and keep a minimum of two instances. Autoscaling a control plane that is still on the file system backend corrupts it, but that does not apply here: this blueprint is on PostgreSQL from the start.
+
 ## Next steps
 
 - <SelfHostLink to="control-plane/production-checklist">Production checklist</SelfHostLink>

src/content/self-host/control-plane/vm.mdx

@@ -98,6 +98,8 @@ From a container on the same host, use `host.docker.internal` instead of the hos
 
 ## Using PostgreSQL
 
+The file system backend above is RocksDB on local disk: single-node, and impossible to share between hosts. Scaling past one control plane node means moving to PostgreSQL first, then adding NATS for pub/sub. See <SelfHostLink to="control-plane/storage">Storage</SelfHostLink>. The commands below are still one engine container on one host; PostgreSQL is what makes adding a second host possible later.
+
 ```bash
 docker network create rivet-net
 

src/content/self-host/workers/aws-ecs.mdx

@@ -42,6 +42,12 @@ Once tasks are running they appear under **Runners** in the dashboard. Nothing n
 
 <ProductSlot name="verify" />
 
+## Autoscaling
+
+Runner-mode tasks are interchangeable, so ECS Service Auto Scaling can drive the desired count. Use target tracking on `ECSServiceAverageCPUUtilization` at 60%, with a minimum of two tasks.
+
+Scale-in is the caveat. It is bound by the same 120 second `stopTimeout` cap, so actors on a removed task are cut off rather than drained. Set a long scale-in cooldown, or leave the desired count fixed and change capacity at deploy time instead.
+
 ## Next steps
 
 - <SelfHostLink to="workers/production-checklist">Production checklist</SelfHostLink>

src/content/self-host/workers/cloudflare.mdx

@@ -60,6 +60,10 @@ Set the Worker URL with the `/api/rivet` path as the serverless runner URL in th
 
 <ProductSlot name="verify" />
 
+## Scaling
+
+Cloudflare autoscales Workers for you: there are no instances or replicas to configure. The one scaling bound you own is `maxConcurrentActors` on the serverless runner config, which caps concurrent actors across the whole pool and defaults to `1000`. See <SelfHostLink to="workers/production-checklist">the production checklist</SelfHostLink>.
+
 ## Next steps
 
 - <SelfHostLink to="workers/production-checklist">Production checklist</SelfHostLink>