> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Deploy Mastra to Kubernetes

Run a Mastra application across multiple pods on [Kubernetes](https://kubernetes.io/), so it scales horizontally behind a load balancer. Because each pod is a separate process, the pods must share a pub/sub backend and a database, otherwise work started on one pod is invisible to the others.

> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.

> **Beta:** Multi-pod support relies on [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents). Breaking changes may occur without a major version bump until the API is stable. Read [Known limitations](#known-limitations) before you rely on this in production.

## Before you begin

You'll need:

- A [Mastra application](https://mastra.ai/guides/getting-started/quickstart)
- A [Kubernetes](https://kubernetes.io/docs/setup/) cluster and [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
- A container registry your cluster can pull from
- A shared [Redis](https://redis.io/) instance, reachable from every pod
- A shared [PostgreSQL](https://www.postgresql.org/) database, reachable from every pod

## Why multiple pods need shared infrastructure

A single pod keeps run state in its own memory. With one pod that's fine, because every request reaches the same process. Across pods it breaks: a browser might stream from pod A while the user's next request is routed to pod B, and pod B has no record of the run on pod A.

Redis and Postgres close that gap:

- **Pub/sub** carries events between pods. When an event is published on one pod, the others receive it. Mastra uses [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), which also provides the per-thread leasing that keeps a single pod as the owner of a conversation at a time. See [PubSub](https://mastra.ai/docs/server/pubsub).
- **Storage** persists run state. [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents) save each run as a workflow snapshot, so any pod can resume a run from the database after a restart or when a request is routed elsewhere.

## Configure shared infrastructure

Point the `Mastra` instance at Redis and Postgres. Read the connection details from environment variables so the same image runs in every pod.

Install the backends:

**npm**:

```bash
npm install @mastra/redis-streams @mastra/pg @mastra/redis ioredis
```

**pnpm**:

```bash
pnpm add @mastra/redis-streams @mastra/pg @mastra/redis ioredis
```

**Yarn**:

```bash
yarn add @mastra/redis-streams @mastra/pg @mastra/redis ioredis
```

**Bun**:

```bash
bun add @mastra/redis-streams @mastra/pg @mastra/redis ioredis
```

Configure pub/sub, storage, and a shared cache on the `Mastra` instance:

```typescript
import { Mastra } from '@mastra/core'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { RedisServerCache } from '@mastra/redis'
import { PostgresStore } from '@mastra/pg'
import Redis from 'ioredis'

export const mastra = new Mastra({
  // Carries events between pods, and provides
  // per-thread leases so one pod owns a conversation at a time.
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
  // Persists run state so any pod can resume a run.
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL!,
  }),
  // Shared event cache so a reconnecting client can replay missed chunks
  // from any pod, not only the one that started the run.
  cache: new RedisServerCache({ client: new Redis(process.env.REDIS_URL!) }),
})
```

The `cache` is what makes resumable streams work across pods. A reconnecting client replays missed events from this cache, so it must be shared. The default in-memory cache only serves replays within one process.

## Use durable agents

A plain [`Agent`](https://mastra.ai/docs/agents/overview) keeps its stream and approval state in one pod's memory, so those don't survive a request landing on another pod. A [durable agent](https://mastra.ai/docs/long-running-agents/durable-agents) runs the agentic loop inside a workflow and persists its state, so any pod can observe or resume the same run.

Wrap the agent with `createDurableAgent()`:

```typescript
import { Agent } from '@mastra/core/agent'
import { createDurableAgent } from '@mastra/core/agent/durable'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.6-sol',
})

export const durableAssistant = createDurableAgent({ agent })
```

Register the durable agent with the `Mastra` instance above. Its run state now lives in Postgres and its events flow through Redis, so the run is reachable from every pod.

## Deploy

1. Build and containerize the Mastra server, then push the image to your registry. Follow the [Mastra server](https://mastra.ai/docs/server/mastra-server) guide for the build, and ensure the server reads `process.env.PORT` and listens on `0.0.0.0`.

2. Store the shared connection strings as a Secret:

   ```bash
   kubectl create secret generic mastra-secrets \
     --from-literal=REDIS_URL='redis://redis:6379' \
     --from-literal=DATABASE_URL='postgresql://user:pass@postgres:5432/mastra'
   ```

3. Apply a Deployment that runs the image, reading the shared Secret. Start with one replica so the first pod creates the database schema on its own, then scale up in the next step:

   ```yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: mastra
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: mastra
     template:
       metadata:
         labels:
           app: mastra
       spec:
         containers:
           - name: mastra
             image: your-registry/mastra:latest
             ports:
               - containerPort: 8080
             env:
               - name: PORT
                 value: '8080'
             envFrom:
               - secretRef:
                   name: mastra-secrets
             readinessProbe:
               tcpSocket:
                 port: 8080
             livenessProbe:
               tcpSocket:
                 port: 8080
             resources:
               requests:
                 cpu: 500m
                 memory: 512Mi
   ```

   The `resources.requests.cpu` value is required for the HorizontalPodAutoscaler below. Kubernetes calculates CPU utilization as usage divided by the requested amount, so without a CPU request the autoscaler can't compute a target and won't scale.

   ```bash
   kubectl apply -f deployment.yaml
   ```

   Once the first pod is ready, scale up:

   ```bash
   kubectl wait --for=condition=available deployment/mastra
   kubectl scale deployment/mastra --replicas=3
   ```

   > **Note:** Every replica runs the same image and connects to the same Redis and Postgres. That shared infrastructure, not the pod count, is what lets runs cross pods.

4. Expose the Deployment with a Service:

   ```yaml
   apiVersion: v1
   kind: Service
   metadata:
     name: mastra
   spec:
     selector:
       app: mastra
     ports:
       - port: 80
         targetPort: 8080
   ```

   ```bash
   kubectl apply -f service.yaml
   ```

5. Scale the replicas automatically with a HorizontalPodAutoscaler:

   ```yaml
   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: mastra
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: mastra
     minReplicas: 3
     maxReplicas: 10
     metrics:
       - type: Resource
         resource:
           name: cpu
           target:
             type: Utilization
             averageUtilization: 70
   ```

   ```bash
   kubectl apply -f hpa.yaml
   ```

   > **Note:** CPU-based autoscaling needs the [metrics-server](https://github.com/kubernetes-sigs/metrics-server) running in the cluster. Managed clusters like GKE, EKS, and AKS include it. Local clusters like kind and minikube don't, so enable it there first (for example, `minikube addons enable metrics-server`).

6. Verify the pods are running:

   ```bash
   kubectl get pods -l app=mastra
   ```

   Forward the service in one terminal. This command stays in the foreground:

   ```bash
   kubectl port-forward service/mastra 8080:80
   ```

   In a second terminal, call the API:

   ```bash
   curl http://localhost:8080/api/agents
   ```

   A JSON list of your agents means the deployment is serving.

   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.

## Streaming and reconnection

A durable agent publishes stream chunks to a per-run topic through the shared pub/sub. A client that disconnects reconnects by calling `observe()` with the run's ID, and replays the chunks it missed from the shared cache:

```typescript
const { output, cleanup } = await durableAssistant.observe(runId)

for await (const chunk of output.fullStream) {
  // Chunks from the run, including any missed while disconnected
}

cleanup()
```

Because the run state is in Postgres and the events are in Redis, the reconnecting request can be served by any pod, not only the one that started the run. See [Resumable streams](https://mastra.ai/docs/long-running-agents/durable-agents).

Multiple clients can observe the same run at once. Each `observe()` call receives the full stream, so a user watching from two devices, or two people following the same run, stay in sync.

## Tool approval across pods

A durable agent pauses on a tool call until a human approves it. Because the suspended run is saved to Postgres, the approval can arrive on any pod, not only the one that started the run.

Start a run that requires approval:

```typescript
const { runId } = await durableAssistant.stream('Delete the archived records', {
  requireToolApproval: true,
  memory: { thread: 'thread-1', resource: 'user-1' },
})
```

The run suspends before the tool runs. Approve it later, from any pod:

```typescript
await durableAssistant.resume(runId, { approved: true })
```

The pod that handles the approval loads the suspended run from Postgres. It then runs the approved tool and publishes the result over the shared pub/sub, so a client observing the run receives the continuation. See [Tool approval](https://mastra.ai/docs/long-running-agents/durable-agents).

## Known limitations

- The default in-process setup keeps run state in one pod's memory and doesn't share it across pods. Use [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents) with shared Redis and Postgres so streaming, approvals, and reconnection work across pods.
- Cross-pod streaming, approvals, and reconnection require the durable-agent path. A plain agent keeps run state in memory and doesn't resume on another pod.
- When multiple pods start at once against an uninitialized database, they can race to create the schema and a pod may fail to start. Start with one replica so the schema is created once, then scale up.
- For a stricter setup, initialize the schema outside the app (for example, a one-off Kubernetes Job) and set `disableInit: true` on the `PostgresStore` in every pod.

## Related

- [PubSub](https://mastra.ai/docs/server/pubsub)
- [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
- [Workers](https://mastra.ai/docs/deployment/workers): Split background processing into separate containers on Kubernetes
- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Full Kubernetes manifests for orchestration, scheduler, and background task workers
- [Mastra server](https://mastra.ai/docs/server/mastra-server)
- [Deployment overview](https://mastra.ai/docs/deployment/overview)