Kubernetes

Download Manifests

Download the self-host/k8s/engine directory from the Rivet repository:

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

Configure Engine

In 02-engine-configmap.yaml, set public_url to your engine’s external URL.

Configure PostgreSQL

In 11-postgres-secret.yaml, update the PostgreSQL password. See Using a Managed PostgreSQL Service for external databases.

Configure Admin Token

Generate a secure admin token and save it somewhere safe:

openssl rand -hex 32

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

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

Deploy

# Apply all manifests
kubectl apply -f .

# 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

Access the Engine

Visit /ui on your public_url to access the dashboard.

Create Kubernetes Manifests

Create these two manifest files:

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 120s for actors to finish; 130s provides buffer.
      # See: /docs/actors/versions#graceful-shutdown-sigterm
      terminationGracePeriodSeconds: 130
      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

Setup Environment

Put the following in rivetkit-secrets.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: rivetkit-secrets
  namespace: your-namespace
type: Opaque
stringData:
  RIVET_ENDPOINT: http://my-app:your-admin-token@your-engine.example.com
  RIVET_PUBLIC_ENDPOINT: http://my-app@your-engine.example.com

Apply Manifests

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

Configure RivetKit URL in Dashboard

After the service is deployed and reachable from the public internet:

1. Open the Rivet Engine dashboard in your browser.
2. Enter your admin token when prompted.
3. Create a namespace (or select an existing namespace) that matches your endpoint namespace (for example, my-app).
4. In the namespace sidebar, click Overview.
5. Click Add Provider, then choose Custom.
6. In the connect modal, select Serverless and click Next.
7. Go to Confirm Connection, enter your app endpoint (.../api/rivet), then click Add.