AWS

Overview

Amazon Web Services (AWS) integration can be set up using either CloudFormation or Terraform. This guide covers both methods and best practices for integrating your AWS account with Firefly.

When integrating an AWS account, you have two primary methods:

• Terraform

• CloudFormation

Both methods create a cross-account IAM Role with read-only access (security audit permissions) to your resources. The integration may also set up an Amazon SNS notifications for tfstate files event-driven scanning.

Best Practices

1. Use a dedicated AWS account (or at least a separate IAM role) for Firefly's access

2. Grant only the minimum read permissions (Firefly's provided template covers what's needed)

3. Monitor the Firefly integration user/role in AWS to ensure it's not being used elsewhere

4. Consider enabling Event-Driven Mode for quick detection of drift and changes

Integration Methods

Using Terraform

Prerequisites

1. Terraform v0.13 or later

2. AWS CLI installed and configured

3. IAM user with necessary roles

4. Selected AWS region(s)

To verify prerequisites, run:

cat ~/.aws/credentials && terraform init && terraform --version

Procedure

1. In Firefly, go to Settings > Integrations

2. Select Add New > AWS > Terraform

3. Enter a descriptive name in Integration Nickname field

4. (Optional) Enable Event-driven mode and select region(s)

5. (Optional) Configure S3 Event Notifications for TF State Files

6. Select Next

7. Copy the generated details into your Terraform code file

8. Run:

   terraform init
   terraform apply

9. Select Done

Using CloudFormation

Procedure

1. Log in to AWS with permissions for CloudFormation and IAM

2. Copy your AWS account ID from the AWS console

3. In Firefly, go to Settings > Integrations

4. Select + Add New > AWS > CloudFormation

5. Paste your AWS account ID

6. Select Launch Stack

Event-Driven Integration

Event-driven mode ensures near real-time updates of your assets in the inventory. To use this feature:

1. Enable CloudTrail in your AWS account

2. Select Enable IaC Auto-Discovery to scan for new Terraform state files

3. (Optional) Set up S3 Event Notifications for Terraform State Files

Upgrading to Event-Driven Mode

For Terraform Integrations

Add these lines to your module call and run terraform apply:

is_event_driven = true
exist_integration = true

For CloudFormation Integrations

1. Generate Firefly access and secret key (Settings > Users > Create key pair)

2. Copy the external ID of the Firefly IAM role from AWS console

3. Use the same integration nickname as in Firefly

4. Apply the following code:

module "firefly {
  source               = "github.com/gofireflyio/terraform-firefly-aws-onboarding"
  firefly_access_key   = "YOUR_ACCESS_KEY"
  firefly_secret_key   = "YOUR_SECRET_KEY"
  role_external_id     = "YOUR_EXTERNAL_ID"
  is_prod              = false/true
  is_event_driven      = true 
  event_driven_regions = ["us-east-1","us-east-2"] //choose relevant region
}

AWS Discovery Status

To scan your integration for changes:

1. Go to Settings > Integrations > AWS

2. Select your integration

3. For asset changes:

   • Go to the Assets card

   • Select Scan now

4. For IaC stack changes:

   • Go to the Stacks card

   • Select Scan now

5. View changes in the Inventory and/or IaC Explorer after several minutes