[Automated] Draft docs (kagent): fix: make push notification JWT signing optional with operator-managed…

[github-actions]

kagent-dev/kagent#3122 — fix: make push notification JWT signing optional with operator-managed PEM keys

Docs versions: 1.x (first shipped in v1.0.0-alpha11)

What changes for users: A2A push notifications still work when no signing key is configured, but callbacks are unsigned and the JWKS endpoint returns 404. To send signed callbacks, operators now provide an unencrypted PKCS#8 Ed25519 key in a Secret and set controller.push.signing.secretName; the old generated seed Secret is gone.

What the docs now say: The operational considerations page now shows how to generate the key, store it as private-key.pem, set controller.push.signing.secretName, keep the issuer stable, and rotate the key across controller replicas.

Not verified: A cluster API surface was captured in cluster-facts.md, but no configuration was applied; the steps are unrun.

How kagent-3122 was drafted, and what was not verified

• Code PR: fix: make push notification JWT signing optional with operator-managed PEM keys kagent#3122
• Code issue: none linked
• Product: kagent (upstream) -> kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha11. The product publishes one rolling 1.x tree, so the release confirms that the change is out rather than choosing another tree.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document the push signing Helm values on the page that owns production controller configuration.
• Learned: agent-memory.md matched only database Secret examples, and reference/helm.md is generated; operations/operational-considerations.md is the specific editable page for production controller settings.
• Did: Added a push notification signing section to operations/operational-considerations.md and wrote a proposed release note.

Why a documentation change is necessary

The pull request changes the push notification signing model from a base64 seed value and chart-managed Secret to an operator-managed Secret that contains an unencrypted PKCS#8 Ed25519 PEM key. It also makes signing optional, so push notifications are sent without an Authorization header by default. The existing website docs did not tell production operators how to configure the new controller.push.signing.secretName field or what happens when they leave it empty.

What changed on disk

• docs-site/content/kagent/1.x/operations/operational-considerations.md — Added a section that documents optional push notification JWT signing, the private-key.pem Secret shape, the controller.push.signing.secretName and controller.push.signing.issuer values, and the rotation requirement for controller replicas.

How to verify this change

1. Create a signing key and Secret.

   openssl genpkey -algorithm ED25519 -out private-key.pem
   kubectl create secret generic kagent-push-signing -n kagent \
     --from-file=private-key.pem

2. Upgrade kagent with controller.push.signing.secretName: kagent-push-signing and a stable controller.push.signing.issuer.

   helm upgrade kagent \
     oci://ghcr.io/kagent-dev/kagent/helm/kagent \
     --namespace kagent \
     --reuse-values \
     --values kagent.yaml

3. Port-forward the controller service and read the JWKS endpoint.

   kubectl port-forward -n kagent svc/kagent-controller 8083:8083
   curl -s http://localhost:8083/.well-known/jwks.json | jq -r '.keys[0].kty'

   The command prints OKP when signing is enabled. With controller.push.signing.secretName omitted, the same endpoint returns 404 and push callbacks have no Authorization header.

What was not verified

The configuration was not applied to a cluster, so every command in this diff is unrun. cluster-facts.md lists the installed CRDs, but this change documents Helm values and runtime behavior from the dossier diff rather than a live apply.

How the pages were chosen (triage report)

Draft a documentation change

kagent-dev/kagent#3122 — fix: make push notification JWT signing optional with operator-managed PEM keys

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Follow up to feat: a2a task push notifications kagent#3036 (comment). Accept Ed25519 signing keys in PEM format through existingSecret, replaces the old seed value. Remove render-time key generation so deployments reuse an operator-managed key. When no key is provided, push notification still works but JWT signing and JWKS publication will not be enabled.
• Not tested: a cluster was used only to dry-run the YAML manifests the draft added; prose, inline field paths and commands are unrun
• No rule covers 6 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/a2a-push-notifications.md
  • docs/env.md
  • go/core/internal/service/session/push_jwt.go
  • go/core/internal/service/session/push_notifications.go
  • go/core/pkg/app/app.go
  • go/core/pkg/env/kagent.go

Draft branch: pr-tracker-draft-kagent-3122

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. This repository's checks are held as action_required until somebody presses Approve and run on the Checks tab. Checks that come from GitHub Apps rather than Actions, such as DCO, run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[Rachael-Graham]

Absorbed into #591 (commit 0ef30c0), rewritten against the current page rather than merged — this branch was cut before main's rewrite of operational-considerations.md, so it conflicts with main on its own.

controller.push.signing.secretName and .issuer both confirmed present at v1.0.0-alpha12. Two changes from the draft: the numbered helm upgrade step was dropped, because every other setting on that page shows the values block and leaves the upgrade implicit; and A2A is now spelled out, since this section lands before the page's previous first use.