From 9f594b6f8d5f4bc54bbdd55a3885eb49282eb95f Mon Sep 17 00:00:00 2001 From: Paolo Dettori Date: Mon, 24 Aug 2026 10:50:53 -0400 Subject: [PATCH 1/2] docs(authbridge): fix outdated Import Agent/Tool UI steps in weather-agent demo The weather-agent UI demo referenced UI fields that no longer match the current Rossoctl Import Agent / Import Tool forms: - Remove the 'Framework: LangGraph' step (dropdown no longer exists; framework is set automatically). - Rename the agent-form checkbox 'Enable AuthBridge sidecar injection' to 'Secure with AuthBridge'. - Rename the SPIRE checkbox to 'Enable SPIRE identity (JWT-SVID via spiffe-helper)' in both the Import Tool and Import Agent steps. - Update the port step: it is now a 'Pod Configuration' section whose defaults already map 8080 -> 8000, so no manual entry is needed. - Rename the 'Outbound Ports to Exclude' field to 'Bypass AuthBridge on these outbound ports' (Step 2 item and Step 4 Ollama section). - Fix 'Deploy From Image' casing to 'Deploy from Image'. The Import Tool form's AuthBridge checkbox is intentionally left as 'Enable AuthBridge sidecar injection' since only the Agent form was renamed. Verified against rossoctl/ui-v2 ImportAgentPage.tsx and ImportToolPage.tsx. Closes #793 Assisted-By: Claude (Anthropic AI) Signed-off-by: Paolo Dettori --- authbridge/demos/weather-agent/demo-ui.md | 30 +++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/authbridge/demos/weather-agent/demo-ui.md b/authbridge/demos/weather-agent/demo-ui.md index ea69794f1..f57016105 100644 --- a/authbridge/demos/weather-agent/demo-ui.md +++ b/authbridge/demos/weather-agent/demo-ui.md @@ -126,7 +126,7 @@ Realm **`rossoctl`** is created by the platform installer. 2. In the **Namespace** drop-down, choose `team1`, fill *Tool Name* with `weather-tool` (do not use uppercase) -3. Select **Deploy From Image** as the deployment method. +3. Select **Deploy from Image** as the deployment method. 4. For **Container Image**, use `ghcr.io/rossoctl/examples/weather_tool`. @@ -137,7 +137,7 @@ Realm **`rossoctl`** is created by the platform installer. 7. **Enable AuthBridge sidecar injection** is unchecked by default for tools. Leave it unchecked. -8. **Enable SPIRE identity (spiffe-helper sidecar)** should be **unchecked**. +8. **Enable SPIRE identity (JWT-SVID via spiffe-helper)** should be **unchecked**. > The weather tool is a simple MCP server calling a public weather API. It > does not need AuthBridge sidecars or token validation. @@ -170,19 +170,19 @@ kubectl get pods -n team1 | grep weather-tool 5. **Protocol**: `A2A` -6. **Framework**: `LangGraph` +6. **Workload Type** select `Deployment`. -7. **Workload Type** select `Deployment`. - -8. **Enable AuthBridge sidecar injection** is checked by default for agents. +7. **Secure with AuthBridge** is checked by default for agents. Leave it checked. -9. **Enable SPIRE identity (spiffe-helper sidecar)** is checked by default. +8. **Enable SPIRE identity (JWT-SVID via spiffe-helper)** is checked by default. Leave it checked. -10. Under **Port Configuration**, set **Service Port** to `8080` and **Target Port** to `8000` +9. The default **Pod Configuration** already maps service port `8080` to target + port `8000`, so no change is needed. Expand **Pod Configuration** to verify + or adjust the ports. -11. Under **Environment Variables**, click **Import from File/URL**, +10. Under **Environment Variables**, click **Import from File/URL**, Select **From URL** and provide the **URL** from this repo: - For Ollama: `https://raw.githubusercontent.com/rossoctl/examples/refs/heads/main/a2a/weather_service/.env.ollama` - For OpenAI: `https://raw.githubusercontent.com/rossoctl/examples/refs/heads/main/a2a/weather_service/.env.openai` @@ -207,13 +207,13 @@ kubectl get pods -n team1 | grep weather-tool > kubectl delete secret openai-secret -n team1 > ``` -12. **(Ollama only)** If using Ollama as your LLM provider, expand +11. **(Ollama only)** If using Ollama as your LLM provider, expand **AuthBridge Advanced Configuration** and enter `11434` in the - **Outbound Ports to Exclude** field. This prevents AuthBridge from - intercepting traffic to Ollama on the host machine. OpenAI users can + **Bypass AuthBridge on these outbound ports** field. This prevents AuthBridge + from intercepting traffic to Ollama on the host machine. OpenAI users can skip this — HTTPS traffic passes through via TLS passthrough. -13. Click **Build & Deploy Agent**. +12. Click **Build & Deploy Agent**. Wait for the Shipwright build to complete and the deployment to become ready. @@ -365,8 +365,8 @@ AuthBridge's `proxy-init` init container redirects traffic through Envoy. By default, only port 8080 (Keycloak) is excluded. Ollama traffic on port 11434 gets intercepted, which corrupts LLM streaming responses. -If you set the **Outbound Ports to Exclude** field to `11434` during import -(Step 2, item 12), this is already handled and no patch is needed. +If you set the **Bypass AuthBridge on these outbound ports** field to `11434` during +import (Step 2, item 11), this is already handled and no patch is needed. Otherwise, add the annotation after deployment: From f060415e89994a515b4b561e63d2528cbc41fccb Mon Sep 17 00:00:00 2001 From: Paolo Dettori Date: Mon, 24 Aug 2026 11:00:49 -0400 Subject: [PATCH 2/2] docs: fix outdated UI steps in github-issue and advanced weather demos Apply the same UI-drift corrections already made to weather-agent/demo-ui.md to the two sibling demo docs: - Remove the obsolete 'Framework' selection step (the UI no longer exposes a framework picker; agents are LangGraph). - Rename the agent-form 'Enable AuthBridge sidecar injection' checkbox to 'Secure with AuthBridge' (tool-form label is unchanged). - Update SPIRE checkbox label to 'Enable SPIRE identity (JWT-SVID via spiffe-helper)'. - Rename the 'Port Configuration' section to 'Pod Configuration'. - Rename the agent-form 'Outbound Ports to Exclude' field to 'Bypass AuthBridge on these outbound ports' (tool-form label is unchanged). - Fix 'Deploy From Image' casing to 'Deploy from Image'. - Renumber the affected agent-import steps and cross-references. Assisted-By: Claude (Anthropic AI) Signed-off-by: Paolo Dettori --- authbridge/demos/github-issue/demo-ui.md | 30 +++++++++---------- .../demos/weather-agent/demo-ui-advanced.md | 17 +++++------ 2 files changed, 22 insertions(+), 25 deletions(-) diff --git a/authbridge/demos/github-issue/demo-ui.md b/authbridge/demos/github-issue/demo-ui.md index 6465905ed..f0956af22 100644 --- a/authbridge/demos/github-issue/demo-ui.md +++ b/authbridge/demos/github-issue/demo-ui.md @@ -256,13 +256,13 @@ kubectl create secret generic github-tool-secrets -n team1 \ 7. **Enable AuthBridge sidecar injection** is unchecked by default for tools. Leave it unchecked. -8. **Enable SPIRE identity (spiffe-helper sidecar)** should be **unchecked**. +8. **Enable SPIRE identity (JWT-SVID via spiffe-helper)** should be **unchecked**. > The GitHub tool does not need AuthBridge sidecars — it validates incoming tokens > directly using its own JWKS logic. Injecting sidecars would cause a port 9090 > conflict between the tool's MCP broker and the authbridge gRPC server. -9. Under **Port Configuration**, set **Service Port** to `9090` and **Target Port** to `9090` +9. Under **Pod Configuration**, set **Service Port** to `9090` and **Target Port** to `9090` > The tool binary listens on port 9090. The agent's `MCP_URL` connects to > `http://github-tool-mcp:9090/mcp`, so both the service port and target port @@ -320,19 +320,17 @@ Expected: 5. **Protocol**: `A2A` -6. **Framework**: `LangGraph` +6. **Workload Type** select `Deployment`. -7. **Workload Type** select `Deployment`. - -8. **Enable AuthBridge sidecar injection** is checked by default for agents. +7. **Secure with AuthBridge** is checked by default for agents. Leave it checked. -9. **Enable SPIRE identity (spiffe-helper sidecar)** is checked by default. +8. **Enable SPIRE identity (JWT-SVID via spiffe-helper)** is checked by default. Leave it checked. -10. Under **Port Configuration**, set **Service Port** to `8080` and **Target Port** to `8000` +9. Under **Pod Configuration**, set **Service Port** to `8080` and **Target Port** to `8000` -11. Under **Environment Variables**, click **Import from File/URL**, +10. Under **Environment Variables**, click **Import from File/URL**, Select **From URL** and provide the **URL** from this repo: - For Ollama: `https://raw.githubusercontent.com/rossoctl/examples/refs/heads/main/a2a/git_issue_agent/.env.ollama` - For OpenAI: `https://raw.githubusercontent.com/rossoctl/examples/refs/heads/main/a2a/git_issue_agent/.env.openai` @@ -351,7 +349,7 @@ Expected: > --from-literal=apikey="" > ``` -12. Expand **Outbound Routing Rules** and add a route for the GitHub tool: +11. Expand **Outbound Routing Rules** and add a route for the GitHub tool: | Host | Target Audience | Token Scopes | |------|----------------|--------------| @@ -369,13 +367,13 @@ Expected: > control yet. Use **Step 2, Option B** instead: > `kubectl apply -f demos/github-issue/k8s/configmaps.yaml` from the `authbridge` > directory (same host, audience, and scopes as the table above). Then continue - > with item 13. Confirm **Enable AuthBridge sidecar injection** (item 8) is still + > with item 12. Confirm **Secure with AuthBridge** (item 7) is still > checked before deploying. -13. **(Ollama only)** If using Ollama, expand **AuthBridge Advanced Configuration** - and enter `11434` in the **Outbound Ports to Exclude** field. +12. **(Ollama only)** If using Ollama, expand **AuthBridge Advanced Configuration** + and enter `11434` in the **Bypass AuthBridge on these outbound ports** field. -14. Click **Build & Deploy Agent**. +13. Click **Build & Deploy Agent**. Wait for the Shipwright build to complete and the deployment to become ready. @@ -535,8 +533,8 @@ AuthBridge's `proxy-init` init container redirects traffic through Envoy. By default, only port 8080 (Keycloak) is excluded. Ollama traffic on port 11434 gets intercepted, which corrupts LLM streaming responses. -If you set the **Outbound Ports to Exclude** field to `11434` during import -(Step 5, item 13), this is already handled and no patch is needed. +If you set the **Bypass AuthBridge on these outbound ports** field to `11434` during import +(Step 5, item 12), this is already handled and no patch is needed. Otherwise, add the annotation after deployment: diff --git a/authbridge/demos/weather-agent/demo-ui-advanced.md b/authbridge/demos/weather-agent/demo-ui-advanced.md index 00032cf71..2bec09674 100644 --- a/authbridge/demos/weather-agent/demo-ui-advanced.md +++ b/authbridge/demos/weather-agent/demo-ui-advanced.md @@ -80,13 +80,13 @@ the optional exchange scope. The script: 1. Open [Import Tool](http://rossoctl-ui.localtest.me:8080/tools/import). 2. **Namespace**: `team1` · **Tool Name**: `weather-tool-advanced` (exact). -3. **Deploy From Image** · **Container Image**: +3. **Deploy from Image** · **Container Image**: `ghcr.io/rossoctl/examples/weather_tool` · **Image Tag**: `latest`. 4. **MCP Transport Protocol**: `streamable HTTP`. 5. **Enable AuthBridge sidecar injection**: ✅ **check** (advanced demo validates JWTs at the tool's ingress — this is the difference vs. the standard demo). -6. **Enable SPIRE identity (spiffe-helper sidecar)**: ✅ **check**. +6. **Enable SPIRE identity (JWT-SVID via spiffe-helper)**: ✅ **check**. 7. **Service Port** `8000` · **Target Port** `8000`. 8. Click **Build & Deploy Tool**. @@ -131,10 +131,9 @@ Now the UI flow (order matches the actual import form top-to-bottom): - Git Branch or Tag: `main` - Select Agent: `Weather Service Agent` - Source Subfolder: `a2a/weather_service` -4. **Protocol**: `A2A` · **Framework**: `LangGraph` · **Workload Type**: - `Deployment`. -5. **Enable AuthBridge sidecar injection**: ✅ (default). -6. **Enable SPIRE identity**: ✅ (default). +4. **Protocol**: `A2A` · **Workload Type**: `Deployment`. +5. **Secure with AuthBridge**: ✅ (default). +6. **Enable SPIRE identity (JWT-SVID via spiffe-helper)**: ✅ (default). 7. Expand **Outbound Routing Rules** and add one route — this is what triggers the RFC 8693 exchange when the agent calls the tool. The form has three fields (currently unlabeled in the UI); fill them in this @@ -166,8 +165,8 @@ Now the UI flow (order matches the actual import form top-to-bottom): MCP_URL=http://weather-tool-advanced-mcp:8000/mcp ``` 10. **(Ollama only)** Expand **AuthBridge Advanced Configuration** and set - **Outbound Ports to Exclude** to `11434`. OpenAI uses HTTPS and needs no - exclusion. + **Bypass AuthBridge on these outbound ports** to `11434`. OpenAI uses HTTPS + and needs no exclusion. 11. Click **Build & Deploy Agent**. After the agent pod is **Ready**, re-run the Keycloak script so the agent's @@ -248,7 +247,7 @@ Useful env knobs: | Symptom | Likely cause | Fix | |---------|--------------|-----| -| UI returns `Error: LLM execution failed: Connection error.` | Agent can't reach its LLM. Ollama not running, or Outbound Ports to Exclude not set to `11434`. `deploy_and_verify_advanced.sh` doesn't catch this — it never calls the LLM. | Start Ollama (`ollama serve` + `ollama pull llama3.2:3b-instruct-fp16`), or re-import with the OpenAI `.env` URL. | +| UI returns `Error: LLM execution failed: Connection error.` | Agent can't reach its LLM. Ollama not running, or **Bypass AuthBridge on these outbound ports** not set to `11434`. `deploy_and_verify_advanced.sh` doesn't catch this — it never calls the LLM. | Start Ollama (`ollama serve` + `ollama pull llama3.2:3b-instruct-fp16`), or re-import with the OpenAI `.env` URL. | | UI returns `Error: No LLM API key configured. Set the LLM_API_KEY environment variable.` | `openai-secret` is empty (often because `$OPENAI_API_KEY` wasn't exported when you ran `kubectl create secret`), or the agent wasn't restarted after fixing it. | Recreate with the literal value, then verify `kubectl get secret openai-secret -n team1 -o jsonpath='{.data.apikey}' \| base64 -d \| wc -c` is non-zero, then `kubectl rollout restart deploy/weather-service-advanced -n team1`. | | UI: **Outbound Routing Rules** expander missing | Rossoctl backend pre-dates [rossoctl#1194](https://github.com/rossoctl/rossoctl/pull/1194) | `kubectl apply -f authbridge/demos/weather-agent/k8s/configmaps-advanced.yaml` and skip the UI step. | | UI: agent card not available | AuthBridge failed to load `authproxy-routes` (invalid YAML shape) | See the same section in the [GitHub Issue UI demo](../github-issue/demo-ui.md#agent-card-not-available-in-the-ui). |