aws / aws/bedrock-agentcore-starter-toolkit

[BUG] agentcore destroy deletes externally-created IAM roles, contradicting documentation

Open
#438 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Python
Stars
508
Forks
155
Avg merge
8h 50m
Merged PRs (30d)
4

Description

## Describe the bug

`agentcore destroy` deletes IAM execution roles unconditionally, even when:

1. The role was created externally (via CloudFormation, Terraform, etc.) and only referenced during `agentcore configure`
2. The role was created by the CLI for one agent but subsequently reused for another agent

This contradicts the documented behavior which states the IAM execution role is only deleted "if not used by other agents."

The CLI calls `DeleteRole` on whatever role is in the config without checking whether other agents depend on it.

## To Reproduce

**Scenario A: Externally-created role**
1. Create an IAM role via CloudFormation (or any method outside the CLI)
2. Run `agentcore configure` and specify that role ARN when prompted
3. Run `agentcore deploy`
4. Run `agentcore destroy`
5. Observe: The externally-created IAM role is deleted

**Scenario B: CLI-created role reused across agents**
1. Run `agentcore configure` for Agent A, letting the CLI create a role
2. Run `agentcore deploy` for Agent A
3. Run `agentcore configure` for Agent B, specifying Agent A's role ARN
4. Run `agentcore deploy` for Agent B
5. Run `agentcore destroy` for Agent A
6. Observe: The shared role is deleted, breaking Agent B

## Expected behavior

Per the [CLI documentation](https://aws.github.io/bedrock-agentcore-starter-toolkit/api-reference/cli.html#destroy) and `agentcore destroy --help`, the IAM execution role should only be deleted "if not used by other agents."

## Error Output

No error is shown - the role is silently deleted. The destroy command shows the IAM role in its confirmation prompt but does not distinguish between deletable and in-use roles.

## Environment

- OS: any
- Python version: any
- Package version: Latest (pulled 2026-01-28)
- Installation method: any

## Workaround

None, except avoiding to use `agentcore destroy` altogether and cleaning up resources manually.

## Additional context

IAM resources being deleted without user knowledge or consent constitues a **high severity security risk**.

## Suggested fix

Track role provenance in `.bedrock_agentcore.yaml`. On `agentcore destroy`:

- If the role was provided by the user (not CLI-created): skip deletion, inform user
- If the role was CLI-created: check if any other agent configs reference it; only delete if no dependencies exist

Contributor guide

Open the contributing guide

Research direction

Start by tracing the `agentcore destroy` command and how `.bedrock_agentcore.yaml` records roles created during `configure`; compare this with the documented destroy behavior and `agentcore destroy --help`. Verify both externally provided roles and roles shared by multiple agents, then confirm that destroy skips protected roles, reports the reason, and deletes CLI-created roles only when no agent depends on them.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, python
Domain
cli, cloud, security
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.