> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/fr/module-1-fondamentaux-de-larchitecture/05-clusters-nodes.md).

# Clusters et types de nœuds

Apprenez comment VergeOS organise les serveurs physiques en clusters, comprenez les différents types de nœuds (contrôleur, scale-out, stockage seul, calcul seul) et comment les systèmes montent en charge.

## Qu'est-ce qu'un cluster ?

Un **cluster** Un cluster dans VergeOS est un regroupement logique de nœuds présentant les mêmes caractéristiques matérielles, formant un pool de ressources présenté comme des actifs utilisables dans l'interface utilisateur de VergeOS. Les clusters permettent une gestion efficace, la mise à l'échelle et la haute disponibilité des charges de travail virtualisées.

Chaque système VergeOS commence avec au moins un cluster — les deux nœuds de contrôleur initiaux forment le premier cluster lors de l'installation. À partir de là, vous pouvez ajouter des nœuds au cluster existant ou créer des clusters supplémentaires avec des rôles et des profils matériels différents.

### Pourquoi les clusters sont importants

Les clusters servent à plusieurs fins :

* **Isolation du calcul** — le CPU, la mémoire et les charges de travail des VM sont liés à un cluster spécifique. Les VM s'exécutent uniquement sur les nœuds de leur cluster attribué (avec basculement optionnel vers un autre cluster).
* **Pool de stockage partagé** — les niveaux vSAN s'étendent sur plusieurs clusters pour former un seul pool de stockage logique. Un disque de stockage sur le cluster 1 et un disque de stockage sur le cluster 2 peuvent tous deux contribuer au même niveau. Les nœuds dédiés au calcul accèdent à ce stockage partagé via le réseau principal.
* **Optimisation matérielle** — différents clusters peuvent avoir des profils matériels différents : nœuds à grande mémoire pour les bases de données, nœuds équipés de GPU pour le rendu, nœuds à forte densité NVMe pour les charges de travail intensives en stockage
* **Mise à l'échelle indépendante** — ajoutez de la capacité de calcul à un cluster sans affecter les autres ; le stockage se met à l'échelle sur l'ensemble du système

## Types de clusters

VergeOS prend en charge trois types de clusters distincts qui peuvent être combinés au sein d'un même système :

| Type de cluster         | Fournit             | Participation au vSAN                                                     | Cas d'utilisation typique                                                     |
| ----------------------- | ------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Combiné (HCI)**       | Calcul + stockage   | Oui — les nœuds contribuent avec des disques de stockage aux niveaux vSAN | Charges de travail polyvalentes, déploiements petits à moyens                 |
| **Stockage uniquement** | Stockage uniquement | Oui — les nœuds fournissent uniquement du stockage                        | Extension de stockage dédiée dans les architectures UCI                       |
| **Calcul uniquement**   | Calcul uniquement   | Non — démarrage sur disque uniquement ou amorçage PXE                     | Charges de travail à forte capacité de calcul (ML, rendu, analyse de données) |

**Exemples de déploiement courants :**

```mermaid
graph TB
    subgraph hci["HCI (un seul cluster)"]
        N1["Contrôleur 1<br/>Calcul + stockage"]
        N2["Contrôleur 2<br/>Calcul + stockage"]
        N3["Scale-out<br/>Calcul + stockage"]
    end

    subgraph hybrid["Hybride (2 clusters)"]
        H1["Contrôleur 1<br/>Stockage + gestion"]
        H2["Contrôleur 2<br/>Stockage + gestion"]
        HC1["Nœud de calcul 1"]
        HC2["Nœud de calcul 2"]
    end

    subgraph uci["UCI (3 clusters)"]
        U1["Contrôleur 1<br/>Gestion"]
        U2["Contrôleur 2<br/>Gestion"]
        US1["Nœud de stockage 1"]
        US2["Nœud de stockage 2"]
        UC1["Nœud de calcul 1"]
        UC2["Nœud de calcul 2"]
    end

    style N1 fill:#e3f2fd,stroke:#1565c0
    style N2 fill:#e3f2fd,stroke:#1565c0
    style N3 fill:#e3f2fd,stroke:#1565c0
    style H1 fill:#e3f2fd,stroke:#1565c0
    style H2 fill:#e3f2fd,stroke:#1565c0
    style HC1 fill:#fff3e0,stroke:#e65100
    style HC2 fill:#fff3e0,stroke:#e65100
    style U1 fill:#e3f2fd,stroke:#1565c0
    style U2 fill:#e3f2fd,stroke:#1565c0
    style US1 fill:#e8f5e9,stroke:#2e7d32
    style US2 fill:#e8f5e9,stroke:#2e7d32
    style UC1 fill:#fff3e0,stroke:#e65100
    style UC2 fill:#fff3e0,stroke:#e65100
```

