AWS guidance documentation change
Summary
Updated documentation for adding organizational taxonomy to AWS dashboards. Changes include: added CUR2 features (Account Tags, IAM Principal Tags, User Attributes), enhanced account mapping using cid-cmd tool, expanded resource-level cost allocation methods, updated prerequisites for data exports, restructured FAQ section with new use cases, and improved performance guidance.
Security assessment
The changes focus on cost allocation methodologies and dashboard taxonomy configuration. While new IAM Principal Tags and User Attributes features are documented, these are cost attribution mechanisms rather than security features. No vulnerabilities, security incidents, or security controls are addressed. Changes are operational improvements for cost visibility.
Diff
diff --git a/guidance/latest/cloud-intelligence-dashboards/add-org-taxonomy.md b/guidance/latest/cloud-intelligence-dashboards/add-org-taxonomy.md index bb258b02a..59b634804 100644 --- a//guidance/latest/cloud-intelligence-dashboards/add-org-taxonomy.md +++ b//guidance/latest/cloud-intelligence-dashboards/add-org-taxonomy.md @@ -5 +5 @@ -IntroductionArchitectural FoundationsAccount Level Cost AllocationResource Level Cost Allocation (Tags and Cost Categories)Adding Taxonomy to the DashboardsFAQDo all dashboards support taxonomy?I need to append a taxonomy from AWS Organization TagsI just need to add a taxonomy based on AWS Cost Allocation TagCan I change taxonomy?Can CloudFormation Template manage this? +IntroductionArchitectural FoundationsAccount Level Cost AllocationResource Level Cost Allocation (Tags and Cost Categories)Adding Taxonomy to the DashboardsFAQ @@ -34,0 +35,6 @@ Resource allocation in AWS typically follows two primary architectural patterns: + 1. [Account Tags as Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/account-tags-cost-allocation.html) (available in CUR2) + + 2. [IAM Principal Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/iam-principal-cost-allocation.html) (available in CUR2) + + 3. [User Attributes](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/user-attributes-cost-allocation.html) (available in CUR2) + @@ -54,0 +61,3 @@ AWS Cost Allocation Tags | Resource Level | CUR | AWS Data Exports | +IAM Principal Tags | Resource Level | CUR2 `tags` column | AWS Data Exports with Tags column | Tags attached to IAM principals (roles/users) making API calls. Useful for attributing costs to specific teams or applications based on who performed the action. +User Attributes | Resource Level | CUR2 `tags` column | AWS Data Exports with Tags column | Workforce user attributes (cost center, division, department) from IAM Identity Center. Supported for Amazon Q Business, Amazon Q Developer, and Amazon Quick. +IAM Principal (ARN) | Resource Level | CUR2 `line_item_iam_principal` column | AWS Data Exports | The full IAM principal ARN that made the API call. Currently supported for Amazon Bedrock. @@ -80 +89 @@ The main benefit of Account Tags as Cost Allocation Tags is simplicity: all requ - 3. Upgrade your data export stack on payer account(s) to `v0.9.0` or later if you are running an older version + 3. Upgrade your [data export stack](./data-exports.html) on payer account(s) to `v0.9.0` or later if you are running an older version @@ -91 +100 @@ The main benefit of Account Tags as Cost Allocation Tags is simplicity: all requ -**When to Use Data Collection Method Instead:** +**When to Use CID Data Collection Method for organizational data Instead:** @@ -104 +113 @@ While Account Tags as Cost Allocation Tags in CUR2 are recommended for simple ac -### Using Static Account Map View +### Using Account Map View @@ -106 +115 @@ While Account Tags as Cost Allocation Tags in CUR2 are recommended for simple ac -To implement account level mapping CID provides a special View in Amazon Athena called `account_map`. This Athena view is specifically designed to be customizable by customers. You can modify this Athena view, leveraging various options: +To implement account level mapping, CID uses a special View in Amazon Athena called `account_map`. This Athena view is specifically designed to be customizable by customers. It can be generated using `cid-cmd map` (recommended) or created manually using any of the following data sources: @@ -119 +128 @@ To implement account level mapping CID provides a special View in Amazon Athena -### Example of default account map based on CUR 2.0 +The following sections describe different ways to use the `account_map` view to build dynamic or static account mapping to organizational taxonomy dimensions. @@ -120,0 +130 @@ To implement account level mapping CID provides a special View in Amazon Athena +### Account map based on AWS Organizations data (Recommended) @@ -122,10 +132 @@ To implement account level mapping CID provides a special View in Amazon Athena - CREATE OR REPLACE VIEW account_map AS - SELECT DISTINCT - line_item_usage_account_id account_id, - MAX_BY(line_item_usage_account_name, line_item_usage_start_date) account_name, - MAX_BY(bill_payer_account_id, line_item_usage_start_date) parent_account_id, - MAX_BY(bill_payer_account_name, line_item_usage_start_date) parent_account_name - FROM - "${cur_database}"."${cur_table_name}" - GROUP BY - line_item_usage_account_id +The `cid-cmd map` command provides an interactive workflow for creating enriched `account_map` views with custom taxonomy dimensions. It supports multiple data sources and can be used with or without an `organization_data` table in Athena. @@ -133 +134 @@ To implement account level mapping CID provides a special View in Amazon Athena -### Advanced example of account map based on AWS Organizations data (Recommended) +The `cid-cmd map` command automatically generates an `account_map` Athena view with your organizational taxonomy columns. It supports three data source modes: @@ -135 +136,5 @@ To implement account level mapping CID provides a special View in Amazon Athena -This example leverages the AWS Organization Data collected by [CID Data Collection](./data-collection.html) and allows you adding Account and OU level tags into account_map. Please note that you do not need to use all the fields from this example, you can adjust it to your specific business and organizational requirements. +Mode | Description +---|--- +**organization_data table** | Uses AWS Organizations data collected via [CID Data Collection](./data-collection.html). Supports OU hierarchy levels, hierarchical tags, and account name splitting. +**CSV file only** | Creates the account map entirely from a CSV file. No Athena source table required. +**Both** | Combines organization_data as the base account list with a CSV file for additional taxonomy columns (e.g. from an external CMDB). @@ -136,0 +142 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti +**Prerequisites:** @@ -138,5 +144,26 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti - CREATE OR REPLACE VIEW "account_map" AS - SELECT DISTINCT - -- Mandatory - id account_id - , Name account_name + * For organization_data mode: [CID Data Collection](./data-collection.html) must be deployed + + * For CSV mode: A CSV file with at minimum an `account_id` column + + * `cid-cmd` version 4.4.14 or later + + + + +**Basic usage:** + + + # Interactive mode — prompts for data source selection + cid-cmd map + + # (Optional) With a CSV file for additional static mapping taxonomy + cid-cmd map --file accounts_mapping.csv + +**Available taxonomy dimension sources (organization_data mode):** + +Source | Description +---|--- +**Tags from source table** | Extract values from OU-level or Account-level tags in AWS Organizations (hierarchical inheritance supported) +**OU hierarchy level** | Use the name of the OU at a specific level (e.g., level 2 = Business Unit) +**Additional file (CSV)** | Join columns from a CSV file by account_id +**Split account name** | Extract a portion of the account name using a delimiter (e.g., `prod-team1-app` → `team1`) @@ -144,4 +171 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti - -- Optional - , email account_email_id - , ManagementAccountId parent_account_id - , Parent "o_u" -- The Name of the lowest level OU of the Account +**Example workflow:** @@ -149,4 +172,0 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti - -- Part of Account Name. - -- Account names are sometimes structured in a way that allows us to use part of the name as a taxonomy identifier - , TRY(split_part(Name, '-', 1)) "account_prefix" - , TRY(split_part(Name, '-', 2)) "account_suffix" @@ -154,2 +174,25 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti - -- A simple mapping of Management Account Ids to user-friendly names - , CASE ManagementAccountId + $ cid-cmd map --file accounts_mapping.csv + + ? Select account data source for taxonomy: + ❯ organization_data table (collected with CID Data Collection) + CSV file only + Both (organization_data table + CSV file for additional taxonomy) + + ? Select data sources for taxonomy dimensions: + ☑ Tags from source table + ☑ OU hierarchy level + ☑ Additional file (CSV) + ☐ Split account name column + +The command will guide you through selecting specific tags, OU levels, and file columns to include as taxonomy dimensions, then preview the resulting SQL before creating the view. + + + CREATE OR REPLACE VIEW "cid_cur"."account_map" AS + SELECT + -- Mandatory + id AS account_id + , name AS account_name + , managementaccountid AS parent_account_id + + -- Friendly name for management account(s) + , CASE managementaccountid @@ -158,18 +201,16 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti - ELSE ManagementAccountId - END parent_account_name - - -- Full path separated with '>' - , HierarchyPath as o_u_hierarchy - - -- Levels of OU hierarchy - , TRY(hierarchy[1].name) o_u_level1 -- root - , TRY(hierarchy[2].name) o_u_level2 - , TRY(hierarchy[3].name) o_u_level3 - , TRY(hierarchy[4].name) o_u_level4 - , TRY(hierarchy[5].name) o_u_level5 - - -- Hierarchical Tags - -- You can set on OU level and override on lower OU or set Account level Tags - , TRY(FILTER(HierarchyTags, x -> x.key = 'MyEnterprise')[1].value) as ou_tag_enterprise - , TRY(FILTER(HierarchyTags, x -> x.key = 'MyBusinessLine')[1].value) as ou_tag_business_line - , TRY(FILTER(HierarchyTags, x -> x.key = 'MyBusinessUnit')[1].value) as ou_tag_business_unit + ELSE managementaccountid + END AS parent_account_name + + -- OU hierarchy levels + , TRY(hierarchy[1].name) AS o_u_level1 + , TRY(hierarchy[2].name) AS business_unit + + -- Hierarchical Tags (set on OU level, override on lower OU or Account level) + , element_at(filter(hierarchytags, x - x.key = 'environment'), 1).value AS environment + , element_at(filter(hierarchytags, x - x.key = 'cost_center'), 1).value AS cost_center + + -- Part of Account Name (when naming convention allows) + , TRY(split_part(name, '-', 1)) AS account_prefix + + -- Additional columns from CSV file (joined by account_id) + , file.team AS team @@ -177 +218,6 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti - "optimization_data"."organization_data" + "optimization_data"."organization_data" org + LEFT JOIN "cid_cur"."account_map_file_source" file ON org.id = file.account_id + +You can also create a similar view manually if you want to tailor it to your specific needs not supported by `cid-cmd map` capabilities. Please note that you do not need to use all the fields from this example — adjust it to your specific business and organizational requirements. + +### Static Account Map from CSV @@ -179 +225 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti -### Example of static Account Map +As an alternative to the dynamic account map based on AWS Organizations data, you can create a static account map from a CSV file. This approach is useful when you have custom mapping maintained in a CMDB or spreadsheet and you want to bring it to account map. @@ -181 +227,7 @@ This example leverages the AWS Organization Data collected by [CID Data Collecti -Static account map is useful when you have custom mapping maintained in the CMDB outside of account names and you want to bring it to account map. +**Using`cid-cmd map` with CSV file:** + + + cid-cmd map --file my_accounts.csv + # Select "CSV file only" when prompted + +The CSV file should contain at minimum an `account_id` column. All other columns can be selected as taxonomy dimensions during the interactive workflow. @@ -200 +252 @@ Static account map is useful when you have custom mapping maintained in the CMDB -You can also leverage `cid-cmd csv2view` command that accepts a csv file and generates the code of view as above. +## Resource Level Cost Allocation (Tags and Cost Categories) @@ -202 +254 @@ You can also leverage `cid-cmd csv2view` command that accepts a csv file and gen -### How to update Account Map +Resource-level cost allocation uses tags and cost categories embedded in the Cost and Usage Report (CUR) to attribute costs to specific resources, teams, or applications. The `cid-cmd` tool automatically discovers available tags and allows you to select which ones to include in your dashboards. @@ -204 +256 @@ You can also leverage `cid-cmd csv2view` command that accepts a csv file and gen - 1. Navigate to Amazon Athena and the cur database (default: `cid_cur`). +### Cost Allocation Tags @@ -206 +258 @@ You can also leverage `cid-cmd csv2view` command that accepts a csv file and gen - 2. Locate the `account_map` and click on the vertical ellipses (`⋮`) next to the view and select _Show/edit query_ from the context menu. +Cost Allocation Tags are the most common resource-level taxonomy source. They come from the `resource_tags` column in CUR and include both user-defined tags and AWS-generated tags. @@ -208 +260 @@ You can also leverage `cid-cmd csv2view` command that accepts a csv file and gen - 3. First, make a copy of the view as backup, naming the new view something like _account_map_original_. +### IAM Principal Tags, IAM Principal ARN, and User Attributes