Déploiements gérés

Un déploiement géré exécute votre worker de workflows pour vous. Vous indiquez un dépôt GitHub à Mistral. Mistral Cloud construit une image Docker à partir du Dockerfile du dépôt et exécute le conteneur. Vous ne gérez jamais de serveurs, et vous ne créez pas de clé API pour le worker.

Chaque déploiement géré s'exécute sous son propre compte de service. Aucune clé API n'est provisionnée pour le worker.

La plateforme monte un token de compte de service rotatif dans le conteneur sous forme de fichier et définit MISTRAL_SA_TOKEN_PATH avec son emplacement. Le SDK Workflows lit le token dans ce fichier et prend en compte chaque rotation automatiquement. Votre code ne gère pas les identifiants.

Les déploiements gérés clonent votre code via l'application GitHub de Mistral. Deux éléments doivent être en place avant de déployer :

1. Installez l'application GitHub de Mistral sur les dépôts depuis lesquels vous souhaitez déployer. Accédez à github.com/apps/mistralai, cliquez sur Configurer, sélectionnez votre organisation et choisissez les dépôts.
2. Connectez GitHub dans la console. Ouvrez Studio›Build›Connectors ↗, ouvrez le connecteur Github et ajoutez des identifiants.

La liste des dépôts affichée lors de la création d'un déploiement contient uniquement les dépôts où l'application est installée et auxquels votre compte peut accéder. Si un dépôt n'apparaît pas dans la liste, c'est que l'application n'y est pas installée. Pour un dépôt d'organisation que vous n'administrez pas, demandez à un propriétaire de l'organisation d'installer l'application.

1. Ouvrez Studio›Build›Workflows›Deployments ↗ et créez un nouveau déploiement.
2. Choisissez un nom de déploiement unique. Deux déploiements portant le même nom se volent leurs exécutions.
3. Collez l'URL du dépôt GitHub et sélectionnez la branche à déployer.
4. Si le Dockerfile ne se trouve pas à la racine du dépôt ou ne s'appelle pas Dockerfile, définissez dockerfile_path et build_directory dans la section Configuration avancée.
5. Attendez que le déploiement passe à l'état Actif. Cela signifie que le worker a enregistré ses workflows, qui sont listés sur la page du déploiement. Si le build échoue, ouvrez les détails du déploiement pour consulter l'erreur.
6. Exécutez un workflow depuis la page Workflows.

Pour redéployer à partir du commit le plus récent de la branche configurée, utilisez Mettre à jour sur le déploiement.

Mistral Cloud clone le dépôt, construit une image Docker et exécute l'image telle quelle. Il n'existe pas de paramètre entrypoint : les instructions ENTRYPOINT/CMD de l'image doivent démarrer le worker, par exemple python worker.py, qui appelle run_worker([...]).

La plateforme injecte tout ce dont le worker a besoin pour se connecter : DEPLOYMENT_NAME, SERVER_URL et le fichier de token de compte de service indiqué par MISTRAL_SA_TOKEN_PATH. La façon dont l'image installe les dépendances dépend de votre Dockerfile — la commande du conteneur doit seulement démarrer le worker.

Exemple d'arborescence pour un worker situé à la racine du dépôt, démarré par worker.py :

my-worker/
├── Dockerfile
├── pyproject.toml
├── uv.lock
├── worker.py
└── workflows/
    └── hello.py

my-worker/
├── Dockerfile
├── pyproject.toml
├── uv.lock
├── worker.py
└── workflows/
    └── hello.py

Exemple de Dockerfile :

FROM ghcr.io/astral-sh/uv:0.11.16 AS uv

FROM python:3.12-slim AS builder

COPY --from=uv /uv /bin/uv

ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1

WORKDIR /app

COPY . .
RUN uv sync --frozen --no-dev

FROM python:3.12-slim

WORKDIR /app
COPY --from=builder /app /app

ENV PATH="/app/.venv/bin:$PATH" \
    PYTHONUNBUFFERED=1

RUN useradd --uid 1001 --create-home worker && chown -R 1001 /app
USER 1001

CMD ["/app/.venv/bin/python", "worker.py"]

FROM ghcr.io/astral-sh/uv:0.11.16 AS uv

FROM python:3.12-slim AS builder

COPY --from=uv /uv /bin/uv

ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1

WORKDIR /app

COPY . .
RUN uv sync --frozen --no-dev

FROM python:3.12-slim

WORKDIR /app
COPY --from=builder /app /app

ENV PATH="/app/.venv/bin:$PATH" \
    PYTHONUNBUFFERED=1

RUN useradd --uid 1001 --create-home worker && chown -R 1001 /app
USER 1001

