AWS Organization Setup

Overview

To set up Heeler across an AWS Organization, Heeler deploys a single CloudFormation or Terraform template to the management (payer) account. This template uses CloudFormation StackSets to automatically deploy the necessary resources to all member accounts, including any accounts added in the future. In each member account, Heeler provisions IAM roles and policies with tightly scoped permissions. These permissions allow Heeler to access only metadata and configuration details—never your application data.

Setup Options

• CloudFormation (Recommended)

• Terraform

CloudFormation

When CloudFormation is selected the StackSet is automatically launched during the onboarding wizard, or you can download the template here.

The template performs the following actions:

Payer Account

• Create an IAM policy, Heeler, that denies visibility to the customer data plane. This includes actions such as s3:GetObject, dynamodb:GetItem and more.

• Create an IAM policy, HeelerEKS, that allows EKS cluster API access configuration so Heeler can automatically harvest Kubernetes resources.

• Create two roles heeler-management-ro and heeler-member. The first role is created with an inline policy that allows visibility into the payer account's AWS Organization configuration. The second role, heeler-member is configured with the newly created policies as well as the AWS-managed policy ReadOnlyAccessto allow visibility into the account. It also is configured with a trust policy that allows heeler-management-ro to assume it.

• Creates a CloudFormation StackSet that performs the steps outlined below across all member accounts and accounts as they are added in the future.

Member Account

• Create an IAM policy, Heeler, that denies visibility to the customer data plane. This includes actions such as s3:GetObject, dynamodb:GetItem and more.

• Create an IAM policy, HeelerEKS, that allows EKS cluster API access configuration so Heeler can automatically harvest Kubernetes resources.

• Create a single role, heeler-member, with the newly created policies as well as the AWS-managed policy ReadOnlyAccessto allow visibility into the account. It also is configured with a trust policy that allows heeler-management-ro to assume it.

Heeler Connection Setup

1. Select the icon from the top navigation

2. Navigate to the Connections tab

3. Select Cloud Organizations

4. Click Add Organization and select AWS

5. Select Setup with CloudFormation

1. If you haven't confirmed that you have the required permissions, now is a good time to do so. Also, you will need to have the Root ID (or Organizational Unit ID) of the target deployment when configuring the CloudFormation StackSet.

2. Select Launch CloudFormation StackSet

1. Choose your active session or sign into a new session. The session should be in the payer account.

1. Confirm that the stack launches into the desired AWS account, that it is deploying the Heeler CFT, and that it has the Heeler-default Stack name.

1. Provide or accept the default parameters:

   1. Organization Unit List: This should be the Root ID (format like r-1234) or other top-level Organization Unit (format like o-abc123def4)

   2. Account List (optional): Accounts provided here are excluded from the deployment

   3. Scope Change (optional): By default, accounts provided in the Accounts List are excluded. By changing this value from exclude to limit, the provided accounts are the only accounts included. If Accounts List is empty (the default), this value does not matter.

   4. Heeler Role Name (Required): Default value is heeler-member. Can be updated

   5. External ID (Recommended): Default value is auto-generated and recommended. Can be updated or deleted

   6. Role ARN provided by Heeler Security: Default value should not be changed unless instructed otherwise

1. As this CloudFormation StackSet deploys IAM roles and policies, you must acknowledge their creation and then select Create stack

1. No action required. You can monitor the creation of resources by viewing the Events tab. The deployment is complete when it says CREATE_COMPETE.

1. Copy the Output value for ManagementReadOnlyRoleArn for use when configuring the connection in Heeler.

1. Copy the Parameter values for ExternalID, HeelerSecurityRoleArn, and MemberRoleNamefor use when configuring the connection in Heeler. If there are values for AccountList or OrganizationUnitList, copy them too.

1. Back in the Heeler modal, populate the values:

   1. Organization Name: a human-friendly name that identies the organization in Heeler

   2. Organization Role ARN: the ManagementReadOnlyRoleArn

   3. Organization Role External ID: the ExternalID

   4. Member Account Role Name: the MemberRoleName

   5. Member Role External ID (Optional): this property is deprecated and will be removed

   6. OU IDs to skip: the OrganizationUnitList values, if any

   7. Skip Listed Accounts: the AccountList values, if any

   8. Region Restrictions: Optional list of regions in which to limit harvesting. This configuration is helpful if resources are limited by Service Control Policies to specific regions. (This restriction is not configured in the CloudFormation StackSet, because it deploys IAM resources, which are global.)

   9. Select Done

