# microVM Runtime V1 → V2 canary checklist

Run against **one non-production agent runtime** first. Assumes the agent already deploys on AgentCore **microVM** Runtime (not Runtime Instances / capacity providers).

Source announcement: [The new AgentCore Runtime — Sep 18, 2026](https://aws.amazon.com/about-aws/whats-new/2026/09/new-agentcore-runtime-generally-available/).
Platform versions: [Runtime how-it-works](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html).
Snapshot rules: [Optimize for Runtime V2](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-v2-optimize.html).

## Pre-flight (45 minutes)

- [ ] Confirm Region is in the V2 list: `us-east-1`, `us-east-2`, `us-west-2`, `eu-west-1`, `ap-northeast-1`.
- [ ] Score the [decision matrix](./v1-vs-v2-decision-matrix.md) — proceed only if sum ≥ 14 **or** you have a hard cold-start problem (multi-GB image / concurrency tail).
- [ ] Fill the [cost worksheet](./v1-peak-vs-v2-elastic-cost-worksheet.csv). If median session < 120s **and** starts are already fast, **do not canary** — V2 will not reclaim memory and list rates are higher.
- [ ] Measure env-var payload size (V2: 1.5 KB direct code, 2.5 KB container; V1: 4 KB). Over the cap → `ValidationException`.
- [ ] Review startup vs handler split: no short-lived credentials, Gateway tool catalogs, `random` seeds, or hostname/PID worker IDs at import time.
- [ ] BYO container crypto: Amazon Linux 2023 `openssl-snapsafe-libs` (direct-code base image is already snapsafe).
- [ ] Write rollback criteria: e.g. $/successful session > 1.2× V1 control, or P75 start not improved, or create/update stuck `FAILED` on health check.
- [ ] Tag plan: `MigrationWave=agentcore-runtime-v2-canary` for Cost Explorer.

## Canary setup (same day)

- [ ] Keep a V1 control runtime (or a custom endpoint pinned to the current version) so you can compare.
- [ ] Set `platformVersion` to `V2` on **create** or **update** via Console, CLI, or SDK. Omit on create → V1. Omit on update → keeps current. CloudFormation and CDK cannot set `platformVersion` yet.
- [ ] Poll `get-agent-runtime` until `READY` or `*FAILED`. V2 snapshot prep takes **minutes**, not seconds. Calling update/delete while `CREATING`/`UPDATING` returns `ConflictException`.
- [ ] Confirm `--query platformVersion` returns `V2`.
- [ ] Confirm `/ping` is healthy only after init; first healthy ping is when the snapshot is taken. Init must finish within **120 seconds** or create fails.
- [ ] Run representative sessions for ≥ **72 hours** (include overnight idle and at least one deploy that rebuilds the snapshot).

CLI shape (replace names, role, and image; AWS CLI `bedrock-agentcore-control`):

```bash
aws bedrock-agentcore-control create-agent-runtime \
  --agent-runtime-name "canary-v2" \
  --role-arn "arn:aws:iam::111122223333:role/AgentExecutionRole" \
  --agent-runtime-artifact '{"containerConfiguration":{"containerUri":"111122223333.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest"}}' \
  --network-configuration '{"networkMode":"PUBLIC"}' \
  --platform-version V2
```

## Compare (end of canary)

- [ ] P75 / P95 session start vs V1 control (AWS published V2 P75 **1.9–2.0s** for 200 MB–2 GB images vs V1 **5.4–30s** — your numbers will differ).
- [ ] Session success rate, tool errors, auth failures (expired STS from snapshot-frozen creds is the tell).
- [ ] Cost Explorer: Runtime vCPU-hour and GB-hour for canary vs control, same traffic shape, normalized to **$/successful session**.
- [ ] Confirm unused memory actually dropped after 120s idle (if your sessions never idle that long, the memory line will not improve).

## Rollback triggers (stop canary if any fire)

- [ ] Create/update fails health check (init > 120s).
- [ ] Duplicate request IDs, identical `random` sequences, or expired credentials across restored instances.
- [ ] Env-var `ValidationException` after a config add.
- [ ] $/successful session worse than V1 with no start-time win.
- [ ] Region not in the V2 list (silent V1 if you omitted the field on create).

## Promote or park

- [ ] If canary wins on P75 start **or** $/session: promote other large-image / long-idle runtimes the same way, one at a time.
- [ ] Keep V1 for bursty sub-120s chat agents — mixed platform versions across runtimes are expected.
- [ ] Do not assume committed-baseline discounts (`$0.0997` / `$0.0132`) until AWS marks them launched (pricing page: by October 2026).
- [ ] Update the architecture decision record with the scored matrix, worksheet, and CE screenshots.