Kubernetes

Prerequisites

• Kubernetes cluster
• kubectl configured
• Metrics server (required for HPA) — included by default in most distributions (k3d, GKE, EKS, AKS)

Deploy Rivet Engine

```bash
npx giget@latest gh:rivet-dev/rivet/self-host/k8s/engine rivet-k8s
cd rivet-k8s
```

```bash
openssl rand -hex 32
```

Create the namespace and store the token as a Kubernetes secret:

```bash
kubectl create namespace rivet-engine
kubectl -n rivet-engine create secret generic rivet-secrets --from-literal=admin-token=YOUR_TOKEN_HERE
```

# Wait for all pods to be ready
kubectl -n rivet-engine wait --for=condition=ready pod -l app=nats --timeout=300s
kubectl -n rivet-engine wait --for=condition=ready pod -l app=postgres --timeout=300s
kubectl -n rivet-engine wait --for=condition=ready pod -l app=rivet-engine --timeout=300s

# Verify all pods are running
kubectl -n rivet-engine get pods
```

Connecting Your Project

Follow the quickstart to create a working server with actors.

Create these manifest files for your app:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rivetkit-app
  namespace: your-namespace
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rivetkit-app
  template:
    metadata:
      labels:
        app: rivetkit-app
    spec:
      # Allow enough time for actors to gracefully stop on SIGTERM.
      # The runner waits up to 30m for actors to finish.
      # Add buffer for runner shutdown overhead after actors stop.
      # See: /docs/actors/versions#graceful-shutdown-sigterm
      terminationGracePeriodSeconds: 2100
      containers:
        - name: rivetkit-app
          image: registry.example.com/your-team/rivetkit-app:latest
          envFrom:
            - secretRef:
                name: rivetkit-secrets

apiVersion: v1
kind: Service
metadata:
  name: rivetkit-app
  namespace: your-namespace
spec:
  selector:
    app: rivetkit-app
  ports:
    - name: http
      port: 8080
      targetPort: 8080

Create rivetkit-secrets.yaml with RIVET_ENDPOINT pointing to the engine. This tells your app to connect as a runner instead of running standalone. See Endpoints for all options.

apiVersion: v1
kind: Secret
metadata:
  name: rivetkit-secrets
  namespace: your-namespace
type: Opaque
stringData:
  RIVET_ENDPOINT: http://my-app:[email protected]

kubectl apply -f rivetkit-secrets.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

1. Open the Rivet Engine dashboard in your browser.
2. Enter your admin token when prompted.
3. In the namespace sidebar, click Settings.
4. Click Add Provider, then choose Custom.
5. Click Next.
6. Go to Confirm Connection, enter your app endpoint (e.g. http://rivetkit-app.your-namespace:8080/api/rivet), then click Add.

Register your runner programmatically via the engine API:

curl -X PUT "https://your-engine.example.com/runner-configs/default?namespace=default" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-admin-token" \
  -d '{
    "datacenters": {
      "default": {
        "normal": {}
      }
    }
  }'

Advanced

Using a Managed PostgreSQL Service

If you prefer to use a managed PostgreSQL service (e.g. Amazon RDS, Cloud SQL, Azure Database) instead of the bundled Postgres deployment:

• Update the postgres.url connection string in 02-engine-configmap.yaml to point to your managed instance
• Delete the bundled PostgreSQL manifests:
  • 10-postgres-configmap.yaml
  • 11-postgres-secret.yaml
  • 12-postgres-statefulset.yaml
  • 13-postgres-service.yaml

Applying Configuration Updates

When making subsequent changes to 02-engine-configmap.yaml, restart the engine pods to pick up the new configuration:

kubectl apply -f 02-engine-configmap.yaml
kubectl -n rivet-engine rollout restart deployment/rivet-engine

Ingress and Load Balancer Timeouts

Rivet uses long-lived WebSocket connections for both client traffic (browsers, SDKs) and envoy traffic (actor hosts connecting back to the engine). Default Ingress and cloud load balancer idle timeouts (typically 30 to 60 seconds) drop these connections and cause reconnect storms.

Raise the idle / read / send timeout on every Ingress and load balancer in front of the engine to at least 1 hour (3600 seconds). Examples:

• NGINX Ingress (annotations on the Ingress):

  yamlCopy

  nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
  

• AWS Load Balancer Controller (ALB):

  yamlCopy

  alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600
  

• GCE Ingress (GKE): set timeoutSec: 3600 on the BackendConfig referenced by the Service.

The same guidance applies to the load balancer fronting your RivetKit app, since envoys connect to it over WebSocket.

Next Steps

• Review the Production Checklist before going live
• See Configuration for all engine config options