# Advanced AWS account configuration > Customize the CloudFormation deployment: deployment scope, account filtering, deploying without StackSets, and updating an existing deployment --- Site [llms.txt](/llms.txt) --- Preparing your AWS environment for CloudBolt Platform integration requires IAM roles and an S3 bucket. This page describes how to use a CloudBolt-provided AWS CloudFormation template to create them. **The template creates the following:** - **Cross-account IAM roles:** Least-privilege IAM roles enabling cost report access. The FOCUS role can also create cost report exports on CloudBolt's behalf (but not delete them). - **Permissions for the cost report exports:** The template grants CloudBolt the permissions needed to create the [FinOps Open Cost and Usage Specification](https://focus.finops.org/what-is-focus/) (FOCUS) 1.0, FOCUS 1.2 Hourly, FOCUS 1.2 Daily, and Cost Optimization Recommendations data exports. When a connection is established, CloudBolt creates any that do not exist. - **S3 bucket:** Created when `CreateS3Bucket=true` (default), with policies for report storage. Set `CreateS3Bucket=false` to use an existing bucket. ## Prerequisites Before you begin, ensure the following: ### AWS account requirements - The management account has full access to AWS Organizations. - CloudFormation StackSets are enabled in the management account (required for [OrganizationWide and SpecificOU deployments](#deployment-scope)). - All target accounts are in the ACTIVE state. ### Service requirements - IAM permissions to create roles and policies. - S3 permissions for bucket creation and management. - **Cost Explorer** is enabled in the management account. Go to **Billing and Cost Management** > **Cost Explorer** and open it once to enable. - **AWS Compute Optimizer** is opted in for the account and all member accounts. Cost Optimization Hub sources its rightsizing recommendations from Compute Optimizer, so enable it first. Go to **Compute Optimizer** > **Get started**, or run: ```bash aws compute-optimizer update-enrollment-status \ --status Active \ --include-member-accounts ``` CloudBolt doesn't verify this enrollment. A connection succeeds without it, but your rightsizing recommendations are incomplete. - **Cost Optimization Hub** is opted in for the organization, including member accounts. Go to **Billing and Cost Management** > **Cost Optimization Hub**, choose **Enable Cost Optimization Hub for this account and all member accounts**, then select **Enable**. Alternatively, run: ```bash aws cost-optimization-hub update-enrollment-status \ --status Active \ --include-member-accounts \ --region us-east-1 ``` - The **`AWSServiceRoleForBCMDataExports`** service-linked role exists in the management account. Navigate to **Billing and Cost Management** > **Data Exports** > **Create** to provision the role automatically, or run: ```bash aws iam create-service-linked-role \ --aws-service-name bcm-data-exports.amazonaws.com ``` ### Template deployment - The template **must** be deployed in the **us-east-1** region. AWS Data Exports (`bcm-data-exports`) operates only in us-east-1, so the bucket and roles the exports depend on must be created there. - Review all [template parameters](/docs/cbp/reference/aws-account-config/cloudformation-template-parameters/) carefully before deploying. - Download the [CloudFormation template](https://downloads.cloudbolt.io/platform/onboarding/cb-onboarding-stackset.yaml). ### Existing S3 bucket - By default, the template creates an S3 bucket, but you can bring your own by setting `CreateS3Bucket=false`. If using an existing S3 bucket, either remove the bucket policy or also set `CreateS3BucketPolicy=false` and [ensure the bucket has the appropriate policy](/docs/cbp/reference/aws-account-config/cloudformation-template-parameters/#s3-bucket-policy). ## Best practices - Use the `ResourceNamePrefix` in multi-environment deployments to identify resources and avoid conflicts. - For multi-account deployments, monitor the StackSet operation status to verify successful deployment. - Always deploy in us-east-1 to ensure report resource availability. ## Deployment decisions Before deploying the template, decide the following: ### Deployment scope The template supports deployment to: - **OrganizationWide (default):** All accounts under a root OU. Requires `TargetRootOUId`. - **SpecificOU:** One or more OUs. Requires comma-separated `TargetOUIds`. - **ManagementAccountOnly:** The management account only. No StackSet is created. Use for single-account environments, or as Pass 1 of the [MemberAccountOnly two-pass flow](#deploy-without-stacksets) when CloudFormation StackSets are not enabled. - **MemberAccountOnly:** Deploy in a member account to create only the action role, OIDC trust, and least-privilege IAM policies. No S3 bucket or FOCUS role is created. Use as Pass 2 of the two-pass flow. If your organization can't use CloudFormation, you can create the management-account resources with a CloudBolt-provided Terraform module. This is a beta option, enabled on request, and equivalent to `ManagementAccountOnly`. Refer to [AWS onboarding with Terraform](/docs/cbp/reference/aws-account-config/terraform-onboarding/). ### Tenant configuration The `TenantHostedRegion` parameter selects which CloudBolt SaaS OIDC provider the cross-account roles trust. Pick the value matching where your CloudBolt tenant is hosted. | Value | OIDC provider | Use case | | --- | --- | --- | | US (default) | `auth.cloudbolt.io` | CloudBolt tenant hosted in the US | | EU | `auth.eu.cloudbolt.io` | CloudBolt tenant hosted in the EU | ### Cost reports CloudBolt creates the following four data exports once the connection is established. The template does not create them, and there is no parameter to select report types. - FOCUS 1.0 - FOCUS 1.2 Hourly - FOCUS 1.2 Daily - Cost Optimization Recommendations ### Initial and subsequent deployments - **First deployment:** Leave `CloudBoltStackExist=false` (default). This creates all resources, including management account IAM roles. - **Updating the same stack:** Leave `CloudBoltStackExist=false` (default). CloudFormation tracks the IAM resources as part of the stack and updates them in place. - **Deploying a second stack in the same account:** Set `CloudBoltStackExist=true`. This is needed only when an existing stack owns the account IAM resources, and you are deploying an additional stack. ## Deploy without StackSets If your AWS Organization does not have CloudFormation StackSets enabled, you can deploy the template in two passes to achieve the desired state. ### Overview | Pass | Account | TargetDeploymentType | Creates | | --- | --- | --- | --- | | 1 | Management | `ManagementAccountOnly` | S3 bucket, IAM roles, OIDC trust, and least-privilege IAM policies. | | 2 | Member | `MemberAccountOnly` | Action role, OIDC trust, and least-privilege IAM policies. | ### Pass 1: Management account Deploy the template in the management account with `TargetDeploymentType=ManagementAccountOnly`. Configure all other parameters (S3 bucket, tenant region, etc.) as you would for a standard deployment. ### Pass 2: Each member account Deploy the template in each member account with `TargetDeploymentType=MemberAccountOnly`. If you changed `TenantHostedRegion` or `ResourceNamePrefix` from their defaults in Pass 1, set the same values here. All S3 and deployment scope parameters are ignored in this mode. ## Deploy the template 1. Log in to your **AWS management account**. 1. Go to **CloudFormation**. 1. Select **Create stack**. 1. Select **Upload a template file**, then choose the downloaded [template file](https://downloads.cloudbolt.io/platform/onboarding/cb-onboarding-stackset.yaml), then select **Next**. 1. In the **Stack name** field, provide a name for the stack. 1. Under **Parameters**, specify your environment parameters, then select **Next**. - Review the [deployment decisions](#deployment-decisions) and [template parameters](/docs/cbp/reference/aws-account-config/cloudformation-template-parameters/) to determine your required configuration. 1. On the **Configure stack options** page, acknowledge the required capabilities, then select **Next**. 1. On the **Review** page, select **Submit**. ## Created resources A successful deployment creates the following resources: - IAM roles `CloudBoltFocusCrossAccountRole` and `CloudBoltActionsCrossAccountRole`, enabling the CloudBolt Platform to retrieve cost reports. - The stack itself does not create the FOCUS 1.0, FOCUS 1.2 Hourly, FOCUS 1.2 Daily, and Cost Optimization Recommendations data exports. CloudBolt creates these once the AWS connection is established: immediately after deployment from CloudBolt, or when you complete the connection after deploying directly in the AWS Console. - If you require historical data, refer to [AWS's guidance on backfilling data exports](https://docs.aws.amazon.com/guidance/latest/cloud-intelligence-dashboards/data-exports.html#backfill-data-export) up to 36 months. - S3 bucket for report storage, if `CreateS3Bucket=true` (default). - CloudBolt automatically reads the S3 bucket name, resource prefix, and stack name from the deployed stack. You do not need to copy them. Adding an AWS connection requires only your AWS account ID. ## Update an existing deployment The CloudFormation template may be updated to support new features. To update an existing deployment, run `update-stack`: ```bash aws cloudformation update-stack \ --stack-name cloudbolt-onboarding \ --template-body file://cb-onboarding-stackset.yaml \ --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \ --parameters \ ParameterKey=S3BucketName,UsePreviousValue=true \ ParameterKey=TargetDeploymentType,UsePreviousValue=true \ ParameterKey=TargetRootOUId,UsePreviousValue=true ``` Set the following parameters to prevent resource conflicts when updating: | Parameter | Value | Reason | | --- | --- | --- | | `CreateS3Bucket` | false | Skip S3 bucket creation (bucket already exists) | | `CreateS3BucketPolicy` | false | Skip S3 bucket policy creation (policy already exists) | ## Troubleshooting | Error | Solution | | --- | --- | | The `AWSServiceRoleForBCMDataExports` service-linked role is missing | CloudBolt reports this on the connection card when it verifies the account. Create the service-linked role as described in the [service requirements](#service-requirements), then select **Re-Sync** on the connection card. | | Cost Optimization Hub is not enabled for this account | CloudBolt reports this on the connection card when it verifies the account. Complete the Cost Optimization Hub opt-in for the organization, including member accounts, as described in the [service requirements](#service-requirements), then select **Re-Sync** on the connection card. | | An export couldn't be created because the table already has 2 of 2 exports | AWS allows two data exports per table. The message names the exports holding the slots. Delete one you no longer need, or, if the message reports an incompatible format, update that export so **Format** and **Compression** are both **PARQUET**. Then select **Re-Sync** on the connection card. | | `EntityAlreadyExists` on `AWS::IAM::OIDCProvider` | An OIDC provider with the same URL already exists in IAM (created manually or by a previous deployment). Delete the existing provider and re-run:
`aws iam delete-open-id-connect-provider --open-id-connect-provider-arn ` | | `EntityAlreadyExists` on an IAM role during stack update | This occurs when deploying a second CloudBolt stack in an account where an existing stack owns the IAM resources. Set `CloudBoltStackExist=true` to skip re-creating them. | | S3 bucket policy creation failed | If using an existing bucket with the appropriate policy already configured, set `CreateS3BucketPolicy=false` to skip policy creation. | | Resource naming conflicts | Use the `ResourceNamePrefix` parameter to avoid resource conflicts, particularly when deploying multiple stacks. | | Export creation or export runs fail due to missing permissions | Ensure your S3 bucket has the appropriate policy, or set `CreateS3BucketPolicy=true` to allow the template to create the policy. | ## Related topics - [CloudFormation template parameters](/docs/cbp/reference/aws-account-config/cloudformation-template-parameters/) - [CloudFormation template outputs](/docs/cbp/reference/aws-account-config/cloudformation-template-outputs/) - [IAM roles](/docs/cbp/reference/aws-account-config/iam-roles/) - [Cost and security considerations](/docs/cbp/reference/aws-account-config/cost-security-considerations/) - [AWS onboarding with Terraform](/docs/cbp/reference/aws-account-config/terraform-onboarding/)