AWS Setup Guide

This guide walks you through creating a read-only IAM user for CLARITY and adding it to your instance.

Prerequisites

• An AWS account with IAM administrative access
• AWS CLI installed or access to the AWS Console
• AWS Cost Explorer enabled in your account

Option 1: AWS CLI (Recommended)

Create a dedicated IAM user with AWS-managed read-only policies:

# Create a dedicated IAM user for CLARITY
aws iam create-user --user-name clarity-finops

# Attach read-only access (covers all resource discovery, metrics, etc.)
aws iam attach-user-policy --user-name clarity-finops \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

# Attach billing read access (Cost Explorer, budgets, anomalies)
aws iam attach-user-policy --user-name clarity-finops \
  --policy-arn arn:aws:iam::aws:policy/AWSBillingReadOnlyAccess

# Create access keys (save the output — the secret is shown only once)
aws iam create-access-key --user-name clarity-finops

Save the AccessKeyId and SecretAccessKey from the output. You will need both when adding the account to CLARITY.

Why ReadOnlyAccess?

ReadOnlyAccess is an AWS-managed policy that grants read-only access across all AWS services. CLARITY uses this broad access to discover all resources that may generate costs — EC2 instances, RDS databases, S3 buckets, EBS volumes, snapshots, load balancers, Lambda functions, ECS/EKS clusters, ElastiCache, ECR repositories, Route53 zones, NAT gateways, and more. This ensures complete visibility into idle, oversized, and underutilized resources across your account.

Option 2: CloudFormation Template

Deploy the IAM user with managed policies as a CloudFormation stack:

AWSTemplateFormatVersion: '2010-09-09'
Description: CLARITY FinOps — Read-only IAM user for cost management

Resources:
  ClarityFinOpsUser:
    Type: AWS::IAM::User
    Properties:
      UserName: clarity-finops
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/ReadOnlyAccess
        - arn:aws:iam::aws:policy/AWSBillingReadOnlyAccess
      Tags:
        - Key: Purpose
          Value: CLARITY FinOps read-only access

  ClarityAccessKey:
    Type: AWS::IAM::AccessKey
    Properties:
      UserName: !Ref ClarityFinOpsUser

Outputs:
  AccessKeyId:
    Description: Access Key ID for CLARITY
    Value: !Ref ClarityAccessKey
  SecretAccessKey:
    Description: Secret Access Key for CLARITY (retrieve from CloudFormation console)
    Value: !GetAtt ClarityAccessKey.SecretAccessKey

Deploy the stack:

aws cloudformation deploy \
  --template-file clarity-iam.yaml \
  --stack-name clarity-finops-iam \
  --capabilities CAPABILITY_NAMED_IAM

# Retrieve the access keys from stack outputs
aws cloudformation describe-stacks \
  --stack-name clarity-finops-iam \
  --query "Stacks[0].Outputs"

Adding to CLARITY

1. Log in to CLARITY and navigate to Provider Setup (gear icon in the sidebar)
2. Click Add Account
3. Select AWS as the provider
4. Enter the following:
   • Access Key ID — from the IAM user creation output
   • Secret Access Key — from the IAM user creation output
   • Account Name (optional) — a friendly label like "Production" or "Dev/Staging"
5. Click Save

CLARITY validates the credentials immediately and begins the initial sync. You will see a progress indicator while resources, costs, and metrics are pulled from your account.

Verification

After the initial sync completes (typically 2-5 minutes), verify that data is flowing:

• Dashboard — Cost breakdown by service and region should appear
• Resources — Your EC2 instances, RDS databases, S3 buckets, and other resources should be listed with cost estimates
• Insights — Optimization recommendations for idle or underutilized resources
• Forecast — Cost projections based on your billing history

If the dashboard shows cost data but the resource list is empty, the IAM user may be missing some Describe* permissions. Check the sync logs for specific errors.

AWS Organizations

If your account is a management (payer) account in an AWS Organization, CLARITY automatically discovers all member accounts and reports organization-level costs. The organizations:DescribeOrganization and organizations:ListAccounts permissions (included in ReadOnlyAccess) enable this. Member accounts will show as linked accounts in the Organizations page.

Cost Explorer Activation

AWS Cost Explorer must be enabled in your account before CLARITY can retrieve billing data. If you have never used Cost Explorer:

1. Go to the AWS Cost Explorer console
2. Click Enable Cost Explorer
3. Wait up to 24 hours for historical data to become available

Cost Explorer API calls are billed at $0.01 per request. CLARITY minimizes API usage with intelligent caching and a default 12-hour sync interval, resulting in approximately $1-2/month in Cost Explorer charges.

Cleanup

To remove CLARITY access from your AWS account:

# Delete the access key
aws iam delete-access-key --user-name clarity-finops \
  --access-key-id YOUR_ACCESS_KEY_ID

# Detach policies
aws iam detach-user-policy --user-name clarity-finops \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess
aws iam detach-user-policy --user-name clarity-finops \
  --policy-arn arn:aws:iam::aws:policy/AWSBillingReadOnlyAccess

# Delete the user
aws iam delete-user --user-name clarity-finops

Or if you used the CloudFormation template:

aws cloudformation delete-stack --stack-name clarity-finops-iam