:book: ADR 0006 — application id as a queryable label, not only an env var by ibolton336 · Pull Request #105 · konveyor/agentic-controller

ibolton336 · 2026-08-05T15:56:00Z

Problem. The UI needs "show me this application's runs" (the application
detail drawer, konveyor/tackle2-ui#3521). Runs live only in etcd — this ADR
keeps no database copies — so when Hub filters a run list, it has exactly two
options: pass a label selector to the apiserver, or fetch every run and scan
it in the handler. The application id currently lives only in spec.env, so
there is nothing to select on: the scan is the only option, on every request
(reads are request-driven, no informer cache), and it couples Hub's query path
to the pod's input format — an env surface #108 is actively reshaping.

Fix (14 lines):

Hub writes the id as a label at create time: konveyor.io/application: "42"
Run list endpoints take ?application=42, answered by a label selector

APP_ID doesn't change — the harness still reads it inside the pod. The label
is the same value, put where list queries can use it. It also works outside
Hub: kubectl get agentruns -l konveyor.io/application=42 answers the same
question when debugging a cluster.

Edge cases recorded in the diff: runs created before the label aren't matched;
an invalid filter is an error instead of an unfiltered list; workflow stage
runs don't get the label yet (#107).

Already working in the shim prototype: ibolton336/agentcontroller-client#3.

🤖 Generated with Claude Code

coderabbitai · 2026-08-05T15:56:26Z

📝 Walkthrough

Walkthrough

The ADR documents application label stamping for created AgentRuns and application filtering for AgentRun list endpoints. It also defines unsupported-filter errors, pre-label exclusions, and missing labels on workflow stage runs.

Changes

AgentRun application semantics

Layer / File(s)	Summary
Application label stamping `docs/adr/0006-hub-addon-pattern-for-agent-resources.md`	The ADR documents `konveyor.io/application` labels on created AgentRuns when an application ID is provided. It distinguishes the label from `APP_ID`.
Application-based AgentRun filtering `docs/adr/0006-hub-addon-pattern-for-agent-resources.md`	AgentRun list endpoints support `?application=` filtering through the application label. The ADR documents unsupported-filter errors, pre-label exclusions, and the lack of inherited labels on workflow stage AgentRuns.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

konveyor/agentic-controller#64: Modifies ADR 0006 with related Hub-managed AgentRun integration details.
konveyor/agentic-controller#80: Defines related AgentWorkflowRun labeling and filtering behavior.
konveyor/agentic-controller#106: Addresses overlapping application-labeling and application-aware AgentRun behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title uses the required 📖 prefix and clearly identifies the ADR change to make the application ID queryable as a label.
Description check	✅ Passed	The description clearly explains the problem, fix, unchanged APP_ID behavior, edge cases, and prototype verification; the docs prefix does not require a changelog fragment.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/adr/0006-hub-addon-pattern-for-agent-resources.md`:
- Around line 53-57: Update the ADR’s validation guidance around hub.ParseAppID
so application IDs are also constrained to Kubernetes’ 63-character label-value
maximum before being used as labels, or revise the claim that numeric validation
alone covers apiserver acceptance. Keep the shared validation behavior and
documented harness/apiserver relationship consistent.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 14c6a0a1-88af-4567-954e-c3872aa20297

📥 Commits

Reviewing files that changed from the base of the PR and between 059b6f6 and c60fbe5.

📒 Files selected for processing (1)

docs/adr/0006-hub-addon-pattern-for-agent-resources.md

coderabbitai · 2026-08-05T16:09:06Z

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

Validation Failed: {"resource":"IssueComment","code":"custom","field":"body","message":"body is too long (maximum is 65536 characters)"} - https://docs.github.com/rest/issues/comments#update-an-issue-comment

Review on the upstream ADR amendment (konveyor/agentic-controller#105) caught a real gap: the guard's /^\d+$/ accepted any digit string, but the harness's hub.ParseAppID is strconv.ParseUint(s, 10, 64) — a 21-digit id passed the shim and then killed the run at startup, the exact doomed-run class the guard exists to pre-empt. Unbounded digits could also exceed the apiserver's 63-char label-value limit. invalidApplicationIdReason now rejects values above uint64 max (BigInt compare, exact at the boundary: ...551615 valid, ...551616 rejected). Smoke gains the overflow reject case; ADR 0010's claim is restated with the bound that makes it true. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The application id rides only spec.env today, so "which runs belong to application 42?" has no server-side answer — a caller must list every run and parse env. Stamp konveyor.io/application at create time and let the run lists take ?application=<id> as a label selector. Additive: the harness keeps reading APP_ID; ids are uint64 so they are always valid label values. Stage-run label inheritance is konveyor#107. Verified end-to-end in the hub-shim prototype (ibolton336/agentcontroller-client#3). Signed-off-by: ibolton336 <ibolton@redhat.com>

coderabbitai · 2026-08-05T20:19:13Z

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

…params) (#106) > **Renumbered 0012/0013** — #108 claimed 0009–0011 for params.json / skill boundary / execution controls shortly after this opened; the maintainer series keeps those. Content otherwise unchanged, plus cross-references to #108's params.json ADR where these touch the KONVEYOR_PARAM_* carrier: that ADR covers how values reach the pod, these cover where values come from and the client-facing contract — complementary layers. Two ADRs that have been steering this work since July but live in a personal prototype repo. #22 and konveyor/enhancements#295 both cite them by URL — which means decisions the platform depends on are currently sourced from a playground. Moving them here. No content invented for this PR: both are as-written, adjusted only for their new home (numbering, and a provenance line on each). ## ADR 0012 — verified client contract and layered transports Freezes what the live controller **actually exhibits**, verified against PR #4 on a real cluster rather than inferred from the types. The load-bearing ones, because each has already bitten a client: - **Pod resolution is by `status.sandboxName`, exactly** — never by label (the pod carries only `agents.x-k8s.io/sandbox-name-hash`, there is no `konveyor.io/agentrun` label on it) and never by string-munging the run name. - **The auto-created Service is headless** — clients must dial the pod. - **ACP key secret** data-key order: `secret-key`, then `ACP_SECRET_KEY`, then sole-entry fallback. - **Spec is immutable**, so every "edit"/"retry" affordance in a UI is defined as delete + recreate. Run identity is per-attempt. It also records **SHIM HTTP API v1** — the route table the hub-shim serves today and the shape the Hub passthrough proxy is expected to expose. That table is a concrete acceptance contract for #72: browser UIs written against it should keep working when Hub replaces the shim. ## ADR 0013 — platform-resolved params Where a param's *value* comes from, so a create form can collapse to "application picker + instructions" without hard-coding per-agent knowledge. The decision worth arguing about: **source identifiers are free-form namespaced strings, not a CRD enum.** An enum bakes one consumer's (Hub's) domain vocabulary into a generic CRD whose own controller ignores the field, and every new value becomes a schema upgrade whose skew fails *closed* — an older CRD rejects newer Agent manifests at admission. Namespaced strings follow the `storageClassName`/`ingressClassName` precedent and fail *open*. Also here: the managed-agent label, and the open question this hits at the Hub boundary — repo URL and branch are plain fields, but a credential is an `Identity` in Hub's encrypted vault and the REST API exposes only its name. Materializing it into the sandbox is something only Hub can do; the shim can bridge known identity names to a pre-created Secret and no more. That bridge is the one honest stub left in the flow. ## Note on the label subsection ADR 0013's managed-label section also records `konveyor.io/application`, which #105 proposes amending ADR 0006 to adopt. If #105 is rejected, that subsection goes with it — the rest of both ADRs is independent of that outcome. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  ## Summary by CodeRabbit * **Documentation** * Added architecture guidance for the AgentRun client, supported transports, and SHIM API. * Documented Kubernetes resource resolution, authentication, endpoint behavior, and edit/retry semantics. * Defined platform-resolved agent parameters and credentials, including validation and application-aware run creation. * Added REST and WebSocket API specifications for applications, agents, gateways, skills, runs, workflows, and ACP connections. * Documented request formats, response behavior, validation errors, authentication, CORS, and lifecycle rules. * Recorded compatibility considerations, known gaps, and open platform questions.  --------- Signed-off-by: ibolton336 <ibolton@redhat.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

…params) (konveyor#106) > **Renumbered 0012/0013** — konveyor#108 claimed 0009–0011 for params.json / skill boundary / execution controls shortly after this opened; the maintainer series keeps those. Content otherwise unchanged, plus cross-references to konveyor#108's params.json ADR where these touch the KONVEYOR_PARAM_* carrier: that ADR covers how values reach the pod, these cover where values come from and the client-facing contract — complementary layers. Two ADRs that have been steering this work since July but live in a personal prototype repo. konveyor#22 and konveyor/enhancements#295 both cite them by URL — which means decisions the platform depends on are currently sourced from a playground. Moving them here. No content invented for this PR: both are as-written, adjusted only for their new home (numbering, and a provenance line on each). ## ADR 0012 — verified client contract and layered transports Freezes what the live controller **actually exhibits**, verified against PR konveyor#4 on a real cluster rather than inferred from the types. The load-bearing ones, because each has already bitten a client: - **Pod resolution is by `status.sandboxName`, exactly** — never by label (the pod carries only `agents.x-k8s.io/sandbox-name-hash`, there is no `konveyor.io/agentrun` label on it) and never by string-munging the run name. - **The auto-created Service is headless** — clients must dial the pod. - **ACP key secret** data-key order: `secret-key`, then `ACP_SECRET_KEY`, then sole-entry fallback. - **Spec is immutable**, so every "edit"/"retry" affordance in a UI is defined as delete + recreate. Run identity is per-attempt. It also records **SHIM HTTP API v1** — the route table the hub-shim serves today and the shape the Hub passthrough proxy is expected to expose. That table is a concrete acceptance contract for konveyor#72: browser UIs written against it should keep working when Hub replaces the shim. ## ADR 0013 — platform-resolved params Where a param's *value* comes from, so a create form can collapse to "application picker + instructions" without hard-coding per-agent knowledge. The decision worth arguing about: **source identifiers are free-form namespaced strings, not a CRD enum.** An enum bakes one consumer's (Hub's) domain vocabulary into a generic CRD whose own controller ignores the field, and every new value becomes a schema upgrade whose skew fails *closed* — an older CRD rejects newer Agent manifests at admission. Namespaced strings follow the `storageClassName`/`ingressClassName` precedent and fail *open*. Also here: the managed-agent label, and the open question this hits at the Hub boundary — repo URL and branch are plain fields, but a credential is an `Identity` in Hub's encrypted vault and the REST API exposes only its name. Materializing it into the sandbox is something only Hub can do; the shim can bridge known identity names to a pre-created Secret and no more. That bridge is the one honest stub left in the flow. ## Note on the label subsection ADR 0013's managed-label section also records `konveyor.io/application`, which konveyor#105 proposes amending ADR 0006 to adopt. If konveyor#105 is rejected, that subsection goes with it — the rest of both ADRs is independent of that outcome. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  ## Summary by CodeRabbit * **Documentation** * Added architecture guidance for the AgentRun client, supported transports, and SHIM API. * Documented Kubernetes resource resolution, authentication, endpoint behavior, and edit/retry semantics. * Defined platform-resolved agent parameters and credentials, including validation and application-aware run creation. * Added REST and WebSocket API specifications for applications, agents, gateways, skills, runs, workflows, and ACP connections. * Documented request formats, response behavior, validation errors, authentication, CORS, and lifecycle rules. * Recorded compatibility considerations, known gaps, and open platform questions.  --------- Signed-off-by: ibolton336 <ibolton@redhat.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

coderabbitai Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread docs/adr/0006-hub-addon-pattern-for-agent-resources.md Outdated

This was referenced Aug 5, 2026

📖 Contribute ADRs 0012 (client contract) and 0013 (platform-resolved params) #106

Merged

Stage AgentRuns do not inherit the parent AgentWorkflowRun's labels #107

Closed

3.1: API client layer #22

Open

Stream 2: Hub integration (konveyor/tackle2-hub) #72

Open

ibolton336 force-pushed the adr/0006-application-label branch from 0cd4405 to d8a8913 Compare August 5, 2026 16:08

ibolton336 changed the title ~~docs: ADR 0006 — application id as a queryable label, not only an env var~~ 📖 ADR 0006 — application id as a queryable label, not only an env var Aug 5, 2026

ibolton336 mentioned this pull request Aug 5, 2026

feat(hub-shim): label runs with their application and filter on it ibolton336/agentcontroller-client#7

Closed

ibolton336 force-pushed the adr/0006-application-label branch from d8a8913 to 0323b29 Compare August 5, 2026 16:22

ibolton336 mentioned this pull request Aug 5, 2026

UI: surface AgentPlaybookRuns in the reference client stack #50

Closed

7 tasks

ibolton336 force-pushed the adr/0006-application-label branch from 0323b29 to 3994132 Compare August 5, 2026 20:19

djzager approved these changes Aug 6, 2026

View reviewed changes

ibolton336 merged commit a48445d into konveyor:main Aug 6, 2026
18 checks passed

coderabbitai Bot mentioned this pull request Aug 7, 2026

🐛 Stage AgentRuns inherit the parent AgentWorkflowRun's labels #113

Merged

Navigation Menu

Uh oh!

📖 ADR 0006 — application id as a queryable label, not only an env var - #105

📖 ADR 0006 — application id as a queryable label, not only an env var#105
ibolton336 merged 1 commit into
konveyor:mainfrom
ibolton336:adr/0006-application-label

ibolton336 commented Aug 5, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 5, 2026

Uh oh!

coderabbitai Bot commented Aug 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ibolton336 commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 5, 2026

Uh oh!

coderabbitai Bot commented Aug 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ibolton336 commented Aug 5, 2026 •

edited

Loading

coderabbitai Bot commented Aug 5, 2026 •

edited

Loading