> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/la-fabrique/gerer-les-instances.md). # Gérer les instances Une instance est un déploiement de votre Agent dans un environnement spécifique. Chaque app peut avoir plusieurs instances (dev, prod, expérimentation...). *** ## Créer une instance depuis le registre interne 1. Depuis la fiche de votre app, accédez à l'onglet **Instances** 2. Cliquez sur **Créer une instance** 3. **Étape 1 - Déploiement** : * Saisissez un **nom** unique pour l'instance (ex : "prod-api") * Cochez **Instance principale** si vous souhaitez que cette instance soit la référence * Sélectionnez **Registre interne ou externe** * Choisissez l'**image** à déployer * Configurez les **ressources** (CPU / RAM) * Configurez le **timeout de déploiement** (par défaut : 9 minutes) * Ajoutez le port `22` pour les autoriser connexions SSH et le port `443` pour les connexions HTTPS. * Définissez le **port exposé.** * Activez un **stockage persistant** au besoin 4. **Étape 2 - Configuration** : * Pour les Apps : activez/désactivez la **sécurisation Basic Auth** * Pour les Apps: Activez un **compte de service** pour accéder **aux fichiers des Données de travail projet** depuis votre app. Lorsqu'il est activé, configurez : * **Rôle** : Lecteur (lecture seule) ou Éditeur (lecture + écriture) * **Projets** : restreignez l'accès à des projets spécifiques, ou laissez vide pour donner accès à tous les projets Un **Client ID** est automatiquement généré (format `sa-`), visible depuis la fiche de l'instance une fois déployée. * Configurez le **Health check** (TCP ou HTTP) 5. **Étape 3 - Variables d'environnement** : * Ajoutez les **variables globales** * **Pour les Tools :** vous pouvez définir des **Variables utilisateur** : elles seront configurées par chaque utilisateur depuis l'assistant global ou le listing des Agents. Ex: API token personnel 6. Cliquez sur **Créer** L'instance est créée avec le statut "Créé". Elle doit ensuite être déployée. Vous pouvez consulter la fiche d'un déploiement pour en connaître les détails. {% hint style="warning" %} La **taille du stockage** persistant ne peut **pas être modifiée** à date. {% endhint %} {% hint style="info" %} Les ressources CPU / RAM sont allouées uniquement au moment du **déploiement**, pas à la création. {% endhint %} {% hint style="info" %} Ajoutez plusieurs variables d'environnement en une seule fois en les collant directement dans le champ (format `CLÉ=valeur`). {% endhint %} ## Créer une instance depuis un registre externe Vous pouvez également déployer une image hébergée sur un registre externe (DockerHub, registry privée...). 1. Dans l'étape "Déploiement", sélectionnez **Registre externe** 2. Saisissez : * **URL de l'image** (ex : `docker.io/mon-org/mon-image:v1.0` ou par digest : `nom-image@sha256:` * **Clé d'accès** (si registre privé) * **Nom d'utilisateur** (optionnel) 3. Poursuivez le parcours normalement ## Déployer une instance {% hint style="info" %} Seul le **responsable de l'app** peut lancer le déploiement. {% endhint %} Le déploiement rend accessible l'instance de l'agent (via URL pour les Apps, ou depuis l'assistant pour les Tools). Vous pouvez déployer une instance depuis plusieurs endroits : | Point de déploiement | Instance déployée | | ------------------------------- | --------------------- | | Fiche Agent → bouton "Déployer" | Instance principale | | Card instance dans la liste | Instance sélectionnée | | Fiche détail d'une instance | Instance consultée | **Processus de déploiement** 1. Cliquez sur **Déployer** 2. L'instance passe en statut "Déploiement en cours" 3. À la fin du processus : * **Succès** : statut "Déployé", URL d'accès disponible * **Échec** : statut "Échec", logs d'erreur consultables Les **logs de déploiement** et les **logs applicatifs** sont disponibles pour diagnostiquer les problèmes : * Onglet Déploiements → bouton "Logs" : suivi du déploiement. * Onglet Logs applicatifs : erreurs et messages runtime. Il est possible d'**annuler un déploiement en cours** directement depuis la fiche de l'instance ou la card dans le listing. L'instance revient alors à son état précédent : statut "Créé" si elle n'avait jamais été déployée, ou statut "Déployé" avec sa dernière configuration stable si un déploiement précédent existait. **Statuts d'une instance** | Statut | Description | | -------------------- | ----------------------------------------------------- | | Créé | Instance configurée, non déployée | | Déploiement en cours | Déploiement en cours d'exécution | | Déployé | Instance active et accessible | | Arrêté | Instance mise en pause, ressources libérées | | Échec | Déploiement échoué | | Attention | Redéploiement échoué, fallback sur version précédente | #### Redéployer une instance Pour redéployer une instance déjà déployée : 1. Cliquez sur **Redéployer** depuis la fiche instance ou la card 2. Confirmez l'action : "Voulez-vous redéployer cette instance ? L'instance actuelle sera arrêtée puis un nouveau déploiement sera lancé." 3. L'ancien déploiement est arrêté et un nouveau est lancé avec la même configuration #### Fallback automatique {% hint style="warning" %} En **cas d'erreur sur un déploiement**, si un précédent déploiement valide existe, la plateforme effectue **automatiquement un rollback** vers la dernière version stable. {% endhint %} En cas d'échec de redéploiement, si une version précédente était déployée avec succès : * La plateforme effectue automatiquement un **rollback** vers la dernière version stable * L'instance passe en statut "Attention" avec le message : "Le redéploiement a échoué. L'instance a été restaurée à sa dernière version fonctionnelle." * Le service n'est pas interrompu * Les logs d'erreur du déploiement échoué sont disponibles ## Définir une Instance principale La première instance créée devient automatiquement l'instance principale. Elle est identifiable par un badge "Principale" dans la liste. Pour changer l'instance principale : 1. Accédez à la liste des instances 2. Sur l'instance souhaitée, cliquez sur **Définir comme principale** 3. Confirmez le changement L'instance principale est celle : * déployée lorsque vous cliquez sur "Déployer" depuis la fiche app * dont l'**URL sera utilisée** par les utilisateurs de l'application (App) * dont les tools seront utilisés dans Le Druide (Tools) ## Modifier une instance Le responsable peut modifier la configuration d'une instance depuis sa fiche détail. **Modifications avec redéploiement automatique** Les modifications suivantes déclenchent un nouveau déploiement : * Image Docker * Ressources (CPU / RAM) * Variables d'environnement * Port exposé * Health check * Configuration Basic Auth **Modifications sans redéploiement** Les modifications suivantes sont appliquées immédiatement sans redéploiement : * Le nom de l'instance * Le timeout de déploiement **Comportement en cas d'échec** Si le redéploiement suite à une modification échoue : * Fallback automatique sur la configuration précédente * Instance en statut "Attention" * Configuration modifiée non appliquée * Possibilité de réessayer ou d'annuler les modifications ## Démarrer / arrêter une instance Le responsable de l'app peut démarrer ou arrêter chaque instance individuellement depuis sa fiche détail ou depuis le listing des instances. ### **Arrêter une instance** L'arrêt d'une instance libère les ressources CPU et RAM tout en conservant la configuration. 1. Depuis la fiche de l'instance ou la card dans le listing, cliquez sur **Arrêter** 2. Confirmez l'action dans la boîte de dialogue 3. L'instance passe en statut "Arrêté" {% hint style="warning" %} L'arrêt d'une instance la rend inaccessible (URL indisponible pour les Apps, outil désactivé pour les Tools). {% endhint %} ### **Démarrer une instance** Le démarrage réactive une instance précédemment arrêtée avec sa configuration existante. 1. Depuis la fiche de l'instance ou la card dans le listing, cliquez sur **Démarrer** 2. L'instance passe en statut "Déploiement en cours" 3. Une fois le démarrage terminé, l'instance repasse en statut "Déployé" ## **Gestion des ressources** Les ressources de calcul allouées aux déploiements d'instances d'agents sont indépendantes des clusters Spark et Python, mais partagées entre les apps elles-mêmes. * Si la plateforme atteint sa capacité maximale, il peut devenir impossible de lancer de nouvelles applications. * Les ressources (CPU/RAM) sont libérées à l'arrêt et réallouées au démarrage des déploiements En cas de saturation récurrente, contactez le Customer Success Manager pour ajuster la capacité globale. {% hint style="info" %} Si les ressources ne sont plus disponibles, le redémarrage sera bloqué jusqu'à libération de capacité. {% endhint %} {% hint style="success" %} **Bonne pratique** : Arrêtez les instances de développement ou de test lorsqu'elles ne sont pas utilisées pour libérer les ressources du cluster. {% endhint %} ## Supprimer une instance ou une app **Supprimer une instance** La suppression d'une instance retire : * Le déploiement actif (si existant) * La configuration de l'instance * Les ressources associées Les autres instances de l'app ne sont pas affectées. **Supprimer une app** La suppression d'une app retire définitivement : * L'entrée dans La Fabrique * Toutes les instances associées * Toutes les images du registre interne * L'accès dans Le Druide (pour les Tools) *** ### Bonnes pratiques pour la gestion des instances * **Nommez clairement** vos instances selon leur environnement (dev, staging, prod) * **Utilisez l'instance principale** pour votre environnement de production * **Arrêtez les instances** de développement/test lorsqu'elles ne sont pas utilisées * **Surveillez les statuts** : une instance en "Attention" nécessite une intervention