Support
Documentation

AWS Integration

Connect your AWS account to give DevGrid read-only access to your infrastructure. DevGrid uses a cross-account IAM role — no credentials are stored, and no resources are ever modified.

Setup

Step 1 — Open the AWS integration

Go to Settings → Integrations, click Add integration, then click Install on the AWS tile. The setup modal will open showing your External ID and a pre-generated CloudFormation template.

Step 2 — Deploy the IAM role

Copy the CloudFormation template from the modal and deploy it in your AWS account:

  1. Go to AWS Console → CloudFormation → Create Stack
  2. Choose Upload a template file and paste or upload the copied template
  3. Click through the defaults and deploy the stack (takes about 1 minute)
  4. Once complete, open the stack and go to the Outputs tab
  5. Copy the RoleARN value

The template creates a single read-only IAM role (DevGridReadOnlyRole).

AWS Organizations: A management-account role can list member accounts; it cannot inventory resources inside those accounts. Deploy the same template into each member account with a CloudFormation StackSet from the management account (target the OUs you want scanned). Keep the role name DevGridReadOnlyRole and use the External ID from the DevGrid modal. Then connect the management account Role ARN in Step 3. DevGrid discovers ACTIVE member accounts from Organizations and assumes arn:aws:iam::<member-account-id>:role/DevGridReadOnlyRole in each.

AWSTemplateFormatVersion: '2010-09-09'
Description: DevGrid AWS Integration - Read-Only IAM Role

Resources:
  DevGridReadOnlyRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevGridReadOnlyRole
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              AWS: 'arn:aws:iam::487920486018:root'
            Action: 'sts:AssumeRole'
            Condition:
              StringEquals:
                'sts:ExternalId': '<YOUR_EXTERNAL_ID>'
      MaxSessionDuration: 3600
      Policies:
        - PolicyName: DevGridResourceInventory
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - ec2:DescribeInstances
                  - ec2:DescribeVolumes
                  - ec2:DescribeRegions
                  - ecs:ListClusters
                  - ecs:DescribeClusters
                  - ecs:ListServices
                  - ecs:DescribeServices
                  - ecs:ListTasks
                  - ecs:DescribeTasks
                  - ecs:ListTaskDefinitions
                  - ecs:DescribeTaskDefinition
                  - ecs:ListContainerInstances
                  - ecs:DescribeContainerInstances
                  - eks:ListClusters
                  - eks:DescribeCluster
                  - eks:ListNodegroups
                  - eks:DescribeNodegroup
                  - eks:ListFargateProfiles
                  - eks:DescribeFargateProfile
                  - lambda:ListFunctions
                  - lambda:GetFunction
                  - lambda:ListLayers
                  - lambda:ListLayerVersions
                  - s3:ListAllMyBuckets
                  - s3:GetBucketLocation
                  - s3:GetBucketTagging
                  - elasticfilesystem:DescribeFileSystems
                  - elasticfilesystem:DescribeMountTargets
                  - elasticfilesystem:ListTagsForResource
                  - ecr:DescribeRepositories
                  - ecr:DescribeImages
                  - ecr:ListTagsForResource
                  - ecr:DescribeImageScanFindings
                  - inspector2:ListFindings
                  - inspector2:ListCoverage
                  - inspector2:BatchGetAccountStatus
                  - rds:DescribeDBInstances
                  - rds:DescribeDBClusters
                  - rds:ListTagsForResource
                  - dynamodb:ListTables
                  - dynamodb:DescribeTable
                  - dynamodb:ListTagsOfResource
                  - elasticache:DescribeCacheClusters
                  - elasticache:DescribeReplicationGroups
                  - elasticache:ListTagsForResource
                  - redshift:DescribeClusters
                  - es:ListDomainNames
                  - es:DescribeDomain
                  - es:DescribeDomains
                  - es:ListTags
                  - sqs:ListQueues
                  - sqs:GetQueueAttributes
                  - sqs:ListQueueTags
                  - sns:ListTopics
                  - sns:GetTopicAttributes
                  - sns:ListTagsForResource
                  - events:ListRules
                  - events:DescribeRule
                  - events:ListTagsForResource
                  - kinesis:ListStreams
                  - kinesis:DescribeStreamSummary
                  - kinesis:ListTagsForStream
                  - apigateway:GET
                  - states:ListStateMachines
                  - states:DescribeStateMachine
                  - states:ListTagsForResource
                  - cloudfront:ListDistributions
                  - cloudfront:GetDistribution
                  - cloudfront:ListTagsForResource
                  - organizations:ListAccounts
                  - organizations:DescribeAccount
                  - organizations:DescribeOrganization
                  - organizations:ListTagsForResource
                  - organizations:ListRoots
                  - organizations:ListOrganizationalUnitsForParent
                  - organizations:ListAccountsForParent
                  - sts:GetCallerIdentity
                Resource: '*'

