Overview
This guide outlines the prerequisites and requirements for successfully onboarding your AWS Organization to the Wiv.ai FinOps platform. Please ensure all requirements are met before initiating the onboarding process.
The Wiv onboarding stack deploys resources in your AWS Management Account to enable comprehensive cost visibility, optimization recommendations, and automated savings across your entire AWS Organization.
Quick Reference Checklist
Use this checklist to verify all prerequisites before starting the onboarding process:
- Stack deployed in us-east-1 region
- Stack deployed from AWS Management (Payer) Account
- Fewer than 10 existing CUR reports (at least 1 slot available)
- Lambda concurrent execution quota ≥ 102
- S3 bucket quota allows creating new bucket
- AWS Organizations enabled with all features
- CloudFormation StackSets service-managed permissions enabled
- IAM user/role has sufficient permissions (see Required Permissions)
1. Account Requirements
1.1 Management Account
The Wiv onboarding stack must be deployed from your AWS Management Account (also known as the Payer Account). This is the root account of your AWS Organization that receives the consolidated bill.
| Requirement | Details |
|---|
| Account Type | AWS Management Account (Payer Account) |
| Why Required | Access to organization-wide billing data, CUR reports, and ability to deploy StackSets to member accounts |
| Verification | AWS Console → Organizations → Your account should show as “Management account” |
1.2 Region Requirement
The stack must be deployed in the us-east-1 (N. Virginia) region. This is required because:
- Cost and Usage Reports (CUR) API is only available in us-east-1
- BCM Data Exports API operates exclusively in us-east-1
- AWS billing services are centralized in this region
2. Service Quotas
Verify the following service quotas before deployment.
2.1 Cost and Usage Reports
| Quota | Requirement |
|---|
| Maximum CUR Reports | Less than 10 existing reports (AWS limit is 10 per account) |
| How to Check | AWS Console → Billing → Cost & Usage Reports → Count existing reports |
| Resolution | Delete unused CUR reports or request quota increase via AWS Support |
2.2 Lambda Concurrent Executions
| Quota | Requirement |
|---|
| Unreserved Concurrent Executions | Minimum 102 available |
| How to Check | AWS Console → Lambda → Account Settings → Unreserved concurrency |
| CLI Command | aws lambda get-account-settings --region us-east-1 |
| Resolution | Request quota increase via Service Quotas console |
2.3 S3 Buckets
The onboarding process creates an S3 bucket named wiv-cur-{AccountId} for storing Cost and Usage Report data. Ensure your account has capacity for at least one additional bucket.
3. AWS Organizations Requirements
3.1 Organizations Features
| Feature | Requirement |
|---|
| All Features Enabled | Required for StackSets, Compute Optimizer, and Cost Optimization Hub |
| Trusted Access | CloudFormation StackSets must have trusted access enabled |
| How to Verify | AWS Console → Organizations → Settings → Organization features |
3.2 StackSets Prerequisites
The Wiv onboarding uses Service-Managed StackSets to deploy IAM roles across all member accounts. This requires:
- Trusted access for CloudFormation StackSets enabled in Organizations
- Auto-deployment enabled for new accounts joining the organization
To enable trusted access for StackSets:
- Navigate to AWS Organizations → Services → CloudFormation StackSets
- Click “Enable trusted access”
- Confirm the action
4. Required IAM Permissions
The IAM user or role deploying the CloudFormation stack requires the following permissions.
| Service | Permissions Required |
|---|
| CloudFormation | CreateStack, UpdateStack, DeleteStack, DescribeStacks, CreateStackSet, CreateStackInstances |
| IAM | CreateRole, AttachRolePolicy, PutRolePolicy, CreatePolicy, PassRole |
| S3 | CreateBucket, PutBucketPolicy, PutBucketEncryption, PutLifecycleConfiguration |
| Lambda | CreateFunction, InvokeFunction, GetAccountSettings |
| Glue | CreateDatabase, CreateTable, CreateCrawler |
| Athena | CreateWorkGroup |
| CUR / BCM Data Exports | CreateExport, DescribeReportDefinitions, PutReportDefinition |
| Organizations | DescribeOrganization, ListAccounts, EnableAWSServiceAccess |
| Cost Explorer | UpdatePreferences (for Split Cost Allocation) |
For initial deployment, using an IAM role with AdministratorAccess simplifies the process. You can scope down permissions after successful deployment.
5. Resources Created by Onboarding
The following AWS resources will be created during onboarding.
5.1 In Management Account
| Resource | Purpose |
|---|
| S3 Bucket | wiv-cur-{AccountId} — Stores CUR data with intelligent tiering |
| CUR 2.0 Export | Hourly cost data with resource-level detail in Parquet format |
| Glue Database | wivdb — Catalog for CUR data |
| Glue Table | Partitioned table with projection for efficient queries |
| Athena Workgroup | WivWorkspace — Dedicated workgroup for queries |
| IAM Role | WivAccessRole — Cross-account role for Wiv platform access |
| Lambda Functions | Pre-check validation, CUR setup, Split Cost Allocation enablement |
| CloudFormation StackSet | WivOrgStackSet — Deploys IAM roles to all member accounts |
5.2 In Each Member Account
| Resource | Purpose |
|---|
| IAM Role | WivAccessRole — Read-only access for cost and resource data |
| IAM Policies | Core access, EventBridge, Organizations retrieval policies |
6. Optional Features Configuration
The following optional features can be enabled during onboarding.
6.1 Split Cost Allocation Data
Provides container-level cost visibility for ECS and EKS workloads.
| Feature | Description |
|---|
| ECS Split Cost | Allocates EC2 costs to individual ECS tasks based on resource utilization |
| EKS Split Cost | Allocates costs to Kubernetes pods. Three methods available: ResourceRequests (default — uses pod CPU/memory requests), Prometheus (uses actual utilization via Amazon Managed Prometheus), ContainerInsights (uses CloudWatch Container Insights metrics) |
6.2 Cost Optimization Services
| Service | Description |
|---|
| Compute Optimizer | ML-powered rightsizing recommendations for EC2, Lambda, EBS, and more |
| Cost Optimization Hub | Centralized view of all AWS cost optimization recommendations |
| Trusted Access | Enables organization-wide visibility for optimization services |
7. Pre-Deployment Verification Commands
Run these AWS CLI commands to verify prerequisites.
7.1 Verify Management Account
aws organizations describe-organization \
--query 'Organization.MasterAccountId' --output text
7.2 Check CUR Report Count
aws cur describe-report-definitions \
--region us-east-1 --query 'length(ReportDefinitions)'
7.3 Check Lambda Concurrency
aws lambda get-account-settings \
--region us-east-1 --query 'AccountLimit.UnreservedConcurrentExecutions'
7.4 Verify Organizations Features
aws organizations describe-organization \
--query 'Organization.FeatureSet'
"ALL" (not "CONSOLIDATED_BILLING")
8. Onboarding Parameters Reference
The following parameters are available when deploying the onboarding stack.
8.1 Required Parameters (Auto-generated)
| Parameter | Description |
|---|
| ExternalId | Unique identifier provided by Wiv for secure cross-account access |
| OBID | Onboarding ID for tracking the integration in Wiv platform |
| IntegrationName | Display name for this AWS integration in Wiv dashboard |
8.2 Optional Parameters
| Parameter | Default | Description |
|---|
| Environment | prod | Backend environment (prod/dev) |
| OrganizationId | (empty) | AWS Organization ID for org-based trust |
| EnableSplitCostAllocationECS | Yes | Enable ECS container cost allocation |
| EnableSplitCostAllocationEKS | Yes | Enable EKS container cost allocation |
| EKSSplitCostMethod | ResourceRequests | EKS allocation method |
| EnableComputeOptimizer | Yes | Enable AWS Compute Optimizer |
| EnableCostOptimizationHub | Yes | Enable Cost Optimization Hub |
| EnableTrustedAccess | Yes | Enable organization trusted access |
9. Common Issues and Troubleshooting
| Issue | Resolution |
|---|
| ”Stack was not created on ‘us-east-1‘“ | Ensure you’re deploying in us-east-1 region. Change region in AWS Console. |
| ”Stack was not created with the master account” | You must deploy from the Management Account. Switch accounts and retry. |
| ”No place to create new CUR report” | Delete unused CUR reports. AWS allows maximum 10 per account. |
| ”Lambda UnreservedConcurrentExecutions is less than 102” | Request Lambda quota increase via Service Quotas console. |
| StackSet deployment fails | Verify trusted access is enabled for CloudFormation StackSets in Organizations. |
| Access Denied errors | Ensure the deploying IAM role has all required permissions listed in Section 4. |
| CUR data not appearing | CUR data can take up to 24 hours to appear after initial setup. |
10. Getting Help
If you encounter issues during onboarding or have questions about prerequisites, contact Wiv support at support@wiv.ai.