How do I troubleshoot AWS DevOps Agent topology that's empty or missing resources?

Resolution

Confirm if your DevOps Agent topology is in the empty, stuck, or stale state, then troubleshoot your issue based on your findings.

To check the state of your topology, complete the following steps:

1. Open the AWS DevOps Agent console.
2. Select your Agent Space.
3. Open the DevOps Agent web app.
4. Choose the Topology page to review your AWS DevOps Agent topology.

Troubleshoot topology that's empty after you create your Agent Space

After you create an Agent Space for AWS DevOps Agent, your topology might appear empty for several minutes. For accounts with a large number of resources, this process takes longer.

If the Topology page shows that AWS DevOps Agent is learning resources, then wait and refresh the page.

If the topology stays empty after discovery completes, then continue with the following sections.

Troubleshoot topology that's stuck on Analyzing your topology or Mapping entities

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Blocked foundational discovery components cause your topology to stay in Analyzing your topology or Mapping entities: Analyzing resources and their relationships status for over an hour. Blocked foundational discovery components also cause the Topology page to show zero resources or zero relationships for over an hour.

To unblock your foundational discovery component, check that your tag filters match your resources. Then, confirm that your Agent Space role has the necessary AWS Identity and Access Management (IAM) permissions.

Tag filters don't match your resources

If you set up tag filters when you create your Agent Space, then AWS DevOps Agent uses those tags to filter discovered resources. If the filter tag keys or values don't match any deployed resources, then discovery stalls.

To remove or update the tag filters, complete the following steps:

1. Open the AWS DevOps Agent console.
2. Select your Agent Space.
3. Choose the Capabilities tab.
4. In the Cloud section, choose Edit on your AWS account association.
5. Under Include AWS tags, remove or correct the tag filters.
6. Save the changes.

After you remove the filters, AWS DevOps Agent discovers the resources that the Agent Space role has permission to read.

The Agent Space role lacks necessary IAM permissions

The Agent Space role must have the AIDevOpsAgentAccessPolicy AWS Managed Policy attached. Without it, the agent can't list AWS CloudFormation stacks or query AWS Resource Explorer.

To verify the role has the managed policy attached, run the following list-attached-role-policies AWS CLI command:

aws iam list-attached-role-policies --role-name agent-space-role

Note: Replace agent-space-role with the name of your Agent Space role.

If the policy is missing, then attach it with the following attach-role-policy AWS CLI command:

aws iam attach-role-policy --role-name agent-space-role --policy-arn arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy

Note: Replace agent-space-role with the name of your Agent Space role.

Troubleshoot a Topology page that displays only resources that you deploy through CloudFormation

AWS DevOps Agent uses Resource Explorer for resources that you don't deploy through CloudFormation. If you don't activate Resource Explorer in the same AWS Region as your Agent Space, then discovery stalls when the agent queries it. If you don't activate Resource Explorer, then only CloudFormation stack resources appear on the Topology page.

Important: You must activate Resource Explorer with an aggregator index in the same as your Agent Space.

To verify you configured Resource Explorer, run the following list-indexes AWS CLI command:

aws resource-explorer-2 list-indexes --region your-region

Note: Replace your-region with the Region where you created your Agent Space.

If the output of the command is empty, then complete the following steps to activate Resource Explorer:

1. Open the Resource Explorer console.
2. Choose Quick setup.
3. Choose the Region for your aggregator index.
4. Wait for the index status to change to Active.

When Resource Explorer finishes indexing, AWS DevOps Agent includes the indexed resources during the next topology refresh.

Note: For accounts with a large number of resources, indexing takes up to 36 hours.

Troubleshoot a recently added resource type that isn't visible

The Agent Space role must have the AIDevOpsAgentAccessPolicy managed policy attached.

If you use a custom policy instead of the managed policy, then confirm that your custom policy includes all the permissions in the AIDevOpsAgentAccessPolicy.

Note: AWS updates the managed policy when DevOps Agent Topology adds new resource types, so review your custom policy periodically to keep it current.

If the Agent Space details page shows a Capability gap identified banner, then the agent didn't call AWS API operations in your account. To resolve the banner, check that you attached the correct trust policy and managed policy to the Agent Space role.

Troubleshoot topology that's stale after an infrastructure change

AWS DevOps Agent refreshes the topology on a service-managed schedule. New, modified, or deleted resources don't appear immediately. To regenerate the topology, complete the following steps:

1. Open the DevOps Agent web app for your Agent Space.
2. Choose the Topology page.
3. Choose Regenerate topology.

The DevOps Agent web app rebuilds the topology graph from the latest CloudFormation stack data and Resource Explorer index. Regeneration typically completes within a few minutes.

If regeneration stops responding, then run the following list-backlog-tasks AWS CLI command:

aws devops-agent list-backlog-tasks --agent-space-id your-agent-space-id

Note: Replace your-agent-space-id with the Universally Unique Identifier (UUID) of your Agent Space.

In the output, note your task ID.

Then, run the following list-executions AWS CLI command to check the status of your regeneration:

aws devops-agent list-executions --agent-space-id your-agent-space-id --task-id your-task-id

Note: Replace your-agent-space-id with the UUID of your Agent Space and your-task-id with the task ID from the first command.

If the list-backlog-tasks command's status remains IN_PROGRESS for a long period, then contact AWS Support with the task ID and execution ID.

Troubleshoot resources in another AWS account that aren't visible

If your application spans multiple AWS accounts, then add each additional account as a secondary account.

To add a secondary account, complete the following steps:

1. Open the DevOps Agent console.
2. Select your Agent Space.
3. Choose the Capabilities tab.
4. In the Cloud section, choose Secondary sources, and then choose Add.
5. Choose AWS as the account source, then choose Add.
6. Follow the console wizard to configure the IAM role in the secondary account.
   Note: The console provides the role name, trust policy, and inline policy.

For more information, see Connecting multiple AWS Accounts.

In the console, the secondary account role sometimes validates resources with check marks when the managed policy is missing or incomplete. If the agent can't list CloudFormation stacks or query Resource Explorer in the secondary account, then re-attach AIDevOpsAgentAccessPolicy to the secondary account role.

Related information

Configuring capabilities for AWS DevOps Agent

Limiting Agent Access in an AWS Account

Learned Skills