Repository navigation
feat(deploy): pin Box runtimes to AgentCore Runtime V2 - #2879
mquang-amazon wants to merge 2 commits into
Conversation
Box runs only on AgentCore Runtime V2, and without platformVersion the service picks the platform, which can be V1. - A runtime can set "platformVersion": "V1" or "V2". create with a box template and add runtime in a Box project write "V2". - build and deploy refuse a runtime of a Box project whose platformVersion is not "V2", before the runtime sync rewrites agentcore.json. - deploy refuses a stack in which a V2 runtime's AWS::BedrockAgentCore::Runtime does not set PlatformVersion, which is what a @aws/agentcore-cdk from before platformVersion synthesizes.
leo237
left a comment
There was a problem hiding this comment.
Thanks @mquang-amazon. First pass from us. I read the diff against box-integration at 2379919, the L3 side (aws/agentcore-l3-cdk-constructs#474 and the v1.1.0 tag the CLI pins), and CI. All CI checks pass, and the branch is up to date with box-integration.
Verdict: COMMENT. The code looks correct to me. It is not merge-ready, because of the dependency the description already names.
Blocking for merge
- Unmet hard dependency. aws/agentcore-l3-cdk-constructs#474 is still open (not merged, not released), and
src/assets/cdk/package.jsonin this PR still pins@aws/agentcore-cdkto1.1.0. I checkedv1.1.0:AgentEnvSpecSchemathere is a plainz.object, so it strips the unknownplatformVersionand synth still succeeds. NoConfigValidationErrorlike theenableApplicationLogscase. But noPlatformVersiongets written either, soassertPlatformVersionswill refuse every Box deploy, andcreate/add runtimenow write the field into every new Box project. This PR is not a draft, so nothing stops a merge. Before this can merge, these need to land, in this order: (a) #474 merged into L3box-integration, (b) an@aws/agentcore-cdkrelease that includes it, (c) the pin bump insrc/assets/cdk/package.json, in this PR or one that merges first. Until then, please convert this PR to draft (or add a do-not-merge label) so the gate is enforced and not only described. Once those land I expect to approve. I have no blocking issue with the code itself.
Non-blocking
- Public description. This repo is public. Please remove the reference to the internal plan and tracking document from the "Related Issue" section of the description. "No GitHub issue" is enough. The diff and commit message are clean, I found no internal names or URLs in either.
- Fail-closed behavior, checked. A missing or renamed
RuntimeIdexport, a missing resource, and a non-literalPlatformVersion(Fn::If,Ref) all failPlatformVersionPropertiesSchema/ the equality check and refuse the deploy. Good. The export-name sanitizer matches L3'sexportName()inlogical-ids.ts, andRuntimeEnvironment.createOutputsexportsruntime.runtimeId, so the lookup is sound. Inline notes below cover the error text in the missing-export case and which runtimes get checked. - Tests. Small gaps, inline: no schema test (
V1/V2accepted,"v2"/other strings rejected) insrc/projectSchemas/runtime.test.ts. The build refusal covers onlyV1, not a missing field. No multi-runtime case forassertPlatformVersions(one good and one bad runtime, error names only the bad one). No test for a project that is not a Box project but sets"platformVersion": "V2". That project is checked post-synth, and I think that is right, but a test would lock it in. - #2878 interaction. Both PRs add Box/V2 gates at the same point in
deploy. When you rebase whichever merges second, consider one helper (for example spec check + region check) so the order is explicit. I suggest the region check first, since it does not depend on the user editingagentcore.json. - Migration UX. For existing Box projects, the
build/deploymessage is clear and actionable. An auto-fix (write"V2"during sync for a Box project with no field, with a step message) would be friendlier, but refusing is a reasonable choice. Your call. - Docs. README documents
containmentbut notplatformVersion. Worth a line once the L3 release is out. - Branch sync. This change is not on
box-integration-development, and it is not in the squash plan's PR list, so it needs a back-merge there after it lands.
Must-survive fixes (runsInBox/assertBoxRuntimesHaveBoxVersion, assertPrivateVpcs, containment, Box gateway logs notice) are untouched. The diff only adds code. The new tests use tmpdir()/join, spawn nothing and make no AWS calls.
| throw new ProjectStateError( | ||
| `Runtime ${missing.map((name) => `'${name}'`).join(", ")} has "platformVersion": ` + | ||
| `"${platformVersion}", but the synthesized stack does not set it. The @aws/agentcore-cdk ` + | ||
| "in agentcore/cdk is older than platformVersion: update it, then deploy again.", |
There was a problem hiding this comment.
Two nits on this message:
- With this PR merged before an L3 release that has
platformVersion, "update it" can't succeed: no newer@aws/agentcore-cdkexists yet. That is one more reason to gate the merge on the release and pin bump (see summary). After that, maybe name the minimum version, like "update it to >= X.Y.Z". - The same text is used when the
<stack>-<runtime>-RuntimeIdexport is not found (the last test case). In that case the cause may be an export rename and not an old library, so "the synthesized stack does not set it" / "older than platformVersion" could mislead. Consider a separate message for the no-export case, like "could not find runtime 'x' in the synthesized stack". It still fails closed, which is the right behavior.
There was a problem hiding this comment.
Done in 42599ee for the no-export case: it now says "Could not find runtime 'x' in the synthesized stack '', so deploy cannot check that it runs on ..." (still fail closed). For the old-library case I kept the message generic ("update it to a release that has platformVersion"), since there is no L3 release with the field to name yet; I will name the minimum version in the pin bump.
| assemblyDirectory, | ||
| artifact, | ||
| project.spec.runtimes | ||
| .filter((runtime) => runtime.platformVersion === BOX_PLATFORM_VERSION) |
There was a problem hiding this comment.
Only runtimes with platformVersion === "V2" are verified post-synth. Two notes:
- A project that is not a Box project but sets
"V2"explicitly is checked too. I think that is the right fail-closed behavior. Worth one test so nobody narrows it toisBoxProjectlater. - A runtime with an explicit
"V1"is not verified, so an old library drops it silently and the service picks. Since the schema acceptsV1, consider checking every runtime with aplatformVersionagainst its own value (for example, pass{name, platformVersion}pairs). ThenassertPlatformVersionscovers what its generic name and signature suggest. Non-blocking.
There was a problem hiding this comment.
Done in 42599ee: runtimePlatformVersions picks every runtime that names a platformVersion, in a Box project or not, V1 included, and assertPlatformVersions checks each against its own value. Tests cover the selection (a non-Box V2 and a V1 are picked), V1 and V2 matches, and a two-runtime stack where only the bad runtime is named.
| /** | ||
| * Throws for a runtime of a Box project whose `platformVersion` is not `"V2"`. Box runs only on | ||
| * AgentCore Runtime V2, and without the field the service picks the platform, which can be V1. | ||
| * `agentcore create` and `add runtime` write it. Build and deploy call this before they write |
There was a problem hiding this comment.
Nit: "before they write anything" is not quite true for deploy. provisionDefaultTarget can write aws-targets.json before this call. Maybe "before the runtime sync rewrites agentcore.json", which matches the call-site comments.
There was a problem hiding this comment.
Done in 42599ee: "Build and deploy call this before the runtime sync rewrites agentcore.json."
| /** Only with `"containment": "PRIVATE_VPC"`. */ | ||
| network: ContainedNetworkSchema.optional(), | ||
| /** No default. Every runtime of a Box project needs `"V2"`; create writes it. */ | ||
| platformVersion: PlatformVersionSchema.optional(), |
There was a problem hiding this comment.
Could you add a couple of cases to src/projectSchemas/runtime.test.ts: "V1"/"V2"/missing accepted, "v2" and "V3" rejected? It is a cheap guard on the casing users are most likely to get wrong.
There was a problem hiding this comment.
Done in 42599ee: runtime.test.ts accepts V1, V2 and a missing field, and refuses v2, V3 and an empty string.
| expect(existsSync(join(aws, "resources", "shared"))).toBe(false); | ||
| }); | ||
|
|
||
| test("refuses a Box runtime that is not on AgentCore Runtime V2, before anything is written", async () => { |
There was a problem hiding this comment.
The deploy tests cover both missing and V1, but build covers only V1. A test.each here over missing/V1, like the deploy test, would cover the more common migration case (an existing Box project with no field).
There was a problem hiding this comment.
Done in 42599ee: the build refusal is a test.each over a missing platformVersion and V1.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## box-integration #2879 +/- ##
================================================
Coverage 96.79% 96.80%
================================================
Files 766 766
Lines 66803 66879 +76
================================================
+ Hits 64665 64741 +76
Misses 2138 2138 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
- Check every runtime that names a platformVersion after synth, V1 included and not only in a Box project (runtimePlatformVersions), each against its own value. - A runtime the stack exports no RuntimeId for gets its own message, since the cause may be a renamed export, not an old CDK library. - Test the schema's accepted and refused values, and the build refusal for a Box runtime with no platformVersion as well as V1. - The validation comment says the check runs before the runtime sync rewrites agentcore.json.
leo237
left a comment
There was a problem hiding this comment.
Re-review at 42599ee. Thanks for the follow-up commit: the post-synth check now covers every runtime that names a platformVersion (V1 included, Box or not), a missing RuntimeId export gets its own message, the schema tests cover "v2"/"V3"/"", the build refuses a Box runtime with no field, and there's a multi-runtime test. The JSDoc wording is fixed too.
Still blocking: the aws/agentcore-l3-cdk-constructs#474 dependency. #474 is still open. No released @aws/agentcore-cdk writes PlatformVersion: the branch pins 1.1.0, and base's 1.2.0 doesn't write it either (I checked the published 1.2.0 tarball). The new commit doesn't add a capability check, version gate, or warn-instead-of-refuse fallback. So if this merges now, every Box deploy fails after synth, and create/add write a field that every deploy then rejects. This now also affects any non-Box project that sets platformVersion. The body says "Do not merge before that", but the PR isn't a draft and has no label, so nothing stops a merge. Please mark it draft (or add a do-not-merge label) until #474 is released and the pin is bumped, or degrade safely when the installed library can't write the field.
Non-blocking, still open:
- The "Related Issue" section still names an internal plan. Please replace it with a generic note. (The commit messages are clean.)
- The "update it to a release that has platformVersion" message points at a release that doesn't exist yet (inline).
- README/docs don't mention
platformVersion. - The branch is behind
box-integration(pin 1.1.0 vs 1.2.0). It merges cleanly, but please back-merge. - FYI: a trial merge with #2878's head conflicts in
boxValidation.ts,manager.tsx, andmanager.test.ts. The suggestion to combine the two gates (region check first) still stands.
CI: Analyze, Windows, and CodeBuild e2e pass. Linux and macOS were still pending when I posted.
| if (synthesized?.PlatformVersion === platformVersion) return []; | ||
| return [ | ||
| `Runtime '${name}' has "platformVersion": "${platformVersion}", but the synthesized stack ` + | ||
| "does not set it. The @aws/agentcore-cdk in agentcore/cdk is older than platformVersion: " + |
There was a problem hiding this comment.
No @aws/agentcore-cdk release has platformVersion yet (1.2.0 is the latest, and it doesn't). Until one does, this tells users to do something they can't. Consider naming the minimum version once it ships, or saying the support isn't released yet.
Description
Box runs only on AgentCore Runtime V2. Without
platformVersiononCreateAgentRuntime, the service picks theplatform, and its V2 default reaches only the accounts its rollout selects, so a Box runtime can land on V1. This PR
pins every runtime of a Box project to V2.
Schema: a runtime can set
"platformVersion": "V1"or"V2"(src/projectSchemas/runtime.ts). No default, soprojects that are not Box projects are unchanged.
create / add runtime:
agentcore createwith a box template, andadd runtimein a Box project, write"platformVersion": "V2"on the runtime.build and deploy refuse a runtime of a Box project whose
platformVersionis not"V2", before the runtimesync rewrites
agentcore.json:deploy, after synth: refuses a stack in which a V2 runtime's
AWS::BedrockAgentCore::Runtimedoes not setPlatformVersion: "V2". A@aws/agentcore-cdkfrom beforeplatformVersiondrops the field without an error, asassertPrivateVpcsguards for containment. The runtime's resource is found through the<stack>-<runtime>-RuntimeIdexport the CDK library writes.Existing Box projects need
"platformVersion": "V2"added to each runtime; build and deploy say so.Depends on
PlatformVersionfrom the runtime'splatformVersion. Until it isreleased and the
@aws/agentcore-cdkpin insrc/assets/cdk/package.jsonis bumped, the post-synth check refusesevery Box deploy, because the pinned library writes no
PlatformVersion. Do not merge before that.deployinmanager.tsxas feat(deploy): refuse Box projects in regions without AgentCore Runtime V2 #2878 (refuse Box projects in regions without Runtime V2), sowhichever merges second has a small conflict.
Related Issue
No GitHub issue. Tracked in the Beatbox plan ("Bugs, Findings, AIs", "support Box on Runtime V2 in V2 supported regions
alone").
Documentation PR
Not applicable.
Type of Change
Testing
How have you tested the change?
bun test: the changed test files pass (manager.test.ts,manager.box.test.ts,assembly.test.ts,269 tests). The full run has 31 failures that also fail without this change; my local
node_moduleshas@aws-sdk/client-bedrock-agentcore3.1153.0 instead of^3.1171.0, and one test needsboxon PATH.bun run test:e2e, or explained why they are not applicable(CI does not run them for you): not run; a Box deploy needs the L3 release first.
bun run typecheck: no errors in the changed files; the 53 it reports also occur without this change(same stale SDK).
bun run lint:checkbun run format:check(on the changed files)bun run auditbun run secrets:checkbun run buildsrc/assets/, I updated affected snapshots withbun test <test-file> --update-snapshotsand committed themby this PR
command.md(the release workflow regenerates it)Tests added: create writes
V2only for box templates; add runtime writesV2; build and deploy refuse a missingfield and
V1and leaveagentcore.jsonunchanged; a project that is not a Box project deploys without the field;assertPlatformVersionsacceptsV2and refuses a missing value,V1, and a runtime with noRuntimeIdexport. Theexport name and
Fn::GetAttshape were checked against a stack synthesized by the L3 branch.Checklist
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.