Skip to content

Reference declarative agents by tag; digests only for sandbox agents - #2242

Merged
EItanya merged 1 commit into
mainfrom
iplay88keys/agent-image-tags
Jul 15, 2026
Merged

EItanya merged 1 commit into
mainfrom
iplay88keys/agent-image-tags

Conversation

@iplay88keys

@iplay88keys iplay88keys commented Jul 14, 2026 •

Copy link
Copy Markdown
Contributor

Description

Declarative agent images are now referenced by tag (registry/repository:tag), honoring --image-tag / Helm IMAGE_TAG. Digest-pinned references (registry/repository@sha256:...) are only used for sandbox agents, where Substrate ActorTemplate validation rejects tag refs.

  • Regular agents: resolvePythonRuntimeImage / resolveGoRuntimeImage emit registry/repo:tag; full variants (skills / SRT) use the <tag>-full convention the Makefile publishes (APP_FULL_IMAGE_TAG, GOLANG_ADK_FULL_IMAGE_TAG).
  • Sandbox agents (SandboxAgent, workload mode sandbox): unchanged digest pinning from the link-time digests.
  • New controller flags to override the link-time digests for sandbox agents when a mirror re-assigns digests: --app-image-digest, --app-full-image-digest, --golang-adk-image-digest, --golang-adk-full-image-digest (env: APP_IMAGE_DIGEST, etc.). Defaults are the digests baked in at build time.
  • No Helm changes: IMAGE_TAG was already plumbed through the controller ConfigMap; the digest overrides are settable via controller env.

Supersedes #2076, following the approach requested in its review: tags for standard deployments, digests kept only where Substrate requires them, rather than an opt-out flag.

Fixes #2055

Test plan

  • go test ./core/internal/controller/translator/agent/... — regular-agent tests now assert tag refs (and no @sha256:), sandbox-agent test asserts digest refs, new unit tests cover tag resolution including the -full suffix and the missing-digest error.
  • Golden files regenerated (UPDATE_GOLDEN=true): all 35 regular-agent outputs change app@sha256:... → app:dev.

@iplay88keys
iplay88keys marked this pull request as ready for review July 14, 2026 16:29
@iplay88keys
iplay88keys requested a review from a team as a code owner July 14, 2026 16:29
Copilot AI review requested due to automatic review settings July 14, 2026 16:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

Updates declarative agent runtime image resolution to reference standard agents by tag (honoring --image-tag / Helm IMAGE_TAG) while keeping digest-pinned image references for sandbox agents due to Substrate ActorTemplate validation requirements.

Changes:

  • Add controller flags to override baked-in sandbox runtime image digests (--python-adk-*-image-digest, --golang-adk-*-image-digest).
  • Switch regular (non-sandbox) agent runtime images from digest-pinned references to tag-based references, using -full tag suffix for full variants.
  • Update translator golden test outputs and unit tests to reflect tag-based image refs for regular agents and digest pinning for sandbox agents.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