## Types de nœuds

Chaque serveur physique dans un système VergeOS est un **nœud**. Les nœuds diffèrent par la manière dont ils rejoignent le système, le rôle qu'ils jouent et le cluster auquel ils appartiennent. VergeOS définit quatre types de nœuds :

### Nœuds de contrôleur

Chaque système VergeOS commence avec au moins deux **nœuds de contrôleur**. Un troisième nœud de contrôleur est requis pour la redondance N+2. Ils sont spéciaux car :

* **Nœud 1** crée un tout nouveau système VergeOS. Il initialise le vSAN, crée le premier cluster et exécute la configuration post-installation (configuration réseau, création de cluster pour des types de nœuds supplémentaires, etc.)
* **Nœud 2** rejoint le système créé par le nœud 1 en tant que second contrôleur, assurant la redondance de toutes les fonctions de gestion du système (N+1)
* **Nœud 3 (facultatif)** — un troisième nœud de contrôleur peut être ajouté pour la redondance N+2, permettant au système de tolérer deux pannes de nœud simultanées

Les nœuds de contrôleur appartiennent toujours à **Cluster 1**. Dans une topologie HCI, ils fournissent à la fois le calcul et le stockage. Dans une topologie hybride, ils fournissent généralement **uniquement le stockage et la gestion** — aucune VM de production — tandis qu'un cluster de calcul séparé gère toutes les charges de travail. Dans une topologie UCI complète, ils gèrent le système mais délèguent le stockage et le calcul à des clusters dédiés.

Le premier cluster doit inclure au moins deux nœuds avec **stockage Tier 0** (disques de métadonnées) — c'est une exigence stricte car le Tier 0 contient l'index du système de fichiers vSAN et doit être redondant.

### Nœuds Scale-Out

Les nœuds Scale-Out étendent un cluster HCI existant en ajoutant davantage de capacité de calcul et de stockage. Caractéristiques clés :

* **Matériel identique** à celui des nœuds de contrôleur du cluster auquel ils rejoignent (même génération de CPU, disposition de stockage similaire, configuration NIC correspondante)
* Installation via USB et sélection du type de nœud Scale-Out. L'installateur détecte automatiquement la fabric principale, puis l'opérateur s'authentifie avec des identifiants admin. Si plusieurs clusters existent, l'opérateur sélectionne également le cluster cible et un nœud de référence pour comparer le matériel
* Les disques rejoignent automatiquement les niveaux vSAN existants
* Contribuent à la fois au calcul (exécutent des VM) et au stockage (participation au vSAN)

Les nœuds Scale-Out sont le moyen le plus simple de faire grandir un déploiement HCI — ajoutez un nœud et la capacité de calcul et de stockage du cluster augmente proportionnellement.

### Nœuds de stockage uniquement

Les nœuds de stockage uniquement sont dédiés exclusivement à l'extension de la capacité vSAN. Ils :

* Contribuent des disques aux niveaux vSAN mais ne **pas** exécutent de charges de travail VM
* Appartiennent à un **cluster de stockage uniquement** (par ex., Cluster 2)
* Nécessitent la création du cluster de stockage dans l'interface VergeOS avant d'ajouter le premier nœud de stockage
* Sont utilisés dans les architectures UCI où le stockage et le calcul évoluent indépendamment

### Nœuds de calcul uniquement

