Skip to content

docs: fix outdated Import Agent/Tool UI steps across AuthBridge demo docs #794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pdettori merged 2 commits into from
Aug 24, 2026
Merged

docs: fix outdated Import Agent/Tool UI steps across AuthBridge demo docs #794

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f594b6
docs(authbridge): fix outdated Import Agent/Tool UI steps in weather-…
pdettori Aug 24, 2026
f060415
docs: fix outdated UI steps in github-issue and advanced weather demos
pdettori Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 14 additions & 16 deletions authbridge/demos/github-issue/demo-ui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`

@huang195 huang195 Aug 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit — the same step now reads two different ways across sibling docs.

ImportAgentPage.tsx:157 initialises the default service port as { name: 'http', port: 8080, targetPort: 8000, protocol: 'TCP' }. This PR rewrote the equivalent step in weather-agent/demo-ui.md to say exactly that:

The default Pod Configuration already maps service port 8080 to target port 8000, so no change is needed.

Here it still reads "set Service Port to 8080 and Target Port to 8000" — the same two values the form already ships with. Not wrong, just asking the reader to set something already set, and now inconsistent with the sibling doc this PR improved.

Worth noting the tool step above it (9090 / 9090) genuinely does differ from the default, so that one should stay imperative — this is only about the agent step.


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`
Expand All @@ -351,7 +349,7 @@ Expected:
> --from-literal=apikey="<YOUR_OPENAI_API_KEY>"
> ```

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 |
|------|----------------|--------------|
Expand All @@ -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.

Expand Down Expand Up @@ -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:

Expand Down
17 changes: 8 additions & 9 deletions authbridge/demos/weather-agent/demo-ui-advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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). |
Expand Down
30 changes: 15 additions & 15 deletions authbridge/demos/weather-agent/demo-ui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand All @@ -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.
Expand Down Expand Up @@ -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`
Expand All @@ -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.

Expand Down Expand Up @@ -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:

Expand Down
Loading