From b75014ab92b6a9a3dad7b011515e775bbc4162b2 Mon Sep 17 00:00:00 2001 From: Yi Nuo <218099172+yi-nuo426@users.noreply.github.com> Date: Sat, 16 May 2026 11:25:25 -0500 Subject: [PATCH 1/4] docs(kanvas): relationship evaluation engine selection & diagnostics Add a Designer user-doc page covering the relationship-evaluation engine choice (Automatic / Meshery server / Client-side WASM), the relationship indicator states (evaluating / evaluated / error), the one-time non-blocking notifications, and a task-oriented section for diagnosing failing or unexpected relationship results using the Relationship Evaluation Diagnostics view. Documents the layer5labs/meshery-extensions#4247 feature. Signed-off-by: Yi Nuo <218099172+yi-nuo426@users.noreply.github.com> --- .../designer/relationship-evaluation/index.md | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 content/en/kanvas/designer/relationship-evaluation/index.md diff --git a/content/en/kanvas/designer/relationship-evaluation/index.md b/content/en/kanvas/designer/relationship-evaluation/index.md new file mode 100644 index 00000000000..4e03871c41c --- /dev/null +++ b/content/en/kanvas/designer/relationship-evaluation/index.md @@ -0,0 +1,157 @@ +--- +title: Relationship Evaluation Engine +description: > + Choose how Kanvas evaluates relationships in your designs, understand the + relationship indicator states, and diagnose failing or unexpected relationship + results. +weight: 11 +categories: [Designer] +tags: [designs, relationships, components, troubleshooting] +aliases: + - /meshmap/designer/relationship-evaluation +--- + +As you build a design, Kanvas continuously evaluates the +[relationships](/kanvas/concepts/relationships/) between your components — to +identify connections, validate them, and keep related configuration in sync. +This page explains how you can choose which engine performs that evaluation, how +to read the relationship indicator, and how to diagnose results that look wrong. + +## How Relationships Are Evaluated + +Kanvas can run relationship evaluation using one of two interchangeable engines: + +- **Meshery server** — the policy engine running inside your Meshery server. It + is always available and is the default. +- **Client-side (WASM)** — the same policy engine, compiled to WebAssembly and + run inside a background worker in your browser. Because it runs locally, there + are no round-trips to the server, so evaluation is typically faster. It is + available only when your Meshery server provides the WebAssembly artifact. + +Both engines produce the same relationship results. The choice affects +performance, not correctness. + +{{< alert type="info" title="Editing is never blocked" >}} Relationship +evaluation runs alongside your work — it never blocks editing or saving a +design. If evaluation fails for any reason, you can keep designing and saving +normally; only the relationship results are affected. {{< /alert >}} + +## Changing the Evaluation Engine Preference + +The engine is controlled by the **Relationship Evaluation Engine** preference. + +1. In Kanvas Designer, open **Settings**. +2. Find the **Relationship Evaluation Engine** preference. +3. Choose one of the following values: + +| Value | What it does | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Automatic** (recommended) | Runs a one-time health check at the start of the session. If the client-side (WASM) engine passes a self-test, it is used for the rest of the session; otherwise the Meshery server is used. | +| **Meshery server** | Always uses the Meshery server's policy engine. | +| **Client-side (WASM)** | Uses the in-browser WebAssembly engine. | + +The engine is selected **once per session**. Changing the preference takes full +effect on the next session (for example, after reloading Kanvas). + +{{< alert type="info" title="When to prefer the server engine" >}} Leave the +preference on **Automatic** unless you have a specific reason to change it. If +client-side results ever look wrong, switching to **Meshery server** is the most +reliable way to rule out the engine as the cause — see +[Diagnosing failing or unexpected results](#diagnosing-failing-or-unexpected-relationship-results). +{{< /alert >}} + +## Reading the Relationship Indicator + +The relationship indicator tells you the state of the most recent evaluation: + +- **Evaluating** — evaluation is in progress. This is normal after you add, + remove, or reconfigure components. +- **Evaluated** — evaluation completed successfully and the relationships shown + on the canvas are up to date. +- **Error** — the most recent evaluation failed. This is a distinct state from + "no relationships evaluated yet". When evaluation fails: + - The last successful relationship results stay on screen so your design + remains readable. + - A one-time, non-blocking notification appears to let you know. + - You can continue editing and saving the design without interruption. + +If the client-side (WASM) engine was active and faults during the session, it +automatically self-heals: Kanvas falls back to the Meshery server engine for the +remainder of the session, without requiring any action from you. + +### What the one-time notifications mean + +When evaluation first fails, or when Kanvas falls back from the client-side +engine to the server engine, a single non-blocking notification is shown. It is +informational — it does not require a response, and it will not repeat for every +subsequent evaluation in that session. Its purpose is to let you know that +relationship results may be stale or that the active engine changed. + +## Diagnosing Failing or Unexpected Relationship Results + +If relationships are missing, look wrong, or the indicator shows an error, use +the **Relationship Evaluation Diagnostics** view to investigate. + +### Step 1 — Enable the debugger preference + +The Diagnostics view is exposed under the Designer **debugger** preference. + +1. In Kanvas Designer, open **Settings**. +2. Enable the **debugger** preference. +3. Open the **Relationship Evaluation Diagnostics** view. + +### Step 2 — Read the Diagnostics view + +The Diagnostics view reports the current state of relationship evaluation: + +- **Active engine and why** — which engine is in use (Meshery server or + client-side WASM) and the reason it was selected (for example, the result of + the Automatic health check, an explicit preference, or a runtime fallback). +- **Contract / version** — the evaluation contract and engine version, used to + confirm the client and server are compatible. +- **Last error** — the most recent evaluation error, if any. +- **Fallback count** — how many times Kanvas has fallen back from the + client-side engine to the server engine this session. +- **Latency** — how long recent evaluations took. + +### Step 3 — Force the server engine if client results look wrong + +If you suspect the client-side engine is producing incorrect results: + +1. Open **Settings**. +2. Set **Relationship Evaluation Engine** to **Meshery server**. +3. Reload Kanvas so the new engine is used for the session. +4. Re-check the design's relationships. + +If the relationships are correct with the server engine but wrong with the +client-side engine, that points to a client engine issue worth reporting (see +below). + +### Step 4 — Re-trigger evaluation + +Evaluation re-runs automatically whenever you change the design — for example, +by adding, removing, or reconfiguring a component, or by toggling a relationship +kind on or off from the relationships section of the design. Making any such +change re-triggers evaluation with the active engine. If the indicator was in +the error state, a successful re-evaluation clears it. + +### Step 5 — When and how to file a bug + +If relationship results are still wrong or evaluation keeps failing after the +steps above — especially if the **Meshery server** engine also produces +incorrect or failing results — file a bug. Include the following from the +Relationship Evaluation Diagnostics view so the issue can be reproduced: + +- The **active engine** and the reason it was selected. +- The **contract / version** shown in the Diagnostics view. +- The **last error** text. +- The **fallback count**, if relevant. +- A description of the expected relationships versus what Kanvas showed, and the + design (or a minimal reproduction) if you can share it. + +{{< alert type="info" title="Related reading" >}} For what relationships are and +the kinds Kanvas supports, see +[Understanding Relationships](/kanvas/concepts/relationships/). For creating and +managing relationships in a design, see +[Creating Relationships](/kanvas/getting-started/creating-relationships/). +{{< /alert >}} From 7a37c442936280fbe177f344210fa1df98964c16 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Tue, 19 May 2026 16:57:41 -0500 Subject: [PATCH 2/4] Rename Relationship Evaluation Engine to Policy Engine Updated the title and description of the relationship evaluation section. Clarified the engine types and their performance implications. Signed-off-by: Lee Calcote --- .../kanvas/designer/relationship-evaluation/index.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/content/en/kanvas/designer/relationship-evaluation/index.md b/content/en/kanvas/designer/relationship-evaluation/index.md index 4e03871c41c..f7c2335f342 100644 --- a/content/en/kanvas/designer/relationship-evaluation/index.md +++ b/content/en/kanvas/designer/relationship-evaluation/index.md @@ -1,5 +1,5 @@ --- -title: Relationship Evaluation Engine +title: Policy Engine description: > Choose how Kanvas evaluates relationships in your designs, understand the relationship indicator states, and diagnose failing or unexpected relationship @@ -7,8 +7,6 @@ description: > weight: 11 categories: [Designer] tags: [designs, relationships, components, troubleshooting] -aliases: - - /meshmap/designer/relationship-evaluation --- As you build a design, Kanvas continuously evaluates the @@ -21,15 +19,15 @@ to read the relationship indicator, and how to diagnose results that look wrong. Kanvas can run relationship evaluation using one of two interchangeable engines: -- **Meshery server** — the policy engine running inside your Meshery server. It +- **Server-side** — the policy engine running inside your Meshery server. It is always available and is the default. -- **Client-side (WASM)** — the same policy engine, compiled to WebAssembly and +- **Client-side** — the same policy engine, compiled to WebAssembly and run inside a background worker in your browser. Because it runs locally, there are no round-trips to the server, so evaluation is typically faster. It is available only when your Meshery server provides the WebAssembly artifact. Both engines produce the same relationship results. The choice affects -performance, not correctness. +performance, and where toil (evaluation) is done, not correctness. {{< alert type="info" title="Editing is never blocked" >}} Relationship evaluation runs alongside your work — it never blocks editing or saving a From d43715cede5761cebe39032712b74ce7c037b275 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Tue, 19 May 2026 16:58:06 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Lee Calcote --- content/en/kanvas/designer/relationship-evaluation/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/kanvas/designer/relationship-evaluation/index.md b/content/en/kanvas/designer/relationship-evaluation/index.md index f7c2335f342..4e02668b94a 100644 --- a/content/en/kanvas/designer/relationship-evaluation/index.md +++ b/content/en/kanvas/designer/relationship-evaluation/index.md @@ -147,8 +147,8 @@ Relationship Evaluation Diagnostics view so the issue can be reproduced: - A description of the expected relationships versus what Kanvas showed, and the design (or a minimal reproduction) if you can share it. -{{< alert type="info" title="Related reading" >}} For what relationships are and -the kinds Kanvas supports, see +{{< alert type="info" title="Related reading" >}} For an overview of what +relationships are and the kinds Kanvas supports, see [Understanding Relationships](/kanvas/concepts/relationships/). For creating and managing relationships in a design, see [Creating Relationships](/kanvas/getting-started/creating-relationships/). From 0fa75fc09daac81f2bba00116ef15f7179901057 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Tue, 19 May 2026 16:59:14 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Lee Calcote --- content/en/kanvas/designer/relationship-evaluation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/kanvas/designer/relationship-evaluation/index.md b/content/en/kanvas/designer/relationship-evaluation/index.md index 4e02668b94a..5bd7490e283 100644 --- a/content/en/kanvas/designer/relationship-evaluation/index.md +++ b/content/en/kanvas/designer/relationship-evaluation/index.md @@ -129,7 +129,7 @@ below). Evaluation re-runs automatically whenever you change the design — for example, by adding, removing, or reconfiguring a component, or by toggling a relationship -kind on or off from the relationships section of the design. Making any such +kind on or off from the **Relationships** section of the Designer. Making any such change re-triggers evaluation with the active engine. If the indicator was in the error state, a successful re-evaluation clears it.