[github-actions]

kagent-dev/kagent#3179 — refactor: simplify config parsing and compiler inputs

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

No code-path rule covers 14 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/process-configuration.md
• go/api/gen/kagent/api/v1alpha1/config.pb.go
• go/core/internal/controller/collections.go
• go/core/internal/controller/reconciler.go
• go/core/internal/controller/runtime.go
• go/core/internal/translator/images.go
• ...and 8 more

What changes for users: Controller configuration files now follow strict YAML-to-JSON conversion followed by ProtoJSON. Field null means unset, YAML anchors and merge keys are resolved before duplicate-key checks, only the first YAML document is read, and omitted or zero config.database.pool.minConns means zero minimum connections.

What the docs now say: The Operational considerations page now describes the parser behavior for duplicate keys, quoted booleans, YAML 1.1 scalars, anchors, merge keys, null values, and multiple documents. The PostgreSQL pool row now clarifies that minConns differs from the optional pool fields.

Not verified: No cluster; the configuration and commands are unrun.

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

• Code PR: refactor: simplify config parsing and compiler inputs kagent#3179
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha14
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Correct the controller configuration rules and minConns default on the page that already documents config.database.pool.
• Learned: The dossier diff shows minConns changed to an ordinary scalar and the local target page already owned both controller parsing rules and pool sizing.
• Did: Updated docs-site/content/kagent/1.x/operations/operational-considerations.md and left the other code-path target pages unchanged.

Why a documentation change is necessary

The pull request changes the controller config loader to use strict YAML conversion followed by ProtoJSON, and the code diff documents how null values, merge keys, aliases, scalar conversion, quoted booleans, and multiple documents behave. The target page still said that null values, YAML aliases or merges, and files with more than one document are rejected. The same page also said that omitting all pool fields keeps pgx defaults, but the diff changes database.pool.minConns so omission and explicit zero both mean zero.

What changed on disk

• docs-site/content/kagent/1.x/operations/operational-considerations.md — Updated controller configuration parsing rules and clarified config.database.pool.minConns default behavior.

How to verify this change

1. Create a controller config file that uses the documented accepted parser behavior.

   cat > controller.yaml <<'EOF'
   database:
     pool:
       minConns: null
       maxConns: 4
   ---
   database:
     pool:
       minConns: 99
   EOF

2. Validate the file. The command should finish without an error, because minConns: null is unset and only the first YAML document is read.

   kagent config validate --component controller --config controller.yaml

3. Change minConns to a value greater than maxConns and validate again. The command should fail because the effective minimum connection count exceeds maxConns.

   cat > controller.yaml <<'EOF'
   database:
     pool:
       minConns: 9
       maxConns: 4
   EOF
   kagent config validate --component controller --config controller.yaml

What was not verified

• The configuration was not applied to a cluster, and the helm, kubectl, and kagent commands in the guide and report are unrun.

How the pages were chosen (triage report)

Feature clusters

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• refactor(adk): generate runtime configuration from protobuf kagent#3162 and refactor: simplify config parsing and compiler inputs kagent#3179 are a stacked pair (one depends on the other), which is a delivery detail rather than a shared feature

Draft a documentation change

kagent-dev/kagent#3179 — refactor: simplify config parsing and compiler inputs

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): This removes CompilerSettings and BuiltinImages and passes the existing protobuf config messages directly to the compilers. Release validation stays at startup, and the translator still selects and validates Harness images. Config files now use strict YAML-to-JSON conversion followed by ProtoJSON, with the library's parsing behavior documented instead of maintaining a custom YAML tree walker.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 14 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/process-configuration.md
  • go/api/gen/kagent/api/v1alpha1/config.pb.go
  • go/core/internal/controller/collections.go
  • go/core/internal/controller/reconciler.go
  • go/core/internal/controller/runtime.go
  • go/core/internal/translator/images.go
  • ...and 8 more

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

---

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.

[github-actions]

Docs preview

Link	Points at
Branch preview	The newest push to this branch. Updates in place.
Commit preview	2b51324 only. Frozen.

Both are uploaded Worker versions and serve no production traffic.