go/core/pkg/app/app.go Adds new CLI flags for overriding sandbox runtime image digests.
go/core/internal/controller/translator/agent/deployments.go Implements shared image resolution helper that chooses tag vs digest pinning based on sandbox mode.
go/core/internal/controller/translator/agent/adk_api_translator.go Updates documentation around digest defaults/overrides and when they apply.
go/core/internal/controller/translator/agent/runtime_test.go Adjusts runtime tests to assert tag refs for regular agents and prohibit digest pinning.
go/core/internal/controller/translator/agent/imageconfig_test.go Updates digest-related tests and adds coverage for tag-based resolution and sandbox pinning behavior.
go/core/internal/controller/translator/agent/testdata/outputs/*.json Updates golden manifests from @sha256:... to :tag for regular agent images (and :tag-full for full variants).
Comments suppressed due to low confidence (1)

go/core/pkg/app/app.go:1

  • These flag descriptions imply the value must be in "sha256:..." form, but normalizeImageDigest() accepts values both with and without the "sha256:" prefix. Consider updating the help text to explicitly allow both formats (and optionally mention the env var equivalents if that's the intended primary config path in Helm) to reduce operator confusion.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated no new comments.

@EItanya
EItanya merged commit 807c568 into main Jul 15, 2026
34 checks passed
@EItanya
EItanya deleted the iplay88keys/agent-image-tags branch July 15, 2026 19:05
@iplay88keys

Copy link
Copy Markdown
Contributor Author

Backport to 0.9.x: #2266

QuentinBisson added a commit to QuentinBisson/kagent that referenced this pull request Jul 17, 2026
Adapts to kagent-dev#2242 (declarative agents referenced by tag, digests only for
sandbox agents):
- DefaultGoImageConfig defaults to ghcr.io/kagent-dev/kagent/golang-adk
  and now carries a Tag (regular Go agents are tag-referenced)
- resolveRuntimeImage takes the tag as a parameter so the Go runtime
  resolves via DefaultGoImageConfig.Tag
- new --go-image-tag flag, controller.goAgentImage.tag Helm value and
  GO_IMAGE_TAG ConfigMap key (coalesced with global tag / Chart version)
- tests updated from digest to tag expectations; drops the upstream
  derivation test superseded by explicit Go image config
EItanya pushed a commit that referenced this pull request Jul 20, 2026
…r sandbox agents (#2242) (#2266)

## Description

Backport of #2242 (`807c5689`) to `release/v0.9.x`.

Fixes #2055 on 0.9.x (mirrored registries that re-assign manifest
digests could not resolve the link-time digest refs).

## Differences from #2242

`release/v0.9.x` predates the Python `-full` runtime variant
(`PythonADKFullImageDigest` / `APP_FULL_IMAGE_TAG` do not exist on this
branch), so:

- `resolvePythonRuntimeImage` gains only the `pinDigest` parameter — no
`full` parameter. The `full := runtime == Go && needsSRTSettings(...)`
computation stays Go-only, as on this branch.
- Three digest-override flags added instead of main's four:
`--app-image-digest`, `--golang-adk-image-digest`,
`--golang-adk-full-image-digest` (env: `APP_IMAGE_DIGEST`, etc.).
`--app-full-image-digest` is dropped with the variant it targets.
- New unit tests adapted to the two-arg Python signature and this
branch's default registry (`cr.kagent.dev`; main's tests use `ghcr.io`).
- The golden files were regenerated with `UPDATE_GOLDEN=true` rather
than hand-merged: each changes `app@sha256:test-app` → `app:dev`,
matching the shape of the change on main.

Additionally, digest pinning is gated on the substrate platform rather
than on sandbox workload mode. On main every `SandboxAgent` is a
substrate agent (no `spec.platform` field), so the workload-mode gate is
equivalent there; this branch also has the agent-sandbox platform, which
accepts tag refs. Pinning those by digest would have kept the
mirrored-registry breakage for them. Sandbox agents on the agent-sandbox
platform now get tag refs like regular agents; only substrate sandbox
agents pin by digest.

---------

Signed-off-by: Jeremy Alvis <[email protected]>
EItanya added a commit that referenced this pull request Jul 21, 2026
…figurable (#2021)

Fixes #2018.

## What

Adds `DefaultGoImageConfig` (registry, repository, tag, pullPolicy) so
the Go (ADK) runtime agent image is configured independently instead of
being derived from the Python repository by string surgery. Exposed
end-to-end as:

- `--go-image-{registry,repository,tag,pull-policy}` controller flags
(auto-mapped to `GO_IMAGE_*` env vars via `LoadFromEnv`)
- `controller.goAgentImage.{registry,repository,tag,pullPolicy}` Helm
values
- `GO_IMAGE_*` ConfigMap keys, following the same defaulting as
`agentImage`/`skillsInitImage` (registry/pullPolicy default to the
globals, tag coalesces with the global tag then the Chart version)

Defaults are encoded in the variable
(`ghcr.io/kagent-dev/kagent/golang-adk`), matching `DefaultImageConfig`
and `DefaultSkillsInitImageConfig`. Since #2242, regular declarative
agents reference the image by tag; sandbox agents still pin by digest
via `GoADKImageDigest` / `GoADKFullImageDigest`. The `-full` variant
selection is unchanged for both paths.

## Why

When `spec.declarative.runtime: go` is used, the controller derived the
Go runtime repository from the Python repository by replacing the last
path segment with `golang-adk`. This breaks for flat-name registry
layouts (e.g. a mirrored registry where the image is
`my-registry.io/kagent-golang-adk`, which the derivation cannot
produce).

## Breaking change

Operators who mirror images and only set `agentImage` no longer get a
derived Go image location; they must set `controller.goAgentImage` as
well. The controller logs a startup warning when the two registries
differ so a misconfigured mirror is visible before a Go agent fails to
pull. As discussed in the review thread, this targets a minor release
(0.10.x).

## Files changed

| File | Change |
|------|--------|
| `go/core/internal/controller/translator/agent/adk_api_translator.go` |
`DefaultGoImageConfig` with encoded defaults |
| `go/core/internal/controller/translator/agent/deployments.go` | Go
image resolution via `DefaultGoImageConfig`; tag threaded through
`resolveRuntimeImage` |
| `go/core/pkg/app/app.go` | four `--go-image-*` flags +
registry-mismatch startup warning |
| `helm/kagent/values.yaml` | `controller.goAgentImage` block |
| `helm/kagent/templates/controller-configmap.yaml` | `GO_IMAGE_*` keys
|
| `go/core/internal/controller/translator/agent/runtime_test.go`,
`imageconfig_test.go` | tests updated to tag-based expectations |

---------

Signed-off-by: QuentinBisson <[email protected]>
Co-authored-by: Eitan Yarmush <[email protected]>
Co-authored-by: Jet Chiang <[email protected]>
Co-authored-by: Peter Jausovec <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Pinned Agent images | Ignoring --image-registry / --image-repository in private-registry deployments

3 participants