Les nœuds de calcul uniquement fournissent de la puissance de traitement sans participer au stockage vSAN. Ils :

* Exécutent des charges de travail VM mais n'ont **aucun stockage vSAN local** (disque de démarrage uniquement ou démarrage PXE)
* Appartiennent à un **cluster de calcul uniquement** (par ex., Cluster 3)
* Nécessitent la création du cluster de calcul dans l'interface VergeOS avant d'ajouter le premier nœud de calcul
* Accèdent au stockage via le réseau principal depuis les nœuds des clusters HCI ou de stockage uniquement

Les nœuds de calcul uniquement sont idéaux pour les charges de travail qui nécessitent une forte densité CPU/RAM/GPU sans croissance de stockage proportionnelle — apprentissage automatique, rendu, analyse de données ou VDI.

### Résumé des types de nœuds

| Type de nœud            | Rôle                                     | Cluster    | vSAN                                        | Exécute des VM         | Méthode de jonction                            |
| ----------------------- | ---------------------------------------- | ---------- | ------------------------------------------- | ---------------------- | ---------------------------------------------- |
| **Contrôleur (nœud 1)** | Crée un nouveau système                  | Cluster 1  | Oui (Tier 0 + niveaux de charge de travail) | Oui (HCI) ou Non (UCI) | Création d'un nouveau système                  |
| **Contrôleur (nœud 2)** | Rejoint en tant que contrôleur redondant | Cluster 1  | Oui (Tier 0 + niveaux de charge de travail) | Oui (HCI) ou Non (UCI) | Rejoint le cluster 1                           |
| **Scale-out**           | Ajoute de la capacité HCI                | Cluster 1  | Oui (niveaux de charge de travail)          | Oui                    | Détection automatique sur la fabric principale |
| **Stockage uniquement** | Extension de stockage dédiée             | Cluster 2+ | Oui (niveaux de charge de travail)          | Non                    | Rejoint le cluster de stockage désigné         |
| **Calcul uniquement**   | Extension de calcul dédiée               | Cluster 2+ | Non (disque de démarrage uniquement / PXE)  | Oui                    | Rejoint le cluster de calcul désigné           |

{% hint style="info" %}
**Venez de VMware ou Nutanix ?**

Aucune de ces plateformes n'a, de manière native, le concept de membres de stockage uniquement ou de calcul uniquement au sein d'un même cluster. VergeOS, oui, et cela vous permet de typer les clusters pour une mise à l'échelle indépendante.