Outputs:
  RoleARN:
    Description: Provide this Role ARN to DevGrid
    Value: !GetAtt DevGridReadOnlyRole.Arn

Step 3 — Complete the setup

Click I've deployed the role in the DevGrid modal. On the next screen:

  • Enter your AWS Account ID (12-digit number)
  • Paste the Role ARN copied from CloudFormation Outputs
  • Select the AWS regions DevGrid should scan for that account

For organization discovery, enter the management account ID and Role ARN. Regions selected there apply to discovered member accounts. You do not paste a row per member if those accounts already have DevGridReadOnlyRole.

Click Save. Then on the AWS integration page, click Test connection. After a successful test, click Activate to start syncing.

Multi-account setup

Manual: Click Add another account in the form. Deploy the CloudFormation template in each AWS account (Step 2) and paste that account’s ID, Role ARN, and regions. All accounts share the same External ID.

Organization discovery: Deploy the template to member accounts with a StackSet (same role name and External ID). In DevGrid, connect only the management account. DevGrid lists organization accounts, skips SUSPENDED accounts, and skips members that do not have DevGridReadOnlyRole (AccessDenied). Use the manual path for accounts that are not in the organization or that use a different role name.

What DevGrid collects

DevGrid scans resource metadata only — names, IDs, configurations, and tags. It never accesses S3 object contents, database records, Lambda source code, or any customer data. All API calls are logged in your AWS CloudTrail.

Resources scanned include: EC2, ECS, EKS, Lambda, S3, RDS, DynamoDB, ElastiCache, ECR, Inspector, SQS, SNS, EventBridge, Kinesis, API Gateway, Step Functions, CloudFront, AWS Organizations accounts (id, name, email, status — when the connected account is the management or delegated administrator account), and more.

Troubleshooting

"No valid AWS accounts or regions remained after validation"

The IAM role trust policy does not match. Check:

  • The CloudFormation stack deployed successfully
  • The Role ARN you pasted matches the ARN in the stack Outputs tab
  • The trust policy includes the correct External ID (shown in the setup modal)

Role ARN format

The Role ARN should look like: arn:aws:iam::123456789012:role/DevGridReadOnlyRole

Organizations APIs fail / no member accounts discovered

The connected role is not in the management (or delegated administrator) account, or an SCP is denying organizations:ListAccounts.

Member account listed but inventory is empty

The StackSet did not create DevGridReadOnlyRole in that account, or the role name or External ID does not match the management-account template.

Manual IAM setup

If you prefer not to use CloudFormation, create the IAM role manually:

  1. Go to IAM → Roles → Create Role → Another AWS account
  2. Enter DevGrid's AWS account ID (shown in the setup modal)
  3. Check Require external ID and paste your External ID (shown in the setup modal)
  4. Attach an inline policy with the permissions listed in the CloudFormation template
  5. Name the role DevGridReadOnlyRole (or any name — the Role ARN is what matters)
  6. Copy the Role ARN and paste it into DevGrid

For organization-wide access, use a CloudFormation StackSet (or equivalent) instead of creating the role by hand in every member account. Discovered members must use the name DevGridReadOnlyRole.

Updated about 2 hours ago