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

# Déployer Mastra sur Kubernetes

Exécutez une application Mastra sur plusieurs pods [Kubernetes](https://kubernetes.io/) afin qu'elle puisse évoluer horizontalement derrière un équilibreur de charge. Chaque pod constituant un processus distinct, les pods doivent partager un service pub/sub et une base de données ; sans cela, les opérations démarrées sur un pod restent invisibles aux autres.

> **Info:** Ce guide explique comment déployer le [serveur Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-server). Si vous utilisez un [adaptateur de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) ou un [framework web](https://mastra.zisheng.pro/fr/docs/deployment/web-framework), suivez votre procédure habituelle de déploiement pour celui-ci.

> **Attention:** La prise en charge de plusieurs pods repose sur les [agents durables](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents), actuellement en **bêta**. Les API peuvent évoluer dans les versions mineures. Consultez les [limitations connues](#known-limitations) avant d'utiliser cette configuration en production.

## Avant de commencer

Vous aurez besoin des éléments suivants :

- Une [application Mastra](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart)
- Un cluster [Kubernetes](https://kubernetes.io/docs/setup/) et [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
- Un registre de conteneurs auquel votre cluster peut accéder pour télécharger des images
- Une instance [Redis](https://redis.io/) partagée, accessible depuis chaque pod
- Une base de données [PostgreSQL](https://www.postgresql.org/) partagée, accessible depuis chaque pod

## Pourquoi plusieurs pods nécessitent une infrastructure partagée

Un pod unique conserve l'état d'exécution dans sa propre mémoire. Cela fonctionne avec un seul pod, car chaque requête atteint le même processus. Avec plusieurs pods, ce fonctionnement n'est plus assuré : un navigateur peut recevoir un flux depuis le pod A, tandis que la requête suivante de l'utilisateur est acheminée vers le pod B, qui ne possède aucune trace de l'exécution sur le pod A.

Redis et Postgres assurent la continuité entre les pods :

- Le système **pub/sub** transmet les événements entre les pods. Lorsqu'un événement est publié sur un pod, les autres le reçoivent. Mastra utilise [`RedisStreamsPubSub`](https://mastra.zisheng.pro/fr/reference/pubsub/redis-streams), qui fournit également un mécanisme de bail par fil de discussion garantissant qu'un seul pod est propriétaire d'une conversation à la fois. Consultez la page [PubSub](https://mastra.zisheng.pro/fr/docs/server/pubsub).
- Le **stockage** conserve l'état d'exécution. Les [agents durables](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents) enregistrent chaque exécution sous forme d'instantané de Workflow, ce qui permet à n'importe quel pod de reprendre une exécution depuis la base de données après un redémarrage ou lorsqu'une requête est acheminée ailleurs.

## Configurer l'infrastructure partagée

Configurez l'instance `Mastra` pour utiliser Redis et Postgres. Lisez les informations de connexion depuis des variables d'environnement afin que la même image puisse s'exécuter dans chaque pod.

Installez les services requis :

**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
```

Configurez le système pub/sub, le stockage et un cache partagé sur l'instance `Mastra` :

```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!) }),
})
```

Le `cache` permet aux flux pouvant être repris de fonctionner entre plusieurs pods. Lorsqu'un client se reconnecte, il récupère dans ce cache les événements manqués ; celui-ci doit donc être partagé. Le cache en mémoire utilisé par défaut ne permet de récupérer les événements qu'au sein d'un même processus.

## Utiliser des agents durables

Un [`Agent`](https://mastra.zisheng.pro/fr/docs/agents/overview) standard conserve son flux et son état d'approbation dans la mémoire d'un seul pod. Ces données ne sont donc plus disponibles si une requête arrive sur un autre pod. Un [agent durable](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents) exécute la boucle agentique au sein d'un Workflow et conserve son état, ce qui permet à n'importe quel pod d'observer ou de reprendre la même exécution.

Encapsulez l'agent avec `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 })
```

Enregistrez l'agent durable auprès de l'instance `Mastra` ci-dessus. Son état d'exécution est désormais stocké dans Postgres et ses événements transitent par Redis ; l'exécution est donc accessible depuis chaque pod.

## Déployer

1. Compilez et conteneurisez le serveur Mastra, puis envoyez l'image vers votre registre. Suivez le guide du [serveur Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-server) pour la compilation et vérifiez que le serveur lit `process.env.PORT` et écoute sur `0.0.0.0`.

2. Stockez les chaînes de connexion partagées dans un 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. Appliquez un Deployment qui exécute l'image en lisant le Secret partagé. Commencez avec un seul réplicat afin que le premier pod crée lui-même le schéma de la base de données, puis augmentez le nombre de réplicats à l'étape suivante :

   ```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
   ```

   La valeur `resources.requests.cpu` est requise pour le HorizontalPodAutoscaler ci-dessous. Kubernetes calcule l'utilisation du processeur en divisant la consommation par la quantité demandée. Sans demande de ressources CPU, le mécanisme de mise à l'échelle automatique ne peut pas calculer de cible et n'ajuste pas le nombre de réplicats.

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

   Une fois le premier pod prêt, augmentez le nombre de réplicats :

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

   > **Remarque:** Chaque réplicat exécute la même image et se connecte aux mêmes instances Redis et Postgres. C'est cette infrastructure partagée, et non le nombre de pods, qui permet aux exécutions de passer d'un pod à l'autre.

4. Exposez le Deployment à l'aide d'un 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. Ajustez automatiquement le nombre de réplicats à l'aide d'un 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
   ```

   > **Remarque:** La mise à l'échelle automatique fondée sur l'utilisation du processeur nécessite que le [metrics-server](https://github.com/kubernetes-sigs/metrics-server) s'exécute dans le cluster. Les clusters gérés tels que GKE, EKS et AKS l'incluent. Ce n'est pas le cas des clusters locaux comme kind et minikube : vous devez donc d'abord l'y activer (par exemple avec `minikube addons enable metrics-server`).

6. Vérifiez que les pods sont en cours d'exécution :

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

   Redirigez le port du service dans un terminal. Cette commande reste exécutée au premier plan :

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

   Dans un second terminal, appelez l'API :

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

   Si vous obtenez une liste JSON de vos agents, le déploiement traite correctement les requêtes.

   > **Attention:** Configurez l'[authentification](https://mastra.zisheng.pro/fr/docs/server/auth) avant d'exposer publiquement vos points de terminaison.

## Diffusion en continu et reconnexion

Un agent durable publie les fragments du flux dans un canal propre à chaque exécution par l'intermédiaire du système pub/sub partagé. Après une déconnexion, un client se reconnecte en appelant `observe()` avec l'ID de l'exécution, puis récupère dans le cache partagé les fragments qu'il a manqués :

```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()
```

Comme l'état d'exécution se trouve dans Postgres et les événements dans Redis, la requête de reconnexion peut être traitée par n'importe quel pod, et pas seulement par celui qui a démarré l'exécution. Consultez la section [Flux pouvant être repris](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents).

Plusieurs clients peuvent observer simultanément la même exécution. Chaque appel à `observe()` reçoit l'intégralité du flux : un utilisateur qui le consulte depuis deux appareils, ou deux personnes qui suivent la même exécution, restent donc synchronisés.

## Approbation des Tools entre les pods

Un agent durable se met en pause lors de l'appel d'un Tool jusqu'à ce qu'une personne l'approuve. L'exécution suspendue étant enregistrée dans Postgres, l'approbation peut arriver sur n'importe quel pod, et pas seulement sur celui qui a démarré l'exécution.

Démarrez une exécution qui nécessite une approbation :

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

L'exécution est suspendue avant le lancement du Tool. Approuvez-la ensuite depuis n'importe quel pod :

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

Le pod qui traite l'approbation charge l'exécution suspendue depuis Postgres. Il exécute ensuite le Tool approuvé et publie le résultat par l'intermédiaire du système pub/sub partagé, afin qu'un client qui observe l'exécution en reçoive la suite. Consultez la section [Approbation des Tools](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents).

## Limitations connues

- La configuration en processus utilisée par défaut conserve l'état d'exécution dans la mémoire d'un seul pod et ne le partage pas entre les pods. Utilisez des [agents durables](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents) avec des instances Redis et Postgres partagées afin que la diffusion en continu, les approbations et la reconnexion fonctionnent entre les pods.
- La diffusion en continu, les approbations et la reconnexion entre les pods nécessitent le recours aux agents durables. Un agent standard conserve l'état d'exécution en mémoire et ne peut pas reprendre sur un autre pod.
- Lorsque plusieurs pods démarrent simultanément avec une base de données non initialisée, ils peuvent tenter de créer le schéma en même temps et l'un d'eux risque de ne pas démarrer. Commencez avec un seul réplicat afin que le schéma ne soit créé qu'une fois, puis augmentez le nombre de réplicats.
- Pour une configuration plus stricte, initialisez le schéma en dehors de l'application (par exemple à l'aide d'un Job Kubernetes ponctuel) et définissez `disableInit: true` sur le `PostgresStore` de chaque pod.

## Pages connexes

- [PubSub](https://mastra.zisheng.pro/fr/docs/server/pubsub)
- [Agents durables](https://mastra.zisheng.pro/fr/docs/long-running-agents/durable-agents)
- [Workers](https://mastra.zisheng.pro/fr/docs/deployment/workers) : répartissez le traitement en arrière-plan dans des conteneurs distincts sur Kubernetes
- [Guide de déploiement des Workers](https://mastra.zisheng.pro/fr/guides/deployment/mastra-workers) : manifestes Kubernetes complets pour l'orchestration, le planificateur et les Workers de tâches en arrière-plan
- [Serveur Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-server)
- [Présentation du déploiement](https://mastra.zisheng.pro/fr/docs/deployment/overview)