✨ Optional Agent gateways, default content, and operator manifest sync

[djzager]

Three intertwined workstreams in one PR.

#209 — Agent.spec.gateways is optional

The gateway list becomes a presence-gated curation constraint:

• When an Agent declares gateways, an AgentRun's gateway must be one of them (an architect can lock an Agent to specific gateways). A single declared gateway is defaulted for runs that omit one.
• When the list is empty/omitted, the controller constrains nothing — the AgentRun must name a gateway itself, which must exist and be Ready.
• An Agent with no gateways is a valid, Ready template, so curated Agents can ship without binding to a customer's Gateway.
• Adds a GatewayConfigured status condition (NoGatewaysDeclared / GatewaysNotReady / GatewaysReady), separate from Ready, so the UI can surface not-runnable state the Kubernetes-native way without treating the Agent as unhealthy.

#210 — Ship default content

• New config/defaults/ holds the curated content the operator installs on enable: the plan/execute/verify SkillCards, the java-migration SkillCollection, the stage Agents (no gateway), and the java-ee-to-quarkus AgentWorkflow.
• config/samples/ now holds only illustrative CRs you copy and edit (per-provider Gateways + a standalone example Agent/AgentRun).
• The gcp-vertex-ai placeholder is dropped from the shipped Agents.
• CONTEXT.md gains a Packaging glossary (Default vs. Sample); README and getting-started updated.

#190 — Push-sync to the operator

