AWS

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.

Integration Methods

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

• CloudFormation

• Terraform

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.

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

Setup 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) Select Mark as Production if you want to use the integration to be flagged as production in Firefly.

5. Click Generate Terraform Snippet.

6. Copy the generated details into your Terraform code file.

7. Run:

   terraform init
   terraform plan
   terraform apply

8. Select Done.

Additional setup instructions and information about the Firefly onboarding Terraform module are available in Firefly AWS Integration.

Using CloudFormation

Firefly offers two CloudFormation integration options:

• Single Account Integration: Use CloudFormation to integrate individual AWS accounts.

• AWS Organization Integration: Use CloudFormation StackSet to integrate multiple accounts across your AWS Organization.

Setup 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.

5. Select Single Account Integration CloudFormation or AWS Organization CloudFormation.

6. Paste your AWS account ID.

7. 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.

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. Find the integration you want to scan.

3. For assets changes, on the integration menu, select Scan Assets.

4. For IaC stacks changes, on the integration menu, select Scan Stacks.

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