| Rôle de nœud VergeOS | Analogue le plus proche dans VMware vSphere                                                | Analogue le plus proche dans Nutanix                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Contrôleur           | Hôte ESXi + services vCenter (pas d'appliance séparée)                                     | Premier nœud dans un cluster ; les contrôleurs VergeOS s'exécutent sur du bare metal, pas dans un CVM |
| Scale-out            | Hôte ESXi supplémentaire rejoignant un cluster vSAN                                        | Nœud supplémentaire rejoignant un cluster Nutanix                                                     |
| Stockage uniquement  | Aucun équivalent natif (le témoin vSAN s'en rapproche le plus)                             | Aucun équivalent — chaque nœud Nutanix exécute un CVM et participe au calcul                          |
| Calcul uniquement    | Hôte ESXi sans vSAN local, montant un stockage externe (ici, vSAN via le réseau principal) | Aucun équivalent direct                                                                               |

Les clusters VMware et Nutanix sont uniformes ; les clusters VergeOS peuvent être HCI, de stockage uniquement ou de calcul uniquement, et un système peut mélanger plusieurs clusters typés.
{% endhint %}

## Comment les nœuds rejoignent un système

Le processus de jonction des nœuds suit une séquence stricte afin d'éviter les conditions de concurrence :

```mermaid
flowchart TD
    A["Nœud 1 (Contrôleur)<br/>Crée un nouveau système VergeOS<br/>Initialise vSAN, crée le cluster 1"] --> B["Nœud 2 (Contrôleur)<br/>Rejoint le cluster 1<br/>Établit la paire HA"]
    B --> C{"Nœuds supplémentaires ?"}
    C -->|"Scale-out"| D["Nœuds Scale-out<br/>Détection automatique du système sur le réseau principal<br/>Rejoignent le cluster 1 séquentiellement"]
    C -->|"Stockage uniquement"| E["Créer le cluster de stockage<br/>(Cluster 2 dans l'interface)"]
    C -->|"Calcul uniquement"| F["Créer le cluster de calcul<br/>(Cluster 2 ou 3 dans l'interface)"]
    E --> G["Nœuds de stockage<br/>Rejoignent séquentiellement le cluster de stockage"]
    F --> H["Nœuds de calcul<br/>Rejoignent séquentiellement le cluster de calcul"]
    G --> F

    style A fill:#e3f2fd,stroke:#1565c0
    style B fill:#e3f2fd,stroke:#1565c0
    style D fill:#e3f2fd,stroke:#1565c0
    style G fill:#e8f5e9,stroke:#2e7d32
    style H fill:#fff3e0,stroke:#e65100
```

Règles clés pour la jonction des nœuds :

1. **Le nœud 1 doit terminer l'installation** avant que le nœud 2 puisse rejoindre — le nœud 2 a besoin d'un système existant auquel se connecter
2. **Les nœuds rejoignent séquentiellement** au sein d'un cluster — nœud 3 après nœud 2, nœud 4 après nœud 3, etc. — afin d'éviter les conditions de concurrence lors des changements d'appartenance au cluster
3. **Les clusters de stockage doivent exister** avant que les nœuds de stockage puissent rejoindre — créez d'abord le cluster dans l'interface VergeOS
4. **Les clusters de calcul doivent exister** avant que les nœuds de calcul puissent rejoindre — même prérequis
5. **Si vous déployez à la fois des clusters de stockage et de calcul**, les nœuds de stockage devraient être ajoutés en premier afin que les nœuds de calcul puissent accéder immédiatement au stockage vSAN

## Numérotation et nommage des clusters

Les clusters sont numérotés à partir de 1, mais le **nom est libre** — vous pouvez appeler un cluster comme vous voulez et le renommer à tout moment dans l'interface VergeOS. Les noms ci-dessous ne sont que des conventions courantes, pas des valeurs obligatoires :

| Numéro de cluster | Rôle par défaut                                                | Nom typique                          |
| ----------------- | -------------------------------------------------------------- | ------------------------------------ |
| Cluster 1         | HCI (contrôleurs + scale-out optionnel)                        | "HCI", "Par défaut" ou "Contrôleurs" |
| Cluster 2         | Stockage uniquement (si UCI) ou calcul uniquement (si hybride) | "Stockage" ou "Calcul"               |
| Cluster 3         | Calcul uniquement (dans une UCI complète avec 3 clusters)      | "Calcul"                             |

Dans un déploiement UCI complet avec 3 clusters :

* **Cluster 1**: Contrôleurs (gestion du système, métadonnées Tier 0)
* **Cluster 2**: Nœuds de stockage (tout le stockage de charge de travail vSAN)
* **Cluster 3**: Nœuds de calcul (exécution de toutes les VM)

## Exigences minimales et haute disponibilité

| Exigence                                | Détail                                                                                                                                                          |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nombre minimum de nœuds par système** | 2 (une paire de contrôleurs)                                                                                                                                    |
| **Nombre minimum de nœuds par cluster** | 2 (pour la redondance pendant la maintenance ou en cas de panne)                                                                                                |
| **Nœuds de contrôleur**                 | Minimum 2 par système (N+1 par défaut) ; 3 requis pour la redondance N+2 — doivent disposer d'un stockage Tier 0 pour les métadonnées vSAN                      |
| **Comportement HA**                     | Si un nœud tombe en panne, ses charges de travail migrent vers le ou les nœuds survivants du même cluster                                                       |
| **Mode maintenance**                    | Les nœuds peuvent être placés en mode maintenance ; les charges de travail sont migrées à chaud vers d'autres nœuds du cluster avant le début de la maintenance |

## Mise à l'échelle

Les systèmes VergeOS évoluent d'un cluster HCI minimum à 2 nœuds vers des déploiements multi-clusters. Tous les nœuds doivent partager le **même réseau de commutation** avec **zéro saut de commutateur** entre eux (objectif de latence inférieur à 0,05 ms). Un seul rack est la manière la plus simple de respecter cette exigence. Les déploiements sur plusieurs racks sont possibles, mais chaque fabric principale doit toujours se terminer sur un seul commutateur — utilisez des câbles plus longs vers la même paire de commutateurs de fabric plutôt que d'étendre la fabric sur plusieurs commutateurs (MLAG/stacking est pour le réseau externe, pas pour la fabric principale). La stratégie de mise à l'échelle dépend de votre architecture :

### Mise à l'échelle HCI (simple)

Ajoutez des nœuds scale-out au cluster 1. Chaque nœud ajoute proportionnellement à la fois du calcul et du stockage.

```mermaid
graph LR
    subgraph "Début : HCI à 2 nœuds"
        A1["Nœud 1"] --- A2["Nœud 2"]
    end

    subgraph "Croissance : HCI à 4 nœuds"
        B1["Nœud 1"] --- B2["Nœud 2"]
        B3["Nœud 3"] --- B4["Nœud 4"]
        B1 --- B3
        B2 --- B4
    end

    subgraph "Mise à l'échelle : HCI 8+ nœuds"
        C1["Nœud 1-2<br/>(Contrôleurs)"]
        C2["Nœuds 3-8<br/>(Scale-out)"]
    end
```

**Idéal pour**: croissance équilibrée où les besoins en calcul et en stockage augmentent ensemble.

### Mise à l'échelle UCI (indépendante)

Ajoutez des nœuds à des clusters spécifiques selon la ressource qui constitue le goulot d'étranglement :

* **Besoin de plus de stockage ?** Ajoutez des nœuds au cluster de stockage
* **Besoin de plus de calcul ?** Ajoutez des nœuds au cluster de calcul
* **Besoin de plus des deux ?** Ajoutez indépendamment aux deux clusters

**Idéal pour**: charges de travail avec des besoins en ressources déséquilibrés (par ex., stockage lourd avec peu de calcul, ou calcul à forte densité GPU avec stockage modeste).

### Bonnes pratiques pour la mise à l'échelle

{% hint style="info" %}
**Système vs cluster**

Dans VergeOS, un cluster est un groupe de nœuds ayant les mêmes caractéristiques matérielles. Un seul système VergeOS peut contenir plusieurs clusters, chacun optimisé pour des charges de travail ou des profils matériels différents. Cela diffère de certaines plateformes HCI, où « cluster » désigne l'ensemble de l'environnement. Pour plus de détails, voir [Vue d'ensemble des clusters](https://docs.verge.io/run-the-platform/fr/administration-systeme/clusters-overview.md).
{% endhint %}

* **Cohérence matérielle au sein des clusters** — utilisez les mêmes spécifications matérielles pour tous les nœuds d'un cluster. Mélanger différents matériels dans un cluster peut entraîner des problèmes de performance et de fiabilité. Pour ajouter un matériel différent, comme une génération de serveur plus récente, créez un nouveau cluster dans le même système.
* **Planifiez une redondance N+1** — dimensionnez chaque cluster de sorte qu'en perdant un nœud, il reste suffisamment de capacité pour toutes les charges de travail
* **Surveillez avant de mettre à l'échelle** — utilisez les métriques du tableau de bord VergeOS (utilisation CPU, usage de la RAM, capacité vSAN) pour identifier la ressource à étendre
* **Mise à l'échelle sans interruption** — de nouveaux nœuds peuvent être ajoutés à un système en cours d'exécution sans interrompre les charges de travail existantes

## Exemples de topologies de déploiement

Topologies courantes qui correspondent à des schémas de déploiement réels :

| Topologie                  | Nœuds                                         | Clusters                                 | Quand l'utiliser                                                           |
| -------------------------- | --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------- |
| **HCI à 2 nœuds**          | 2 contrôleurs                                 | 1 (HCI)                                  | Petits sites, edge, PoC, évaluation de base                                |
| **HCI + scale-out**        | 2 contrôleurs + N scale-out                   | 1 (HCI)                                  | Déploiements HCI en croissance nécessitant une mise à l'échelle équilibrée |
| **Hybride (2 clusters)**   | 2 contrôleurs + N calcul                      | 2 (stockage + calcul)                    | Charges de travail intensives en calcul avec stockage modeste              |
| **UCI (3 clusters)**       | 2 contrôleurs + N stockage + M calcul         | 3 (Contrôleur + Stockage + Calcul)       | Mise à l'échelle indépendante du calcul/stockage                           |
| **UCI + GPU (4 clusters)** | 2 contrôleurs + N stockage + M calcul + G GPU | 4 (Contrôleur + Stockage + Calcul + GPU) | IA/ML, rendu ou VDI avec des nœuds GPU dédiés                              |

```mermaid
graph TB
    subgraph "HCI à 2 nœuds"
        direction LR
        H1["Contrôleur 1<br/>HCI"] --- H2["Contrôleur 2<br/>HCI"]
    end

    subgraph "HCI + scale-out"
        direction LR
        S1["Contrôleur 1"] --- S2["Contrôleur 2"]
        S3["Scale-out 1"] --- S4["Scale-out 2"]
    end

    subgraph "Hybride (2 clusters)"
        direction LR
        subgraph "Cluster 1 (Stockage)"
            Y1["Contrôleur 1"]
            Y2["Contrôleur 2"]
        end
        subgraph "Cluster 2 (Calcul)"
            Y3["Calcul 1"]
            Y4["Calcul 2"]
        end
    end

    subgraph "UCI + GPU (4 clusters)"
        direction LR
        subgraph "Cluster 1 (Contrôleur)"
            U1["Contrôleur 1"]
            U2["Contrôleur 2"]
        end
        sous-graphe "Cluster 2 (Stockage)"
            U3["Stockage 1"]
            U4["Stockage 2"]
        end
        sous-graphe "Cluster 3 (Calcul)"
            U5["Calcul 1"]
            U6["Calcul 2"]
        end
        sous-graphe "Cluster 4 (GPU)"
            G1["Nœud GPU 1"]
            G2["Nœud GPU 2"]
        end
    end
```

## Points clés à retenir

| Concept                           | Résumé                                                                                                                                          |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cluster**                       | Regroupement logique de nœuds ayant le même matériel, formant une pool de ressources                                                            |
| **Trois types de clusters**       | HCI (calcul + stockage), stockage uniquement, calcul uniquement — combinables au sein d’un même système                                         |
| **Quatre types de nœuds**         | Contrôleur, mise à l’échelle horizontale, stockage uniquement, calcul uniquement — chacun avec un rôle et une méthode d’intégration spécifiques |
| **Minimum 2 nœuds**               | Par cluster pour la redondance ; les contrôleurs nécessitent un stockage de niveau 0                                                            |
| **Intégration séquentielle**      | Les nœuds rejoignent le système un par un afin d’éviter les conditions de course                                                                |
| **Cohérence matérielle**          | Tous les nœuds d’un cluster doivent avoir des spécifications matérielles correspondantes                                                        |
| **Mise à l'échelle indépendante** | L’architecture UCI permet d’ajouter indépendamment de la capacité de calcul ou de stockage                                                      |
| **Mise à l'échelle**              | Les systèmes évoluent d’un HCI à 2 nœuds vers des déploiements multi-clusters au sein d’un seul plan de commutation                             |

## Étapes suivantes

Vous comprenez maintenant comment VergeOS organise les nœuds en clusters et comment différents types de nœuds remplissent différents rôles. Dans l’atelier pratique, vous explorerez ces concepts à l’aide du playground Terraform : [**Atelier : exploration de l’architecture →**](https://docs.verge.io/learn-the-platform/fr/module-1-fondamentaux-de-larchitecture/lab.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/fr/module-1-fondamentaux-de-larchitecture/05-clusters-nodes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
