feat: add gateway import command with executionRoleArn support#855
Open
jesseturner21 wants to merge 16 commits intoaws:mainfrom
Open
feat: add gateway import command with executionRoleArn support#855jesseturner21 wants to merge 16 commits intoaws:mainfrom
jesseturner21 wants to merge 16 commits intoaws:mainfrom
Conversation
Add `agentcore import gateway --arn <arn>` to import existing AWS gateways (with all targets) into a local CLI project. Also remove import from the HIDDEN_FROM_TUI list so it appears in the interactive TUI. - Add AWS SDK wrappers for gateway/target list/get APIs - Add import-gateway.ts with multi-resource CFN import support - Add resourceName schema field to preserve actual AWS gateway name during import - Register gateway in TUI ImportSelectScreen and ImportProgressScreen - Extend ARN pattern, deployed state, and CFN constants for gateway type
The ARN text input was truncating long ARNs. Use the expandable prop to wrap text across multiple lines. Also add gateway to the ARN validation pattern and resource type labels.
Remove --name (confusing local rename) and --yes (no prompts to confirm) from the gateway import command. The gateway's AWS name is used directly.
Add end-to-end tests that create a real AWS gateway with an MCP server target, import it via `agentcore import gateway --arn`, and verify the resulting agentcore.json fields and deployed-state.json entries. New files: - e2e-tests/fixtures/import/setup_gateway.py: creates gateway + target - e2e-tests/fixtures/import/common.py: gateway wait helpers - e2e-tests/fixtures/import/cleanup_resources.py: gateway cleanup Constraint: Tests follow the existing import-resources.test.ts pattern Confidence: high Scope-risk: narrow
Extract roleArn from the AWS GetGateway response and map it to executionRoleArn in agentcore.json. On deploy, CDK uses iam.Role.fromRoleArn() instead of creating a new role, keeping the original permissions intact. Constraint: imported roles use mutable: false so CDK cannot modify them Rejected: always create new role | breaks permissions on re-import Confidence: high Scope-risk: narrow
jesseturner21
had a problem deploying
to
e2e-testing
GitHub Actions
Failure
jesseturner21
temporarily deployed
to
e2e-testing
GitHub Actions
Inactive
Contributor
Package TarballHow to installnpm install https://github.com/aws/agentcore-cli/releases/download/pr-855-tarball/aws-agentcore-0.8.1.tgz |
jesseturner21
temporarily deployed
to
e2e-testing
GitHub Actions
Inactive
jesseturner21
temporarily deployed
to
e2e-testing
GitHub Actions
Inactive
Add @internal exports for toGatewayTargetSpec, resolveOutboundAuth, toGatewaySpec, and buildCredentialArnMap to enable direct unit testing of the pure mapping functions in import-gateway.ts. Confidence: high Scope-risk: narrow
…lution Bugbash coverage for toGatewayTargetSpec and resolveOutboundAuth: - mcpServer with no auth, OAuth, and API_KEY credentials - Credential resolution warnings when ARNs not in project - Targets with no MCP configuration - OAuth scopes pass-through and empty scopes omission 8 tests, all passing. Confidence: high Scope-risk: narrow
…da target mapping Bugbash coverage for toGatewayTargetSpec non-mcpServer target types: - apiGateway: restApiId, stage, toolFilters, toolOverrides mapping - openApiSchema: S3 URI mapping, missing URI warning - smithyModel: S3 URI mapping, missing URI warning - lambda: S3 tool schema to lambdaFunctionArn mapping, missing ARN, inline-only schema warning, progress messages - Unrecognized target type warning 13 tests, all passing. Confidence: high Scope-risk: narrow
Bugbash coverage for toGatewaySpec AWS-to-CLI schema mapping: - Authorizer types: NONE, AWS_IAM, CUSTOM_JWT with all JWT fields - CUSTOM_JWT customClaims with full claim structure - Semantic search: SEMANTIC/KEYWORD/missing protocolConfiguration - Exception level: DEBUG/undefined/other values - Policy engine: ARN name extraction, mode preservation - Optional fields: resourceName, description, tags, executionRoleArn - Edge cases: empty tags object omitted, empty JWT arrays omitted 23 tests, all passing. Confidence: high Scope-risk: narrow
Bugbash coverage for the main gateway import flow: - Happy path: successful import with --arn, config written, result verified - Rollback: pipeline failure restores original config, noResources error - Duplicate detection: name collision, resource ID already tracked - Name validation: invalid name regex, --name override preserves resourceName - Auto-select: single gateway auto-selected, multiple gateways error, no gateways error - Target mapping: skipped targets warning, non-READY gateway continues 12 tests, all passing. Confidence: high Scope-risk: narrow
Bugbash coverage for credential resolution and CFN resource matching: - buildCredentialArnMap: reads ARN-to-name map from deployed state, handles multiple credentials, empty/missing state, thrown errors - findLogicalIdByProperty: gateway by Name property, resourceName fallback, target by Name, Fn::Join/Fn::Sub intrinsic function patterns, regex boundary check prevents false substring matches - findLogicalIdsByType: single gateway fallback, single target fallback, multiple targets prevent fallback 14 tests, all passing. Confidence: high Scope-risk: narrow
…ce list When a project already contains an imported resource (gateway + target, agent, memory, etc.), a subsequent import of a different resource that shares a Name with the deployed one caused buildResourcesToImport to resolve the OLD logical ID via findLogicalIdByProperty. The resulting CFN change set then failed with "Resources [...] passed in ResourceToImport are already in a stack and cannot be imported." Thread the deployed template into every buildResourcesToImport callback and skip logical IDs already present in the stack during both the name lookup and the single-candidate fallback. Constraint: GatewayTarget has no structural parent ref in Properties — only the physical-ID tuple (GatewayIdentifier, TargetId), so scoping the synth search by parent gateway is not available. Rejected: Parse Fn::Ref/Fn::GetAtt from GatewayIdentifier | brittle intrinsic traversal Rejected: Match by physical TargetId | synth template has no physical ID for new resources Rejected: Strip deployed resources from synth before lookup | breaks buildImportTemplate Confidence: high Scope-risk: narrow Directive: new callbacks into executeCdkImportPipeline must accept and honor the deployedTemplate arg Not-tested: multi-region / cross-stack-identifier collisions
…ound error When importing a gateway by a well-formed but nonexistent ARN, the BedrockAgentCore control plane returns AccessDenied (not ResourceNotFound) for bedrock-agentcore:GetGateway. The CLI surfaced the raw SDK error — which is misleading when the caller has full Admin access and the gateway simply doesn't exist. Catch AccessDenied from getGatewayDetail and return a targeted failure with guidance: the gateway is likely nonexistent / the ARN is malformed / the caller lacks GetGateway. Point the user at list-gateways so they can confirm. Constraint: AWS returns AccessDenied instead of ResourceNotFound for nonexistent gateway IDs; we cannot distinguish the two server-side Rejected: Client-side ARN existence probe via ListGateways | extra latency on the happy path and still racy Confidence: high Scope-risk: narrow Directive: Do not swallow other error classes here — only AccessDenied is reinterpreted
Previously when a user ran import with AWS_REGION=us-west-2 against a us-east-1 ARN, and no deployment targets existed yet, the CLI silently synthesized a default target from the ARN's region and proceeded — so the user would unknowingly import from a different region than they intended, leaving agentcore.json pointed at the wrong region and causing cross-region CFN errors on later deploy. Short-circuit resolveImportTarget when AWS_REGION (or AWS_DEFAULT_REGION) is set and disagrees with the ARN's region, and ask the user to reconcile explicitly. Constraint: Must fail fast before any side effects (writing aws-targets.json, calling GetGateway) Rejected: Warn-and-continue | a silent cross-region import is exactly the failure mode we're preventing Confidence: high Scope-risk: narrow Directive: Only throw when both env region AND ARN region are present — do not require AWS_REGION to be set
jesseturner21
temporarily deployed
to
e2e-testing
GitHub Actions
Inactive
jesseturner21
temporarily deployed
to
e2e-testing
GitHub Actions
Inactive
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
agentcore import gateway --arn <gatewayArn>command that imports an existing AWS gateway with its targets into a local agentcore projectexecutionRoleArn, matching the pattern used by runtime and memory importsiam.Role.fromRoleArn()instead of creating a new role, keeping original permissions intactimportcommand from the TUI and add gateway ARN support to the ARN input componentChanges
Gateway Import Command
src/cli/commands/import/import-gateway.ts— new import command that fetches gateway details + targets from AWS, maps them to the local schema, writes agentcore.json and deployed-state.json, then runs CDK synth for CloudFormation importsrc/cli/aws/agentcore-control.ts— extractroleArnfrom GetGateway API responseexecutionRoleArn Support
src/schema/schemas/mcp.ts— add optionalexecutionRoleArnfield to gateway schemasrc/cli/commands/import/import-gateway.ts— map AWSroleArn→executionRoleArnduring importCDK Constructs (separate PR in agentcore-l3-cdk-constructs)
Gateway.ts— usefromRoleArnwhenexecutionRoleArnis set, addaddToPolicyguard methodAgentCoreMcp.ts— usegateway.addToPolicy()for policy engine grantsmcp.ts— addexecutionRoleArnto CDK schemaE2E Tests
e2e-tests/import-resources.test.ts— gateway import test, field verification (includingexecutionRoleArn), deployed-state verificatione2e-tests/fixtures/import/setup_gateway.py— creates gateway + MCP server target for testinge2e-tests/fixtures/import/common.py— gateway wait helpersTest plan
executionRoleArnmatches original role ARNagentcore.jsoncontains all gateway fields (name, resourceName, description, authorizerType, enableSemanticSearch, exceptionLevel, executionRoleArn, tags, targets)CDK_TARBALL=<path> npm run test:e2e