CMD ["/app/.venv/bin/python", "worker.py"]

L'étape finale s'exécute avec un utilisateur non root : la plateforme exécute l'image telle quelle, donc l'instruction USER du Dockerfile définit l'utilisateur d'exécution.

La plupart des échecs de build sont de simples échecs de build Docker ou de démarrage. Vous pouvez reproduire le build sur votre machine avec le même contexte et le même Dockerfile :

docker build -t my-worker .   # run from build_directory if the worker is in a subdirectory
docker run --rm \
  -e MISTRAL_API_KEY \
  -e DEPLOYMENT_NAME=my-worker-local \
  my-worker

docker build -t my-worker .   # run from build_directory if the worker is in a subdirectory
docker run --rm \
  -e MISTRAL_API_KEY \
  -e DEPLOYMENT_NAME=my-worker-local \
  my-worker

La variable MISTRAL_API_KEY est transmise depuis votre shell. Une fois définie, le worker se connecte à https://api.mistral.ai et enregistre réellement ses workflows. Utilisez un DEPLOYMENT_NAME différent de celui de votre déploiement en production : un worker local portant le même nom lui volerait ses exécutions.

Les workers ont souvent besoin d'identifiants, par exemple un token pour une API externe. Les déploiements gérés les lisent depuis le Secrets Manager de l'espace de travail.

1. Créez d'abord le secret dans la console, dans la section Studio›Secrets ↗.
2. Liez-le au déploiement. Chaque liaison associe une variable d'environnement à un secret.

curl -X POST "https://api.mistral.ai/v1/workflows/deployments" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-worker",
    "spec": {
      "github_url": "https://github.com/acme/my-worker",
      "revision": "main",
      "backend_spec": {
        "type": "koyeb",
        "secrets": [
          {
            "env_var_name": "GITHUB_TOKEN",
            "reference": "secret:workspace:github_token"
          }
        ]
      }
    }
  }'

curl -X POST "https://api.mistral.ai/v1/workflows/deployments" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-worker",
    "spec": {
      "github_url": "https://github.com/acme/my-worker",
      "revision": "main",
      "backend_spec": {
        "type": "koyeb",
        "secrets": [
          {
            "env_var_name": "GITHUB_TOKEN",
            "reference": "secret:workspace:github_token"
          }
        ]
      }
    }
  }'

Seules les références limitées à l'espace de travail (secret:workspace:<NAME>) sont prises en charge. Pour modifier les liaisons, envoyez PATCH /v1/workflows/deployments/{name} avec la liste complète : la liste entière redéfinit les liaisons, une liste vide supprime toutes les liaisons, et si vous l'omettez, les liaisons restent inchangées. Les valeurs des secrets sont lues au démarrage — redémarrez le déploiement pour prendre en compte une valeur modifiée.

Chaque liaison est également transmise au build Docker sous forme d'argument de build portant le même nom. Déclarez un ARG correspondant dans le Dockerfile pour l'utiliser, par exemple pour installer des paquets depuis un registre privé :

ARG UV_INDEX_USERNAME
ARG UV_INDEX_PASSWORD

RUN uv sync --frozen --no-dev

ARG UV_INDEX_USERNAME
ARG UV_INDEX_PASSWORD

RUN uv sync --frozen --no-dev

Les arguments de build sont stockés dans l'historique et les couches de l'image, donc toute personne pouvant accéder à l'image peut récupérer les valeurs. Privilégiez des identifiants que vous pouvez renouveler, et évitez de lier des secrets sensibles pour les builds.

Chaque organisation dispose d'un plafond sur le nombre de déploiements gérés pouvant s'exécuter simultanément :

La création ou le démarrage d'un déploiement au-delà du plafond échoue avec une erreur 403. Arrêtez ou supprimez un déploiement pour libérer une place. Les plafonds peuvent être relevés par organisation — contactez l'assistance Mistral.

Mistral Cloud choisit également la taille d'instance pour vous. Tous les workers gérés ont la même taille, et les métriques CPU et mémoire par déploiement ne sont pas encore exposées.

• Le worker s'exécute mais aucun workflow n'apparaît — vérifiez les instructions ENTRYPOINT/CMD de l'image. Elles doivent démarrer le worker, par exemple python worker.py, qui appelle run_worker([...]). La plateforme exécute l'image telle quelle.
• Le build échoue — ouvrez les détails du déploiement pour lire l'erreur, puis reproduisez le build en local avec docker build, en utilisant le même contexte et le même Dockerfile.
• Les exécutions arrivent sur le mauvais worker — deux déploiements portant le même nom se volent leurs exécutions. Donnez un nom unique à chaque déploiement.