Skip to content

AWS integration

Connect DXDT to your AWS account(s) with a read-only identity so DXDT can run read-only AWS CLI calls for SRE and FinOps insight. You provide named accounts, each authenticated by either a cross-account IAM role (recommended) or read-only access keys.
Setup time ~20 minutes
Difficulty Advanced

Access required: AWS IAM administrator access to create a read-only role or user in each account you want DXDT to observe.

Prerequisites

  • An AWS account (or several) you want DXDT to observe.
  • Permission to create IAM roles/users and attach the ReadOnlyAccess (or ViewOnlyAccess) AWS managed policy.
  • Your 12-digit AWS account ID(s) and preferred default region (for example us-east-1).

Setup

1. Decide on an auth mode per account

DXDT supports two credential modes and auto-detects which you supplied. A cross-account IAM role (with role_arn + external_id) is strongly recommended over long-lived keys because it grants no standing credentials. Use read-only access keys only where role assumption is not practical.

In the AWS Console → IAM → Roles → Create role, choose AWS account as the trusted entity. Enable Require external ID and enter a strong, unique value you will reuse as external_id. Attach the AWS managed policy ReadOnlyAccess (or the tighter ViewOnlyAccess). After creation, copy the role's role_arn (for example arn:aws:iam::123456789012:role/DXDT-ReadOnly).

  • Trusted entity type: AWS account (the DXDT platform's master account, provided by DXDT).
  • Options: check Require external ID and set a unique secret.
  • Permissions: attach ReadOnlyAccess or ViewOnlyAccess only — no write/admin policies.
  • Copy the resulting role_arn and note the external_id.

Note

The trust policy must trust the DXDT master identity so DXDT can AssumeRole. If you do not yet have the DXDT master account ID, request it from DXDT support before creating the role.

3. Alternative: create read-only access keys

If you cannot use a role, go to IAM → Users → Create user, attach ReadOnlyAccess, then create an access key for programmatic access. Copy the aws_access_key_id and aws_secret_access_key (the secret is shown only once).

4. Build the accounts map

DXDT keys credentials under an accounts map so you can observe multiple accounts. Each entry is a friendly name mapping to either role fields or key fields, plus aws_default_region.

  • Role entry: {"prod": {"role_arn": "arn:aws:iam::123456789012:role/DXDT-ReadOnly", "external_id": "<secret>", "aws_default_region": "us-east-1"}}
  • Access-key entry: {"staging": {"aws_access_key_id": "AKIA...", "aws_secret_access_key": "...", "aws_default_region": "eu-west-1"}}
  • You may mix roles and keys across named accounts in the same map.

5. Enter the configuration in DXDT

Open the aws-exec plugin in the DXDT marketplace and paste your accounts map into the configuration. On save, DXDT validates the credentials (via /on-install) without storing anything beyond your encrypted config — the exec service is stateless.

Configuration fields

Field Where to find it
Accounts (accounts) A map of name -> credentials. Each value is EITHER an IAM role {role_arn, external_id, aws_default_region} OR access keys {aws_access_key_id, aws_secret_access_key, aws_default_region}. Use one named entry per AWS account you want DXDT to observe.

Verify the connection

After saving, open the plugin Status view. A healthy connection lists each named account and its detected permission level (read-only). You can also confirm DXDT can enumerate resources without errors.

Security

DXDT runs only read-only AWS CLI calls and stores no standing credentials on the exec service (it is stateless). Grant least privilege: prefer a cross-account IAM role with an external_id and only the ReadOnlyAccess/ViewOnlyAccess policy — never attach write or admin permissions.

Troubleshooting

AccessDenied when DXDT assumes the role

The role's trust policy does not trust the DXDT master account, or the external_id does not match. Edit the role's trust relationship to trust the DXDT master identity and confirm the external_id in your accounts map exactly matches the role's required external ID.

InvalidClientTokenId or SignatureDoesNotMatch on access keys

The aws_access_key_id/aws_secret_access_key is wrong, deactivated, or from a different account. Regenerate the access key for the read-only user and paste both values again; ensure no whitespace was copied.

Commands fail with authorization errors even though creds are valid

The attached policy is narrower than ReadOnlyAccess, so some read APIs are blocked. Attach the AWS managed ReadOnlyAccess (or ViewOnlyAccess) policy to the role/user. DXDT never needs write permissions.

One account works but another shows no data

Wrong aws_default_region or a per-account credential typo in the accounts map. Verify each named entry's region and credentials independently; the map is validated per account.

Vendor documentation: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html