aws / aws/bedrock-agentcore-starter-toolkit
[BUG] agentcore destroy deletes externally-created IAM roles, contradicting documentation
- 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
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