1. When added successfully, you will see a Healthy notification status

Terraform

This Terraform module configures Heeler Security at the AWS Organization level. The module must be applied to your payer (organization management) account.

Download the terraform module:

Before applying this template, ensure the following:

• AWS CloudFormation StackSets are enabled in your organization

• Retrieve your AWS Organization Root ID (you'll need this during setup)

• Terraform version 1.8.4 or greater is installed

• AWS CLI is configured and authenticated to your payer account

• You have required permissions to create IAM roles and CloudFormation StackSets

What This Template Deploys

The template creates the following AWS resources:

1. Management Role: Read-only role assumed by Heeler Security to fetch resources from accounts (includes inline policy)

2. Member Role: Read-only role assumed by the management role to access member account resources (attached with three policies including AWS Managed ReadOnly policy)

3. Member Read-only Policy: Heeler policy that denies access to certain actions and allows SSM SendCommand

4. EKS Policy: Heeler policy that allows configuring API access to EKS clusters

5. CloudFormation StackSet: Deploys resources across all member accounts in the organization

6. Policy Attachment: Links custom policies to the member role

7. StackSet Instance: Instantiates the StackSet deployment

Setup Instructions

Step 1: Retrieve Generated External ID from Heeler

• Select the icon from the top navigation

• Navigate to the Connections tab

• Select Cloud Organizations

• Click Add Organization and select AWS

• Select Setup manually

• Click Next

• Retrieve the Organization Role External ID from the popup

• Place into the variables.tf

Step 2: Initialize Terraform

Navigate to the directory containing the Terraform files and run:

terraform init

Expected output:

Initializing the backend...
Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Using previously-installed hashicorp/aws v5.63.1

Terraform has been successfully initialized!

Step 3: Review the Plan

Preview the changes that will be made:

terraform plan

Expected output (sample):

# aws_iam_role.heeler_member will be created
+ resource "aws_iam_role" "heeler_member" {
    + arn                   = (known after apply)
    + assume_role_policy    = (known after apply)
    + create_date           = (known after apply)
    + description           = "Role that the read-only management role will assume to fetch resources from member accounts and allow API access to EKS clusters"
    + force_detach_policies = false
    + id                    = (known after apply)
    + managed_policy_arns   = (known after apply)
    + max_session_duration  = 28800
    + name                  = "heeler-member-tf"
    + name_prefix           = (known after apply)
    + path                  = "/"
    + tags_all              = (known after apply)
    + unique_id             = (known after apply)
  }

Plan: 7 to add, 0 to change, 0 to destroy.

Review the plan carefully to ensure all expected resources are listed.

Step 4: Apply the Configuration

Deploy the infrastructure:

terraform apply

You'll see a confirmation prompt similar to:

Plan: 7 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

Enter a value:

Type yes and press Enter to proceed.

Step 5: Monitor Deployment

The deployment process may take several minutes. You'll see periodic status updates:

aws_cloudformation_stack_set_instance.heeler_setup: Still creating... [10s elapsed]
aws_cloudformation_stack_set_instance.heeler_setup: Still creating... [20s elapsed]

Optional: If you have AWS Console access, you can monitor progress in CloudFormation > Stacks > Events.

Step 6: Verify Completion

When successful, you'll see:

Apply complete! Resources: 7 added, 0 changed, 0 destroyed.

Step 6: Configure Heeler with AWS Deployment Options

• Organization Name: a human-friendly name that identifies the organization in Heeler

• Organization Role ARN: the ManagementReadOnlyRoleArn

• Organization Role External ID: the ExternalID

• Member Account Role Name: the MemberRoleName

• Member Role External ID (Optional): this property is deprecated and will be removed

• OU IDs to skip: the OrganizationUnitList values, if any

• Skip Listed Accounts: the AccountList values, if any

• Region Restrictions: Optional list of regions in which to limit harvesting. This configuration is helpful if resources are limited by Service Control Policies to specific regions. (This restriction is not configured in the CloudFormation StackSet, because it deploys IAM resources, which are global.)

• Select Done

• When added successfully, you will see a Healthy notification status