Operations
Local port, provider keys, Service Bus topology, and deployment status for the broker service.
Broker is not in DEPLOYED_SERVICES yet, so its paths stay out of the merged platform OpenAPI
document. The Azure pipeline deploys the Helm releases below.
A failed relay request log includes provider, model, actor, the upstream
HTTP status and body, and error. Other handler failures set error to the
cause (Cedar deny includes fid and action).
Local
| Process | broker-api |
| Port | 8125 |
| Database | broker on the shared local Postgres |
| Auth | DEV_AUTH=1 and X-Dev-Principal |
8122 and 8123 are retired and never reused. See tools/localenv/ports.yaml.
Provider keys use the same names as data-broker. Name them from services/broker/.env.example locally and from services/broker/.azure/env/secrets.dev.yaml.example on Azure:
ANTHROPIC_API_KEYOPENAI_API_KEYXAI_API_KEYOPENROUTER_API_KEY
Put local values in services/broker/.env. Put deployed values in
secrets.<env>.yaml with helm secrets edit. An empty key is valid: the catalog
still lists the models, with available=false.
BROKER_PLATFORM_ADMINS is a comma-separated list of emails that receive platform-admin
on first sight.
Service Bus topology
services/broker/.azure/bus/topology.yaml declares domain usage with
subscriber listener. usageListener consumes broker-usage-queue-listener and logs each
message. Only name a subscriber that has a reader — a queue nobody reads fills until its
messages dead-letter.
Configuration
Values that are not secret are committed in .azure/env/config.<env>.yaml. The rest is encrypted
with SOPS in a file next to it. The committed secrets files are still the template pair, so
provider keys are not present until they are added with helm secrets edit.
services/broker/.azure/env/readme.md lists every key, which file it
belongs in, and why.
One image, several releases
| Helm release | Binary | Chart |
|---|---|---|
broker-api | /service (default) | k8s/ |
broker-usagelistener | /usageListener | k8s/ |
Dev API ingress: broker-api.dev.apps-and-services.com
(services/broker/.azure/k8s/values/api.dev.yaml); prod is
broker-api.apps-and-services.com.
Pipeline
services/broker/.azure/azure-pipelines.yml triggers on develop /
master changes under services/broker. The Helm install step applies every entry in that
file's charts list. Stages match template's: decrypt SOPS secrets, build the image from the
repository root, busctl plan (exit 2 additive, exit 3 destructive and gated by a manual
approval), apply, then helm upgrade --install per chart.
Migrations
Goose SQL in services/broker/migrations/. cmd/api -migrate is a
separate invocation, not startup. Seed prices live in 0003_seed_catalog.sql. A new model, and a later
price change, is a new migration. 0008_grok_4_7.sql adds grok-4.7.
0013_routing_default_on.sql turns routing on for everyone, 0014_routing_decisions.sql
adds the decision log and why a call was routed, 0015_credential_kinds.sql adds
credential kinds and people.creator_fid, 0016_jev_classifier.sql adds Jev to the
catalog with no price, and 0017_auto_route_changed.sql records when routing was turned
on or off for a person and by whom. A price
change inserts a broker_model_prices row with a new effective_from.