rossoctl / rossoctl/cortex

docs(authbridge): three inaccuracies in weather-agent demo-ui.md (secret name/ns, build-from-source precondition, agent-card name)

Open Beginner friendly
#671 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

stale
Dominant language
Go
Stars
13
Forks
40
Avg merge
12h 17m
Merged PRs (30d)
156

Description

Summary

While running the weather-agent beginner path end-to-end on a fresh Kind cluster
(setup-kagenti.sh --with-spire --with-ui --with-backend, operator chart
0.3.0-alpha.6), I hit three inaccuracies in
authbridge/demos/weather-agent/demo-ui.md that block or mislead a reader following
it verbatim. All three are confirmed against the live cluster and/or source.

1. Wrong Keycloak admin secret name and namespace (4 occurrences)

demo-ui.md states the operator's Keycloak admin secret is keycloak-admin-secret
in kagenti-system
:

  • L110–114 ("Installer-Provided Resources"):

    keycloak-admin-secret is not in team1. Operator 0.2+ keeps it in kagenti-system
    kubectl get secret keycloak-admin-secret -n kagenti-system

  • L577–578 (troubleshooting): same claim.

This is wrong. The operator's client-registration controller reads
keycloak-initial-admin from the keycloak namespace (keys username /
password), configured via keycloak.adminSecretName / keycloak.namespace in the
chart. Verified on a live cluster:

$ kubectl get secret keycloak-admin-secret -n kagenti-system
Error from server (NotFound): secrets "keycloak-admin-secret" not found

$ kubectl get secret keycloak-initial-admin -n keycloak -o jsonpath='{.data}'
{"password":"…","username":"…"}

So a reader running the documented verification command gets NotFound and concludes
the platform is broken, when in fact the secret they should check is
keycloak-initial-admin -n keycloak.

Fix: replace all four references with
kubectl get secret keycloak-initial-admin -n keycloak, and correct the surrounding
prose (it is in the keycloak namespace, not kagenti-system).

Note: the same wrong claim previously lived in kagenti's docs/install.md and is
being corrected in kagenti#1680.

2. "Build from Source" without a --with-builds precondition (L163, L218)

Step 2 instructs "Select Build from Source as the deployment method" and later
"Wait for the Shipwright build to complete." But a standard install
(--with-spire --with-ui --with-backend, no --with-builds) does not install
Shipwright/Tekton, and the UI then only offers "Deploy from Existing Image" — the
"Build from Source" option is absent. A reader on the beginner path has no way to
follow the step as written.

Fix: either (a) add a precondition note that Build from Source requires
--with-builds, and document the Deploy-from-Image alternative
(ghcr.io/kagenti/agent-examples/weather_service:latest), or (b) make the demo use
Deploy-from-Image by default (matching the weather-tool step, which already does).

3. Wrong expected agent-card name (L446)

Step 6 says:

# Expected: "weather_service"

The agent's actual A2A card name is Weather Assistant (see
agent-examples a2a/weather_service/src/weather_service/agent.py, name="Weather Assistant").
Live confirmation:

$ kubectl exec -n team1 test-client -- curl -s \
    http://weather-service:8080/.well-known/agent.json | jq -r .name
Weather Assistant

Fix: change the expected value to Weather Assistant.

Environment

  • Kagenti installed via setup-kagenti.sh --with-spire --with-ui --with-backend on Kind
  • kagenti-operator-chart 0.3.0-alpha.6
  • All three verified 2026-07-13 against a running cluster

Assisted-By: Claude Code

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with authbridge/demos/weather-agent/demo-ui.md at the cited sections and compare the secret details with the operator configuration and the weather-agent source at a2a/weather_service/src/weather_service/agent.py. Correct all four secret references, document the --with-builds prerequisite or image alternative, and update the expected card name; verify the revised commands and values against the described cluster behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes, shell
Domain
devops, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.