• hack/sync-operator.sh renders CRDs (verbatim), RBAC (textual rename + label-strip, byte-identical to the operator's committed role files), and config/defaults/ into a konveyor/operator checkout.
• .github/workflows/sync-operator.yml runs on merge to main/release-*: syncs, runs make bundle to regenerate the CSV, filters CSV createdAt churn, and force-pushes a fixed branch to open (or update) one PR on konveyor/operator via the Konveyor CI app.

Testing

make test (79% controller coverage), make lint (0 issues), and changelog validation all pass. The full sync pipeline was verified end-to-end against a real konveyor/operator clone (first-sync detection, no-op idempotency, deterministic RBAC render).

Manual follow-ups on konveyor/operator (one-time)

• Wire an Ansible task in roles/tackle/tasks/agentic.yml to k8s apply the synced roles/tackle/templates/agentic/defaults/*.yaml into the enabled namespace (the sync lands the files; applying them is the operator's job).
• Confirm the Konveyor CI app has contents:write + pull_requests:write on konveyor/operator.

Closes #209
Closes #210
Closes #190

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 5a80ae38-c830-4fdc-99d8-e0ce340d794d

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[ibolton336]

Read through all three workstreams — the design hangs together well (optional gateways is exactly what lets the shipped default Agents be gateway-free and therefore safe to sync into the operator). validateGateway covers all the branches correctly, every other Spec.Gateways use is empty-safe, and the deployment_parity_test anti-drift guard is a nice touch. Two minor things, neither blocking:

1. Mistyped gateway on a no-gateways Agent never terminates. With a non-empty list, a bad spec.gateway fails fast → terminal Failed (InvalidGateway). With an empty list, validateGateway accepts any name, so a nonexistent gateway flows into createSandbox, hits NotFound, and is treated as transient → Succeeded=Unknown "SandboxCreationFailed", requeuing indefinitely rather than reaching Failed. Message is clear and it's arguably consistent with existing transient-createSandbox handling (a gateway could be created later), so this may be intended — just flagging the asymmetry against the "fail fast" rationale in the comments. Deliberate?

2. sync-operator.sh clears the defaults dir but not the CRD dir. defaults_dir is rm -f'd before copy so a removed default disappears downstream, but the CRD copy is a plain cp konveyor.io_*.yaml — a renamed/removed CRD would leave a stale file in the operator. Low likelihood, just inconsistent with the defaults handling.

One note on the operator-side follow-up: until the Ansible k8s apply task lands, the sync copies the default-content files but nothing applies them, so the "populated UI day one" goal isn't live yet. Worth making sure that task doesn't get lost.

[savitharaghunathan]

Nice work pulling these three workstreams together — the docstrings and comments make the intent really easy to follow. Here's what stood out, starting with the ones I'd want eyes on first:

Gateway validation gap for zero-gateway Agents

In validateGateway (agentrun_controller.go:413), when the Agent has no declared gateways, we accept whatever run.Spec.Gateway the user typed without checking it exists. That's fine as a design ("createSandbox will catch it"), but the failure mode is different from what we do elsewhere: a typo'd gateway name surfaces later in buildEnvVars as SandboxCreationFailed with ConditionUnknown, which gets retried forever with backoff — instead of failing fast with a terminal condition like the membership-violation case does. Might be worth treating "gateway doesn't exist" as terminal here too, since a typo isn't going to fix itself on retry.

Workflow gateway errors point users at the wrong resource

The default java-ee-to-quarkus stage Agents ship with no gateways, so if someone creates an AgentWorkflowRun without spec.gateway, the error ends up on the workflow-owned child AgentRun ("agent %q declares no gateways; select one via spec.gateway") — but that AgentRun is immutable and controller-managed, so there's nothing the user can actually do to it. On top of that, the parent AgentWorkflowRun only surfaces the child's Reason (InvalidGateway), not the actual message, so the guidance never reaches the resource the user can edit. Also worth noting: docs/getting-started.md's Workflows section and hack/harness-test/workflow-resources.yaml both use gateway-bearing Agents, so this path isn't exercised anywhere. Could we either propagate the message up to the AgentWorkflowRun, or have the error explicitly say "set spec.gateway on the AgentWorkflowRun"?

A couple of stale config/samples/ references from the defaults split

Now that SkillCards/SkillCollections moved to config/defaults/, these two spots still point at config/samples/:

• hack/setup-e2e.sh:138-146 applies config/samples/ then asserts kubectl get skillcards/skillcollections — this will just print "No resources found" now.
• config/default/kustomization.yaml:21's comment still says "Apply with: kubectl apply -k config/samples/ -n <namespace>" for default skill resources.

Missing printcolumn for the new condition

GatewayConfigured (api/v1alpha1/agent_types.go) doesn't have a +kubebuilder:printcolumn, so kubectl get agents won't show it even though the whole point per the comment is to surface not-runnable state "the Kubernetes-native way." SkillCard's Resolvable condition has one — could we add the same here?

Two smaller ones on the operator sync workflow

• hack/sync-operator.sh:64 renames the RBAC role via an exact-string/indentation-sniffing awk script. Since yq is already a build dependency, might be more robust to use that — if controller-gen ever reformats the RBAC YAML, this awk silently no-ops and we'd ship a name collision into the operator's helm chart without any error.
• .github/workflows/sync-operator.yml:76 checks out konveyor/operator at the exact same branch name as the trigger, with no fallback. If we ever cut a new release-* branch here before the matching branch exists upstream, every sync run on that branch fails until someone manually creates it there.

Nothing here feels blocking except maybe the first two — happy to pair on either if useful!

[ibolton336]

One blocking workflow-reliability finding is inline; I did not find a controller state-machine regression. Non-blocking documentation mismatch: AgentRunSpec.Gateway (and therefore its CRD description) still says the gateway must be declared on the Agent, but this PR allows any Ready Gateway when the Agent list is empty.

Validated the exact head with clean generation/gofmt drift checks, go vet ./..., and the full non-e2e go test suite. actionlint, both kustomize renders, and a two-pass operator-sync smoke/idempotence test also passed. DCO is green; the remaining CI jobs were still in progress when reviewed.

[ibolton336]

Blocking: This treats every gh api failure as “branch absent” and lets the job succeed. GitHub also returns 404 when the App cannot access konveyor/operator, so the bot installation/permission issue called out in the PR description would be silently masked and no sync PR would appear; 5xx/network failures are swallowed too. Please skip only a confirmed missing-branch response and fail on repository-access/auth or other API errors.

[savitharaghunathan]

Two things I'd love a second look at before this merges — nothing blocking, just flagging for discussion.

[savitharaghunathan]

Nice catch extending the fail-fast pattern to Gateway lookups for the unconstrained-Agent case — makes sense to match how validateGateway already handles a bad name on a constrained one.

One thing worth double-checking though: r.Get here reads through the manager's cache, and Gateway isn't excluded from it in cmd/main.go. If a Gateway, Agent, and AgentRun are applied together (e.g. one bundle/GitOps sync), there's a window where the informer hasn't synced the new Gateway yet, IsNotFound fires, and the AgentRun gets marked Failed/InvalidGateway permanently — since the spec is immutable, that means delete-and-recreate to recover from what was really just a timing issue, not a bad reference.

To be clear, this isn't new to this PR — the Agent lookup a few lines up (AgentNotFound) has had the exact same cache-vs-terminal-failure shape since #4, so this change is just staying consistent with existing behavior rather than introducing something novel. Might be worth a follow-up (maybe a short requeue-and-retry before declaring terminal, for both Agent and Gateway) rather than blocking this PR on it — curious what you think given you've clearly already thought about cache lag elsewhere in this file (the apiReader for pod termination messages).

[savitharaghunathan]

Small inconsistency here: the comment block says to "pick the one for your provider" and docs/getting-started.md applies exactly one gateway sample at a time with kubectl apply -f, but the kustomization aggregates all 5 provider Gateways as resources, and the header instructs kubectl apply -k config/samples/. If someone follows the header literally instead of getting-started.md, they'll end up creating all 5 Gateways at once, most referencing Secrets they never made.

Might just need the header comment/resources list trimmed down to match the "pick one" intent — happy to be wrong if there's a reason to keep all 5 wired up here.