AWS Integration setup for drift detection and resource analysis

TL;DR: What This Setup Does

This setup allows your application to securely assume an IAM role via AWS STS to extract metadata and execute AWS SDK commands based on Terraform state files.

Key Purpose:

✅ Grants Read-Only Access to AWS Resources → Ensures your app can fetch all necessary Terraform-managed metadata.

✅ Supports STS AssumeRole → Enables secure role assumption so your app can access AWS without static credentials.

✅ Includes ExternalId for Security → Protects against unauthorized access (confused deputy problem).

✅ Ensures Tags & Metadata Are Fully Accessible → Explicit permissions ensure all AWS services provide necessary details.

✅ Supports Future Refinement → Allows logs to identify missing permissions for fine-tuning.

This guide explains how to configure your AWS environment so your application can securely assume an IAM role to extract metadata and execute SDK commands derived from Terraform state files. Follow these steps to set it up.

Prerequisites

• An AWS account with permissions to create IAM roles and policies.
• Terraform state files stored in your environment that your application will process.
• A designated IAM role that the application will assume via STS when running AWS SDK commands.
• Terracotta’s AWS account ID: 489507631213.
• Optionally, an ExternalId (a unique string you create, like TerraformSDK-Secure-123)—more on this below.

Step 1: Create an IAM Role for Terraform SDK Execution

1. Navigate to IAM: Go to IAM > Roles > Create Role in the AWS console.

2. Set the Trusted Entity: Select "Another AWS account" and enter your AWS account ID to allow the application to assume this role.

   1. Enter the OpsBerry AI AWS VPC account ID: 489507631213

3. Define the Trust Policy with ExternalId (Optional):

   1. Use the following JSON to allow your application to assume the role securely. You can include an ExternalId (optional but recommended for security—see below):
   JSON

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::489507631213:root"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

   • About the "Root" ARN: The arn:aws:iam::489507631213:root refers to your entire AWS account, not the root user. It allows any IAM user or role in the account with sts:AssumeRole permission to assume this role.
   • What’s the ExternalId?: The ExternalId (e.g., TerracottaSDK-Secure-123) is a custom string you create to add security. It’s like a shared secret: only your application, when given this value, can assume the role, preventing unauthorized use (a “confused deputy” issue). Share it securely with your application (e.g., encrypted storage, not plaintext).

4. Attach a Permissions Policy: Edit the role and attach this policy to grant read-only access to all Terraform-supported AWS resources:

   JSON

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "aws-marketplace:Describe*",
           "aws-marketplace:List*",
           "aws-marketplace:Get*",
           "cloudformation:Describe*",
           "cloudformation:List*",
           "cloudformation:Get*",
           "cloudfront:Describe*",
           "cloudfront:List*",
           "cloudfront:Get*",
           "cloudtrail:Describe*",
           "cloudtrail:List*",
           "cloudtrail:Get*",
           "cloudwatch:Describe*",
           "cloudwatch:List*",
           "cloudwatch:Get*",
           "dynamodb:Describe*",
           "dynamodb:List*",
           "dynamodb:Get*",
           "ec2:Describe*",
           "ec2:List*",
           "ec2:Get*",
           "iam:List*",
           "iam:Get*",
           "lambda:List*",
           "lambda:Get*",
           "rds:Describe*",
           "rds:List*",
           "rds:Get*",
           "s3:List*",
           "s3:Get*",
           "s3:GetTags",
           "s3:ListTags",
           "s3:ListTagsForResource",
           "sns:List*",
           "sns:Get*",
           "sqs:List*",
           "sqs:Get*",
           "sts:AssumeRole"
         ],
         "Resource": "*"
       }
     ]
   }

5. Name the Role: Call it something likeTerracottaSDKExecutionRole and create it.

Step 2: Share the Role ARN (and ExternalId, if Used)

1. Find the ARN: After creating the role, copy its ARN (e.g., arn:aws:iam::your-account-id:role/TerraformSDKExecutionRole).
2. On the Terracotta configuration on the app Share the ARN with Terracotta. If you used an ExternalId, send that too (e.g., Terracotta-Secure-123), using a secure method like encrypted email or a shared vault.

Step 3: Secure Access (Optional but Recommended)

1. Restrict Access to Specific Resources: If needed, modify the IAM policy to limit access to only Terraform-managed resources.

Step 4: Test the Configuration

1. Coordinate with your application: Ensure the application can assume the role and execute Terraform state-based AWS SDK commands.
2. Run a test query: Execute an AWS SDK command to verify access (e.g., aws ec2 describe-instances).
3. Verify Access: Confirm the application can retrieve Terraform metadata without AccessDenied errors.

Additional Notes

• ExternalId Handling: If you use it, pick a unique, hard-to-guess value (e.g., TerraformSDK-YourProject-2025) and store it securely. If you skip it, the setup still works but relies on your AWS account security.
• Monitoring: Enable CloudTrail and IAM role session logging to track usage.
• Temporary Access: The assumed role will receive temporary credentials (default 1 hour, max 12 hours).
• Refining Permissions: As your application evolves, log missing permissions and adjust the IAM policy accordingly.