PlatformIntegration GuidesAWS

Setting up an AWS Integration

CloudQuery Platform supports authentication with AWS through IAM Roles for Service Account (IRSA).

The AWS accounts involved are:

  • CloudQuery Account: This is the AWS account where CloudQuery Platform is deployed. This account hosts the IAM role that CloudQuery uses to assume roles in other accounts.
  • Your Account: This is the AWS account that you want to sync resources from. This account will have a role that allows the CloudQuery account’s role to assume and read resources.

Prerequisites

The following values are referenced as environment variables in the setup commands below. All three must be added as secrets in the Secrets section of your AWS plugin configuration in CloudQuery Platform.

  • CLOUDQUERY_ACCOUNT_ID and TENANT_ID — Request these from CloudQuery support, then add them as secrets.
  • EXTERNAL_ID — Generate this yourself (e.g. by running uuidgen). An external ID is recommended by AWS best practices to provide an additional verification layer when assuming roles in a third-party account. It can be any alphanumeric string between 2 and 1224 characters.

Add all three values — CLOUDQUERY_ACCOUNT_ID, TENANT_ID, and EXTERNAL_ID — as secrets in the Secrets section of your AWS plugin configuration before proceeding.

IAM Role And Permissions

Use this approach if you want to sync only from one AWS Account.

  1. Create the trust relationship for the cross-account role:
cat >third-party-trust.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::${CLOUDQUERY_ACCOUNT_ID}:role/syncs-${TENANT_ID}-role"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "${EXTERNAL_ID}"
                }
            }
        }
    ]
}
EOF
  1. Create the cross-account role and attach the ReadOnly policy:
aws iam create-role --role-name cross-account-readonly-role \
    --assume-role-policy-document file://third-party-trust.json

aws iam attach-role-policy \
    --role-name cross-account-readonly-role \
    --policy-arn="arn:aws:iam::aws:policy/ReadOnlyAccess"

Configuring the Integration

After creating the IAM role in your AWS account, you need to configure the AWS integration in CloudQuery Platform.

  1. Navigate to Data Pipelines → Integrations in CloudQuery Platform.
  2. Click Create Integration and select AWS.

AWS Yaml Configuration

  1. Update the YAML configuration with the role ARN of the IAM role you created and the external ID. Use the appropriate format for your setup:
kind: source
spec:
  name: aws
  path: cloudquery/aws
  version: "v32.26.0" # latest version of source aws plugin
  tables:
    - aws_ec2_instances
  spec:
    accounts:
      - account_name: your_account
        role_arn: "arn:aws:iam::<your_account>:role/cross-account-readonly-role"
        external_id: "${EXTERNAL_ID}"

Replace <your_account> with your AWS account ID. The role_arn should correspond to the cross-account-readonly-role created in the previous step.

The external_id value must match the name of the EXTERNAL_ID secret you configured in the Secrets section of the plugin UI.

  1. Click Test Connection to verify the setup.

Next Steps

With your AWS integration created, you can now proceed to use it in a new sync. This will give you the opportunity to specify when your AWS sync should be run, and to which destination databases.

AlertsAWS Cost & Usage