> 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/run-the-platform/de/systemadministration/core-fabric-status.md). # Leitfaden zum Status des Core Fabric ## Voraussetzungen * Zugriff auf die VergeOS-Oberfläche mit Node-Verwaltungsrechten * Grundlegendes Verständnis von [VergeOS-Kernnetzwerkarchitektur](/plan-and-deploy/de/implementierungsleitfaden/concepts.md#core-fabric-network) * Physischer Konsolen- oder IPMI-Zugriff auf die Nodes (zur Fehlerbehebung) * Kenntnis Ihrer Core-VLAN-Zuweisungen (Core 1 und Core 2) und der erwarteten NIC-Link-Geschwindigkeit ## Was ist die Core Fabric? Die Fabric ist das Rückgrat Ihres VergeOS-Systems und nutzt das Kernnetzwerk, um die gesamte Node-zu-Node-Kommunikation zu verwalten, einschließlich vSAN-Traffic, Peer-Erkennung, Verwaltungsoperationen, Netzwerkverkehr zwischen Nodes, VM- und Netzwerkmigrationen sowie andere Funktionen. Eine typische VergeOS-Bereitstellung verwendet **zwei unabhängige physische Kernnetzwerke** ("Core 1 Switch", "Core 2 Switch") für Redundanz. Jeder Node sollte über zwei unabhängige physische Pfade zu jedem anderen Node im Cluster verfügen. {% hint style="warning" %} **Keine Switch-Hops erforderlich** Alle Nodes müssen mit derselben Switching-Fabric verbunden sein, mit **null Switch-Hops** zwischen ihnen. Die Ziel-Latenz zwischen Nodes in Core-Fabric-Netzwerken liegt unter 0,05 ms. Das Hinzufügen von Switch-Hops führt zu Latenz, die Fabric-Scores und Cluster-Performance verschlechtert. {% endhint %} Diese Redundanz der Core Fabric ist entscheidend, um Systemresilienz und einen unterbrechungsfreien Betrieb selbst bei einem Node- oder Laufwerksausfall aufrechtzuerhalten und Wartungsarbeiten ohne Ausfallzeit zu ermöglichen. **MTU-Anforderungen der Core Fabric:** | Komponente | MTU | | ---------------------- | ------------------------------ | | Physischer Switch-Port | >= 9216 | | Physische NIC | 9192 (typisch) | | VXLAN-Overlay | NIC-MTU minus 50 Byte Overhead | {% hint style="info" %} **Wie die Redundanz der Core Fabric funktioniert** Die Core Fabric behandelt Redundanz auf niedriger Ebene und erstellt ein Mesh, in dem jeder Node redundante Pfade zu jedem anderen Node im System aufrechterhält. Aufgrund dieser eingebauten Redundanz sollte physisches LAG oder Port-Bonding auf Core-Fabric-Netzwerken **nicht** nicht verwendet werden — das würde die eigenen Mechanismen der Fabric beeinträchtigen. Die VergeOS Core Fabric bietet umfassendere Erkennung und höhere Resilienz als herkömmliche Link-Aggregation. LAG erkennt und schützt nur vor Ausfällen auf Link-Ebene, während die VergeOS Fabric auf Anwendungsebene arbeitet und eine weitaus größere Bandbreite an Problemen erkennt, einschließlich verlorener Pakete, MTU-Mismatches, NIC-Hängern und fehlerhafter Firmware — zusätzlich zu einfach getrennten Links. {% endhint %} ## Fabric-Status aufrufen (UI) Der Fabric-Status ist in der VergeOS-UI auf mehreren Detailebenen verfügbar. | Methode | Detaillierungsgrad | Anwendungsfall | | ----------------------- | --------------------------- | ------------------------------------------------------------------------------ | | **Alarme** | Zusammenfassung | Tägliche Überwachung — Warnungen, wenn Pfade beeinträchtigt oder verloren sind | | **Liste der Node-NICs** | Pro NIC | Schnelle Statusprüfung aller Node-NICs | | **Node-Dashboard** | Pro NIC (ausgewählter Node) | Schnelle Statusprüfung einzelner NICs und ihrer Verbindungen zu anderen Nodes | | **Knotendiagnose** | Vollständiger JSON-Bericht | Erweiterte Fehlerbehebung — vollständige Pfad-, Score- und Peer-Details | ### Alarme Im Alltag kann die Überwachung des Fabric-Status über dasselbe Alarmsystem erfolgen, das auch für den Rest Ihrer VergeOS-Umgebung verwendet wird. Eine **Warnung** wird ausgelöst, wenn bidirektionale Kommunikation auf einem Kernnetzwerkpfad nicht verfügbar ist. {% hint style="success" %} Wenn Sie auf einen Alarm in der Liste klicken, gelangen Sie direkt zum betroffenen Node-Dashboard, wo weitere Details verfügbar sind. {% endhint %} Weitere Informationen zum Anzeigen und Verwalten von Alarmen finden Sie im [Alarm-Leitfaden](/run-the-platform/de/betrieb/alarms.md). {% hint style="warning" %} **Kernnetzwerk-Alarme sofort beheben** Kernnetzwerk-Alarme zeigen an, dass Ihr System möglicherweise nicht über vollständige Fabric-Redundanz verfügt. Beheben Sie diese umgehend, um sicherzustellen, dass Ihr Cluster einen Ausfall ohne Unterbrechung tolerieren kann. Ereignisauslöser können so konfiguriert werden, dass Benachrichtigungen per E-Mail, Textwarnsystemen, überwachten Slack-Kanälen und mehr gesendet werden, sodass Administratoren sofort benachrichtigt werden. Siehe den [Task-Engine-Produktleitfaden](/automate-protect-and-extend/de/automatisierung/task-engine.md) für weitere Informationen zum Erstellen automatisierter Aufgaben; dieses [Automatisierungsbeispiel](/knowledge-base/de/automation-api/automated-task-example-webhook.md) KB-Artikel enthält ein Beispiel für das Einrichten ereignisgesteuerter Benachrichtigungen. {% endhint %} ### Liste der Node-NICs Dies ist eine schnelle Möglichkeit, den Fabric-Status aller Core-Netzwerk-NICs auf einer einzigen Seite anzuzeigen. 1. Navigieren Sie zu **Infrastruktur** > **Knoten**. 2. Klicken Sie **NICs** im linken Menü. 3. Eine Liste aller NICs aller Nodes wird angezeigt. Die **Fabric-Status** Spalte zeigt den Status der Core-Netzwerk-NICs an (z. B. 'Confirmed', 'No Path', 'Degraded'). Ein *Fabric-Status* von 'None' wird für NICs angezeigt, die nicht an der Core Fabric teilnehmen (z. B. externe Netzwerke). ### Node-Dashboards Statusinformationen sind pro NIC in jedem Node-Dashboard verfügbar. 1. Navigieren Sie zu **Infrastruktur** > **Knoten**. 2. Doppelklicken Sie auf den gewünschten **Knoten** aus der Liste. 3. Scrollen Sie nach unten zum **NICs** Abschnitt auf dem Node-Dashboard. Jede Core-Fabric-NIC zeigt entweder einen **Bestätigt** Statusindikator oder eine Problemstatusmeldung an (z. B. No Path, Degraded). 4. Für detailliertere Informationen klicken Sie auf das Globus-Symbol rechts. Dies zeigt ein Popup mit NIC-Details an: * Hersteller, Modell, Schnittstelle und Treiber * **Bestätigt** / **Kein Pfad** / **Beeinträchtigt** Status pro Verbindung zu jedem anderen Node im System * **Score** pro Verbindung zu jedem anderen Node (siehe [Score-Werte](#score-values) unten) 5. Jeder Pfad sollte **Bestätigt** Status anzeigen. Jeder Pfad, der **Kein Pfad** oder **Beeinträchtigt** zeigt, weist auf ein Konnektivitätsproblem hin, das untersucht und behoben werden sollte. ### Knotendiagnose Ausführlichere Fabric-Statusdetails (nützlich für fortgeschrittene Fehlerbehebung) sind über die Node-Diagnose verfügbar. Diese liefert einen vollständigen JSON-Bericht über den Fabric-Status, wie er vom ausgewählten Node gesehen wird, einschließlich aller entdeckten Peers, ihrer Pfade, Scores und Bestätigungsstatus. 1. Navigieren Sie zu **Infrastruktur** > **Knoten**. 2. Wählen Sie die gewünschte **Knoten** aus der Liste. 3. Klicken Sie **Diagnosen** im linken Menü. 4. Wählen Sie **Fabric-Konfiguration** aus der **Abfrage** Dropdown-Menü. 5. Klicken Sie **Senden** auszuführen. 6. Überprüfen Sie die Ausgabe. Die wichtigsten Felder zuerst prüfen: `paths[].confirmed` und `paths[].score` für jeden Peer-Node. #### Feldreferenz Die folgenden Felder erscheinen in der JSON-Ausgabe des Fabric-Status. | Feld | Beschreibung | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `$sysid` | SHA-1-Hash zur Identifizierung dieses VergeOS-Systems (bezogen aus `/.system_id`) | | `$last_update` | Zeitstempel der jüngsten Aktualisierung des Fabric-Status | | `syncing_time` | Feld auf oberster Ebene, das angibt, ob der Node derzeit seine Uhr mit dem Cluster synchronisiert. Dies muss `falsch` bevor der Node vollständig beitritt. Während des initialen Node-Beitritts ist es normal, dass der Wert `true`. | | `paths` | Array von Netzwerkpfaden zu diesem Peer-Node | | `paths[].ip` | IP-Adresse des entfernten Nodes im Kernnetzwerk | | `paths[].iface` | Lokale Netzwerkschnittstelle, die zum Erreichen dieses Pfads verwendet wird | | `paths[].score` | Numerischer Score für die Verbindungsqualität (höher ist besser). Der Maximalwert hängt von der NIC-Link-Geschwindigkeit ab — siehe [Score-Werte](#score-values) unten. | | `paths[].confirmed` | Ob dieser Pfad als aktiv und erreichbar verifiziert wurde (`true` / `falsch`) | | `vxlans` | Für diesen Peer konfigurierte VXLAN-Tunnelendpunkte. Dies sind die Overlay-Tunnel, die für virtuellen Netzwerkverkehr zwischen Nodes verwendet werden. | #### Bestätigter Status | Wert | Bedeutung | | -------- | -------------------------------------------------------------------------------------------------------------- | | `true` | Der Pfad wurde verifiziert — bidirektionale Kommunikation funktioniert | | `falsch` | Der Pfad konnte nicht verifiziert werden — die Konnektivität ist verloren gegangen oder nie hergestellt worden | ### Score-Werte Der `score` Feld stellt die Qualität der Verbindung zu einem Peer-Node über einen bestimmten Pfad dar. Der maximale Score entspricht der Link-Geschwindigkeit der Core-NIC — ein höherer Score bedeutet eine schnellere, gesündere Verbindung. | NIC-Link-Geschwindigkeit | Maximaler Score | | ------------------------ | --------------- | | 100 Gbit/s | 200 | | 50 Gbit/s | 100 | | 25 Gbit/s | 50 | | 10 Gbit/s | 20 | {% hint style="info" %} **Scores interpretieren** Ein „perfekter“ Score bedeutet, dass der Wert dem erwarteten Maximum für Ihre NIC-Geschwindigkeit entspricht. Beispielsweise ist ein Score von **50** auf einer 25-Gbit/s-NIC gesund, während ein Score von **50** auf einer 100-Gbit/s-NIC auf eine Verschlechterung hinweist. Vergleichen Sie den Score immer mit dem Maximum Ihrer Link-Geschwindigkeit. {% endhint %} Ein Score, der deutlich **unter** dem erwarteten Maximum liegt, weist auf eine Verschlechterung hin – mögliche Ursachen sind Netzwerklatenz, Paketverlust oder suboptimales Routing. Ein Score von **0** weist auf einen vollständigen Verlust der bidirektionalen Kommunikation hin. {% hint style="success" %} **Bestätigt vs. Score** *bestätigt* gibt an, ob der Pfad erreichbar ist, während *score* die Qualität dieses Pfads widerspiegelt. {% endhint %} ## Beispiele für gesunde und ungesunde Fabric ### Gesunde Fabric (2-Knoten-System) Alle Nodes sichtbar, jeweils zwei Pfade, Scores auf Maximum für die NIC-Geschwindigkeit, alle bestätigt: ```json { "$sysid": "68e1925057aa7c6afaf9a255dcfc623794a6398e", "$last_update": "03/24/2026 13:31:46", "syncing_time": false, "node2": { "paths": [ { "ip": "172.16.1.2", "iface": "enp148s0f0np0", "score": 200, "confirmed": true }, { "ip": "172.16.2.2", "iface": "enp148s0f1np1", "score": 200, "confirmed": true } ], "vxlans": ["vx2 via 172.16.1.2", "vx1 via 172.16.2.2"] }, "node1": { "paths": [ { "ip": "172.16.1.1", "iface": "enp148s0f0np0", "score": 200, "confirmed": true }, { "ip": "172.16.2.1", "iface": "enp148s0f1np1", "score": 200, "confirmed": true } ], "vxlans": ["vx2 via 172.16.1.1", "vx1 via 172.16.2.1"] } } ``` {% hint style="success" %} **Worauf zu achten ist** * Jeder Node im Cluster erscheint in der Ausgabe (in einem 4-Node-Cluster sollten Sie alle 4 Node-Einträge sehen) * Jeder Node hat **zwei Pfade** (einen pro Kernnetzwerk) * Alle Pfade zeigen `"confirmed": true` * `"syncing_time": false` auf oberster Ebene * Scores entsprechen dem erwarteten Maximum für Ihre NIC-Link-Geschwindigkeit (z. B. 200 für 100 Gbit/s, 50 für 25 Gbit/s) {% endhint %} ### Verschlechterte Fabric — Redundanz verloren Ein Pfad fehlt für einen Node (Ausfall eines einzelnen Kernnetzwerks): ```json { "node2": { "paths": [ { "ip": "172.16.1.2", "score": 200, "confirmed": true } ] } } ``` {% hint style="warning" %} **Auswirkung** Der Node ist nur über ein Kernnetzwerk erreichbar. Wenn der verbleibende Pfad ausfällt, verliert der Node die Cluster-Konnektivität vollständig. Unverzüglich untersuchen. {% endhint %} ### Verschlechterte Fabric — niedriger Score Beide Pfade vorhanden, aber einer zeigt reduzierte Qualität: ```json { "node2": { "paths": [ { "ip": "172.16.1.2", "score": 200, "confirmed": true }, { "ip": "172.16.2.2", "score": 120, "confirmed": true } ] } } ``` {% hint style="warning" %} **Auswirkung** Ein Score unter dem erwarteten Maximum für Ihre NIC-Geschwindigkeit weist auf eine Verschlechterung des Netzwerks auf diesem Pfad hin. Die vSAN-Performance kann beeinträchtigt sein. Prüfen Sie den betroffenen Core-Netzwerkpfad auf Latenz, Paketverlust oder Switch-Probleme. {% endhint %} ### Kritische Fabric — Pfad nicht bestätigt Ein Pfad ist vorhanden, kann aber nicht verifiziert werden: ```json { "node2": { "paths": [ { "ip": "172.16.1.2", "score": 200, "confirmed": true }, { "ip": "172.16.2.2", "score": 0, "confirmed": false } ] } } ``` {% hint style="danger" %} **Auswirkung** Der Node hat die Kommunikation auf einem Kernnetzwerk verloren. Wenn beide Pfade `"confirmed": false`anzeigen, ist der Node vom Cluster isoliert, was zu Störungen von vSAN und Workloads führt. {% endhint %} ### Kritische Fabric — Node fehlt Ein Node, der im Cluster sein sollte, erscheint überhaupt nicht in der Fabric-Ausgabe. {% hint style="danger" %} **Auswirkung** Der fehlende Node ist vollständig nicht erreichbar. Er könnte ausgeschaltet sein, beide Core-NICs könnten ausgefallen sein oder er könnte sich in einem anderen VLAN befinden. Prüfen Sie sofort die physische Konnektivität und den Stromstatus des Nodes. {% endhint %} ## Fabric-Überprüfung vor der Wartung VergeOS-Wartungsarbeiten — einschließlich [System-Updates](/run-the-platform/de/betrieb/sop-update.md), [vSAN-Scale-ups](/run-the-platform/de/betrieb/vsan-scale-up-sop.md), und [Scale-outs](/run-the-platform/de/betrieb/sop-scale-out.md) — erfordern als Voraussetzung eine gesunde Fabric. **Führen Sie keine Wartungsarbeiten durch, wenn die Fabric ungesund ist.** Beheben Sie zunächst alle Probleme mithilfe des [Problembehebung](#troubleshooting-fabric-issues) Abschnitts unten. Eine gesunde Fabric bedeutet: * Alle Peer-Nodes erscheinen in der Ausgabe * Jeder Peer hat **zwei Pfade** (einen pro Kernnetzwerk) * Alle Pfade zeigen `"confirmed": true` * Scores entsprechen dem erwarteten Maximum für Ihre NIC-Link-Geschwindigkeit * `"syncing_time": false` auf oberster Ebene {% hint style="success" %} **Schnelle Überprüfung** Führen Sie von einem beliebigen Node aus **Knotendiagnose** > **Fabric-Konfiguration** aus und bestätigen Sie vor der Wartung, dass jeder Peer die oben genannten Kriterien erfüllt. {% endhint %} ## Fabric-Probleme beheben ### Pfad nicht bestätigt **Symptome:** Ein oder mehrere Pfade zeigen `"confirmed": false` **Häufige Ursachen und Maßnahmen:** 1. **Physische Verkabelung** — Stellen Sie sicher, dass das Kabel sowohl am Node-NIC- als auch am Switch-Port korrekt sitzt. Verwenden Sie ein nachweislich funktionierendes Kabel. 2. **Switch-VLAN-Konfiguration** — Bestätigen Sie, dass der Switch-Port dem richtigen Core-VLAN zugewiesen ist. Core-Ports sollten als **Access-Ports** auf einem dedizierten VLAN konfiguriert sein. 3. **MTU-Mismatch** — Die Core Fabric erfordert Jumbo-Frames (mindestens MTU 9216 auf dem physischen Switch). Überprüfen Sie die MTU-Konsistenz End-to-End: * Switch-Port-MTU >= 9216 * Physische NIC-MTU (z. B. 9192) * VXLAN-MTU = NIC-MTU minus 50 Byte Overhead 4. **NIC ausgefallen** — Prüfen Sie den NIC-Status auf dem Node-Dashboard. Wenn die NIC als "Down" angezeigt wird, kann dies auf einen Hardwarefehler oder ein Treiberproblem hinweisen. ### Score-Verschlechterung **Symptome:** Pfade sind bestätigt, aber der Score liegt unter dem erwarteten Maximum für Ihre NIC-Geschwindigkeit **Häufige Ursachen und Maßnahmen:** 1. **Netzwerklatenz** — Alle Nodes müssen sich in derselben Switching-Fabric befinden mit **null Switch-Hops** zwischen ihnen (Ziel-Latenz <0,05 ms). Das Hinzufügen von Switch-Hops auf dem Core-Fabric-Pfad führt zu Latenz, die die Cluster-Performance und Scores erheblich verschlechtern kann. 2. **Switch-Überlastung** — Überprüfen Sie die Schnittstellenzähler des Switches auf Fehler, Drops oder CRC-Fehler. 3. **Duplex-/Geschwindigkeits-Mismatch** — Verwenden Sie **Knotendiagnose** > **Ethernet-Tool** um zu überprüfen, ob die NIC mit der erwarteten Geschwindigkeit (10 Gbit/s+) ausgehandelt hat. ### Fehlende Nodes **Symptome:** Ein Node, der im Cluster sein sollte, erscheint nicht in der Fabric-Ausgabe **Häufige Ursachen und Maßnahmen:** 1. **Node offline** — Stellen Sie sicher, dass der Node eingeschaltet ist und läuft. Prüfen Sie IPMI, wenn der Node nicht reagiert. 2. **Beide Core-NICs ausgefallen** — Wenn beide Kernnetzwerkschnittstellen ausgefallen sind, kann der Node nicht an der Fabric-Erkennung teilnehmen. 3. **VLAN-Isolierung** — Bestätigen Sie, dass die Switch-Ports für den fehlenden Node auf denselben VLANs wie die anderen Nodes liegen. 4. **ybfabric wird nicht ausgeführt** — Der `ybfabric` Daemon muss laufen, damit ein Node an der Fabric-Erkennung teilnehmen kann. Wenn der Prozess nicht läuft, sollte der `vsan-watchdog` ihn automatisch neu starten. Wenn der Node nach mehreren Minuten weiterhin fehlt, wenden Sie sich an den VergeOS-Support. ### Nur ein Pfad **Symptome:** Nodes zeigen nur einen Pfad statt zwei **Häufige Ursachen und Maßnahmen:** 1. **Kabeldefekt** — Ein Kabel eines Kernnetzwerks könnte getrennt oder beschädigt sein. Verwenden Sie ein nachweislich funktionierendes Kabel. 2. **Ausfall des Switch-Ports** — Der Switch-Port für ein Kernnetzwerk könnte ausgefallen sein. Prüfen Sie den Status und die Protokolle der Switch-Schnittstelle. 3. **NIC-Fehler** — Eine der beiden Core-NICs könnte ausgefallen sein. Prüfen Sie den NIC-Status auf dem Node-Dashboard. Verwenden Sie **Knotendiagnose** > **Ethernet-Tool** um den Link-Status zu überprüfen. ### Probleme bei der Zeitsynchronisierung **Symptome:** `"syncing_time": true` bleibt länger als 60 Sekunden nach dem Start des Nodes bestehen **Häufige Ursachen und Maßnahmen:** 1. Der Node kann keine Verbindung zu Peers herstellen, um seine Uhr zu synchronisieren. Untersuchen Sie zuerst die Fabric-Konnektivität. 2. Wenn die Fabric-Pfade gesund sind, muss der `ybfabric` Daemon möglicherweise über das Starter-Skript neu gestartet werden. ## Bewährte Vorgehensweisen * **Kernnetzwerk-Alarme sofort beheben** — Beheben Sie Probleme schnell, um vollständige Fabric-Redundanz aufrechtzuerhalten * **Fabric vor jeder Wartungsoperation überprüfen** — Machen Sie es sich zur Gewohnheit, den Fabric-Status vor Updates, Scale-ups, Scale-outs und Node-Wartung zu prüfen * **Zwei Kernnetzwerke beibehalten** — Halten Sie immer sowohl Core1- als auch Core2-Pfade gesund, um Redundanz zu gewährleisten * **Nach physischen Änderungen testen** — Nach Änderungen an Verkabelung, Switch oder NIC den Fabric-Status erneut überprüfen * **Die Aktion „Refresh Fabric“ verwenden** — Nachdem Sie ein Konnektivitätsproblem behoben haben, verwenden Sie die **Refresh Fabric** Schaltfläche auf dem Node-Dashboard (oder die Sammelaktion in der Node-Liste), um eine Statusaktualisierung zu erzwingen * **Fabric-Status in Diagnosen aufnehmen** — Wenn Sie mit dem VergeOS-Support zusammenarbeiten, enthält die `ybfabric.txt` Datei in den Systemdiagnosen den Fabric-Zustand zum Zeitpunkt der Erstellung der Diagnose ## Verwandte Ressourcen * [Kernkonzepte — Core-Fabric-Netzwerk](/plan-and-deploy/de/implementierungsleitfaden/concepts.md#core-fabric-network) * [Knotenübersicht](/run-the-platform/de/systemadministration/nodes-overview.md) * [Leitfaden zur Knotendiagnose](/run-the-platform/de/systemadministration/node-diagnostics.md) * [SOP für System-Updates](/run-the-platform/de/betrieb/sop-update.md) * [SOP für vSAN-Scale-Up](/run-the-platform/de/betrieb/vsan-scale-up-sop.md) * [SOP für Scale-Out](/run-the-platform/de/betrieb/sop-scale-out.md) * [Leitfaden zur Switch-Konfiguration](/plan-and-deploy/de/implementierungsleitfaden/switch-configuration.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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/run-the-platform/de/systemadministration/core-fabric-status.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.