ContextQMD
Back to Rivet

Kubernetes

website/src/content/docs/self-hosting/kubernetes.mdx

2.2.15.7 KB
Original Source
<Warning> PostgreSQL is the recommended backend for multi-node self-hosted deployments today, but it remains experimental. For a production-ready single-node Rivet deployment, use the file system backend (RocksDB-based). Enterprise teams can contact [enterprise support](https://rivet.dev/sales) about FoundationDB for the most scalable production-ready deployment. </Warning>

Prerequisites

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

Deploy Rivet Engine

<Steps> <Step title="Download Manifests"> Download the `self-host/k8s/engine` directory from the Rivet repository: 
```bash
npx giget@latest gh:rivet-dev/rivet/self-host/k8s/engine rivet-k8s
cd rivet-k8s
```
</Step> <Step title="Configure Engine"> In `02-engine-configmap.yaml`, set `public_url` to your engine's external URL. </Step> <Step title="Configure PostgreSQL"> In `11-postgres-secret.yaml`, update the PostgreSQL password. See [Using a Managed PostgreSQL Service](#using-a-managed-postgresql-service) for external databases. </Step> <Step title="Configure Admin Token"> Generate a secure admin token and save it somewhere safe: 
```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
```
</Step> <Step title="Deploy"> ```bash # 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
```
</Step> <Step title="Access the Engine"> Visit `/ui` on your `public_url` to access the dashboard. </Step> </Steps>

Connecting Your Project

<Steps> <Step title="Create your server">

Follow the quickstart to create a working server with actors.

</Step> <Step title="Create Kubernetes manifests">

Create these manifest files for your app:

<CodeGroup>
yaml
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
yaml
apiVersion: v1
kind: Service
metadata:
  name: rivetkit-app
  namespace: your-namespace
spec:
  selector:
    app: rivetkit-app
  ports:
    - name: http
      port: 8080
      targetPort: 8080
</CodeGroup> </Step> <Step title="Configure the endpoint">

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.

yaml
apiVersion: v1
kind: Secret
metadata:
  name: rivetkit-secrets
  namespace: your-namespace
type: Opaque
stringData:
  RIVET_ENDPOINT: http://my-app:[email protected]
</Step> <Step title="Deploy your app">
bash
kubectl apply -f rivetkit-secrets.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
</Step> <Step title="Register your runner with the engine"> <Tabs> <Tab title="Dashboard">
  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.
</Tab> <Tab title="CLI (curl)">

Register your runner programmatically via the engine API:

bash
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": {}
      }
    }
  }'
</Tab> </Tabs> </Step> </Steps>

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:

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

Next Steps