Skip to content

feat: AgentCore Instances compute type (x86_64) for managed environments - #468

Open
matheus-1618 wants to merge 14 commits into
aws-samples:mainfrom
matheus-1618:feat/agentcore-instances
Open

matheus-1618 wants to merge 14 commits into
aws-samples:mainfrom
matheus-1618:feat/agentcore-instances

Conversation

@matheus-1618

@matheus-1618 matheus-1618 commented Sep 15, 2026

Copy link
Copy Markdown

What

Adds opt-in support for the AgentCore Instances compute type to managed environments, including x86_64 environments — the first non-arm64 path in the platform.

Admins creating a managed environment can now choose its compute:

  • Serverless microVMs (arm64) — the existing default, unchanged
  • EC2 Instances (x86_64) — runs the environment's runtime on EC2 managed instances in the deployment account, provisioned through an AgentCore capacity provider

Everything is gated behind a new terraform variable enable_instances_compute (default false). Deployments that don't opt in are unaffected — with the flag off there is no amd64 image build, no operator role, and the compute selector rejects instances.

Why

  • x86_64 workloads: microVMs are arm64-only; teams that need to build/run x86 artifacts had no path.
  • Persistent workspace: the capacity provider's EBS volume replaces managed session storage at /mnt/workspace, lifting the fixed 1 GB session-storage ceiling and surviving session stops.
  • Account-level controls: instances run in the deployment account (Savings Plans/ODCRs apply, data stays in-account), with sessions of up to 14 days.

How

  • compute: { type, architecture } field on the environment (API + UI selector on the create flow; immutable after creation, matching the AgentCore contract).
  • Capacity provider per architecture, created lazily by the status lambda with a deterministic name on first use. Capacity providers are immutable (duplicate-to-change), so they are treated as create-once resources rather than terraform state.
  • Runtime creation branches on the compute type: capacityProviderConfiguration + capacityProviderVolume (no networkConfiguration — Instances inherits the capacity provider's VPC).
  • One CodeBuild project serves both architectures via per-build overrides (environmentTypeOverride/imageOverride + an IMAGE_PLATFORM variable in the buildspec).
  • x86_64 environments build FROM an amd64 variant of the core image (opt-in terraform build). Catalog tools remain arm64-only for now and are rejected on x86_64 with a clear error.
  • The core image Dockerfile is now architecture-aware: the base image is pinned to the multi-arch index digest (the previous pin referenced the arm64 manifest, which silently ignores --platform), and Kiro/OpenCode/bun/uv select artifact + pinned sha256 by TARGETARCH. arm64 builds resolve to the exact same artifacts as before.

Fixes picked up along the way (apply to microVMs deployments too)

  • inspector2:ListCoverage/ListFindings for the status lambda — in accounts with ECR enhanced scanning, DescribeImageScanFindings is served by Amazon Inspector and every image scan fails without these.
  • iam:CreateServiceLinkedRole (scoped) — the first capacity provider in an account provisions the AWSServiceRoleForBedrockAgentCoreRuntimeInstances SLR.
  • bedrock-agentcore:PassCapacityProvider — required by CreateAgentRuntime when associating a capacity provider.
  • Transient first-invoke errors (instance provisioning) are retried instead of permanently failing the revision.
  • Block-device workspace mounts come formatted — mkfs.ext4 leaves lost+found at the volume root and git clone refuses the non-empty destination. The workspace init now clears the well-known filesystem entries before cloning (any other residue still fails loudly).

Notes and limitations

  • Burstable instance types (t family) are rejected by CreateCapacityProvider (Instance type 't3.large' is not supported); the default allowlist uses m6i.large. m5/m6i/c5/c6i were verified to be accepted.
  • x86_64 environments must derive from the Standard environment (the base swap targets the amd64 core); tool-catalog x86 binaries are a natural follow-up.
  • The environment verification guardrail now asserts the architecture from the recipe instead of hardcoding arm64.

Validation

End-to-end on a fresh us-east-1 deployment with enable_instances_compute = true:

  1. Environment created via the UI selector with compute: { type: instances, architecture: x86_64 }.
  2. CodeBuild ran on the x86 fleet with --platform linux/amd64, image built FROM the amd64 core and passed the (now architecture-aware) verification script.
  3. Capacity provider created lazily (READY), runtime created with capacityProviderConfiguration and the workspace EBS volume at /mnt/workspace.
  4. Runtime validation invoked the runtime — an m6i instance was provisioned by AgentCore and the container reported arch=x86_64, non-root, writable workspace, all four agent CLIs installed.
  5. Revision published; three further revisions repeated the pipeline cleanly with no intervention.
  6. A real intent ran end-to-end on the Instances runtime: workspace cloned onto the EBS volume, and the agent CLI (Claude Code via Bedrock) executed stages on the EC2 managed instance.
  7. linux/amd64 and linux/arm64 builds of the core image verified locally (all six CLI binaries at their pinned versions on both).

Tests: 122 backend (18 new covering the compute module and the Instances runtime path) and 569 frontend, all passing; terraform validate clean.

Managed environments can now target the AgentCore Instances compute type
(compute: { type: 'instances', architecture: 'x86_64' | 'arm64' }):

- capacity provider per architecture, created lazily by the status
  lambda with a deterministic name (immutable resource, create-once)
- runtime created with capacityProviderConfiguration; networking is
  inherited from the capacity provider and the workspace moves from
  managed session storage to a persistent EBS volume at /mnt/workspace
- x86_64 environments build FROM an amd64 variant of the core image
  (opt-in terraform build) on an x86 CodeBuild fleet via per-build
  overrides; catalog tools stay arm64-only for now
- everything is gated behind enable_instances_compute (default false)
The previous pin referenced the arm64-specific manifest, which silently
ignores --platform and blocks amd64 builds of the core image. The index
digest resolves to the exact same arm64 manifest on arm builds (no-op)
and selects the amd64 manifest when building for x86_64.
Kiro, OpenCode, bun and uv were pinned to arm64 artifacts, which made
--platform linux/amd64 builds impossible. Each download now selects the
artifact and its pinned sha256 by TARGETARCH; arm64 builds keep the
exact same artifacts as before.
Admins choose between serverless microVMs (default, arm64) and EC2
Instances (x86_64) when creating a managed environment. The choice is
immutable after creation, matching the AgentCore contract, so the
selector only renders on the create flow.
The verification prologue hardcoded the arm64 assertion, rejecting
correctly-built x86_64 images. The expected architecture now follows
the recipe (docker inspect reports x86_64 as amd64).
…counts

In accounts where ECR enhanced scanning is enabled, DescribeImageScanFindings
is backed by Amazon Inspector and the status lambda also needs
inspector2:ListCoverage/ListFindings, otherwise every image scan fails with
an authorization error.
The first CreateCapacityProvider in an account provisions the
AWSServiceRoleForBedrockAgentCoreRuntimeInstances service-linked role on
behalf of the caller, which requires iam:CreateServiceLinkedRole scoped to
that service.
CreateAgentRuntime with a capacityProviderConfiguration authorizes the
association through PassCapacityProvider on the capacity provider ARN.
…device workspace

EBS-backed workspace mounts (Instances compute type) come formatted, so
/mnt/workspace contains lost+found and git clone refuses the non-empty
destination. Remove only the well-known mkfs entries when no checkout
exists; any other residue still fails loudly.
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.

1 participant