AWS guidance documentation change
Summary
Updated documentation for granular data collection controls including wildcard support, region restrictions, policy evaluation logic, troubleshooting tips, and best practices.
Security assessment
The changes enhance documentation for data scoping features but contain no references to vulnerabilities, security patches, or security incidents. Updates focus on operational controls without security-specific context.
Diff
diff --git a/guidance/latest/cloud-intelligence-dashboards/granular-data-collection-control.md b/guidance/latest/cloud-intelligence-dashboards/granular-data-collection-control.md index 9c36efae0..a610accba 100644 --- a//guidance/latest/cloud-intelligence-dashboards/granular-data-collection-control.md +++ b//guidance/latest/cloud-intelligence-dashboards/granular-data-collection-control.md @@ -5 +5 @@ -Last UpdatedAuthorControlling Data Collection ScopeOverviewInclusion and Exclusion ListsGranular Execution ControlConfiguration SummaryTroubleshooting +Last UpdatedAuthorControlling Data Collection ScopeOverviewInclusion and Exclusion ListsGranular Execution ControlTroubleshooting @@ -22 +22,5 @@ March 2026 -This guide explains how to customize which AWS accounts and regions the Cloud Intelligence Dashboards Data Collection framework processes. You can limit data collection to specific accounts, exclude certain accounts, or apply granular rules to accounts and OUs per module and region. +This guide explains how to customize which AWS accounts and regions the Cloud Intelligence Dashboards Data Collection framework processes. You can limit data collection to specific accounts, exclude certain accounts, or apply granular rules to accounts and OUs per module and region. No changes to the deployed CloudFormation stack are required. You only need to supply configuration files, per the description below and The Account Collector Lambda automatically detects and applies them. + +###### Note + +You must be using the Data Collection framework version 3.14.4+ to enable the Granular Control capability. See [Update](./data-collection-update.html) for instructions on updating your deployment. @@ -30 +34 @@ Method | Use Case | Scope -Inclusion List | Collect data from only specific accounts | All modules +Inclusion List | Collect data only from specific accounts | All modules @@ -107 +111 @@ Field | Description | Required -`module` | The module name (e.g., `budgets`, `inventory`, `health-events`) | Yes +`module` | The module name (e.g., `budgets`, `inventory`, `health-events`). Leave blank or use `*` to apply the rule to all modules. | Yes @@ -110 +114 @@ Field | Description | Required -`regions` | Colon-separated list of regions (e.g., `us-east-1:ap-southeast-2`). Leave empty for all regions. | No +`regions` | Colon-separated list of regions (e.g., `us-east-1:ap-southeast-2`). Leave blank or use `*` for all regions in scope. | No @@ -114,0 +119,7 @@ Field | Description | Required +**Allow all modules at the root OU level, then deny all regions to one accounts but only us-east-1 to another:** + + + *,A,r-xxxx,, + *,D,345678901234,* + *,D,456789012345,us-east-1 + @@ -118 +129 @@ Field | Description | Required - budgets,D,123456789012,, + budgets,D,123456789012,* @@ -120 +131 @@ Field | Description | Required -**Deny a specific account for inventory in us-east-1 only:** +**Deny a specific account for the ec2 inventory in us-east-1 only:** @@ -123 +134 @@ Field | Description | Required - inventory,D,234567890123,us-east-1, + inventory-ec2-instances,D,234567890123,us-east-1 @@ -127 +138 @@ Field | Description | Required -For inventory the current capability is to manage all inventory sub-modules together. +The Inventory module has several sub-modules and you must define each one you with to control @@ -132 +143 @@ For inventory the current capability is to manage all inventory sub-modules toge - backup,A,ou-abc1-12345678,, + backup,A,ou-abc1-12345678,* @@ -137,2 +148,2 @@ For inventory the current capability is to manage all inventory sub-modules toge - backup,A,ou-abc1-12345678,, - backup,D,345678901234,, + backup,A,ou-abc1-12345678,* + backup,D,345678901234,* @@ -140 +151 @@ For inventory the current capability is to manage all inventory sub-modules toge -**Deny multiple regions for a specific account:** +**Deny multiple regions for a specific account for all modules:** @@ -143 +154 @@ For inventory the current capability is to manage all inventory sub-modules toge - compute-optimizer,D,456789012345,us-east-1:eu-west-1, + *,D,456789012345,us-east-1:eu-west-1 @@ -145 +156 @@ For inventory the current capability is to manage all inventory sub-modules toge -### Policy Evaluation +**Deny specifc regions for all accounts for all modules:** @@ -147 +157,0 @@ For inventory the current capability is to manage all inventory sub-modules toge -The granular configuration follows IAM-style policy evaluation: @@ -149 +159 @@ The granular configuration follows IAM-style policy evaluation: - 1. **Deny always wins** — If any deny rule matches an account, that account is excluded regardless of any allow rules. + *,D,*,us-east-1:eu-west-1 @@ -151 +161 @@ The granular configuration follows IAM-style policy evaluation: - 2. **OU expansion** — When you specify an OU ID, the rule applies to all accounts within that OU and its child OUs. +**Deny all regions for all accounts for all modules. This rule would produce an error because nothing would be allowed:** @@ -153 +162,0 @@ The granular configuration follows IAM-style policy evaluation: - 3. **Region filtering** — When regions are specified, the rule applies only to those regions. An empty regions field means all regions. @@ -154,0 +164 @@ The granular configuration follows IAM-style policy evaluation: + *,D,*,* @@ -155,0 +166 @@ The granular configuration follows IAM-style policy evaluation: +### Wildcards and Blank Fields @@ -156,0 +168 @@ The granular configuration follows IAM-style policy evaluation: +The `module` and `regions` fields support a wildcard (`*`) or can be left blank: @@ -158 +170 @@ The granular configuration follows IAM-style policy evaluation: -This allows you to create broad allow rules (such as allowing an entire OU) and then carve out specific exceptions with deny rules. + * **Module field:** Leave blank or use `*` to apply the rule to all modules. @@ -160 +172 @@ This allows you to create broad allow rules (such as allowing an entire OU) and -### Precedence + * **Regions field:** Leave blank or use `*` to apply the rule to all regions in your deployment scope. @@ -162 +173,0 @@ This allows you to create broad allow rules (such as allowing an entire OU) and -When a granular execution config file exists and contains rules for a module: @@ -164 +174,0 @@ When a granular execution config file exists and contains rules for a module: - 1. The granular config is used for that module. @@ -166 +175,0 @@ When a granular execution config file exists and contains rules for a module: - 2. Any inclusion and exclusion lists (as described before the granular operation) are ignored for that module. @@ -167,0 +177 @@ When a granular execution config file exists and contains rules for a module: +###### Important @@ -168,0 +179 @@ When a granular execution config file exists and contains rules for a module: +The wildcard `*` does not perform pattern matching. It is only valid as a standalone value in a field. Do not combine it with other characters (e.g., `budget*` is not valid). Use only `*` by itself or leave the field empty. @@ -169,0 +181,15 @@ When a granular execution config file exists and contains rules for a module: +### Region Scope and Restrictions + +The regional restriction in the granular policy works in conjunction with the top-level **Regions in Scope** parameter defined in the [Data Collection Stack deployment](./data-collection-deployment.html). The granular policy can only restrict regions that are already included in that top-level scope — it cannot add regions that are not defined there. + +For example, if your Data Collection Stack is deployed with `us-east-1:us-west-2:eu-west-1` as the regions in scope, a granular policy can deny `eu-west-1` for a specific module, but it cannot enable `ap-southeast-1` if that region is not in the top-level scope. + +Ensure that the **Regions in Scope** parameter in your Data Collection Stack includes all regions you may want to collect from. Then use the granular policy to restrict specific modules or accounts to a subset of those regions as needed. + +### Best Practices + +If you wish to deny one or a few specific accounts across all modules while allowing everything else, a recommended approach is: + + 1. Define an allow rule at the root OU level for all modules and all regions. + + 2. Add deny rules for the specific accounts you want to exclude. @@ -171 +196,0 @@ When a granular execution config file exists and contains rules for a module: -If the granular config file exists but has no rules for a specific module, that module falls back to the standard inclusion/exclusion list behavior. @@ -173 +197,0 @@ If the granular config file exists but has no rules for a specific module, that -## Configuration Summary @@ -175,5 +198,0 @@ If the granular config file exists but has no rules for a specific module, that -File | Path | Purpose ----|---|--- -Inclusion list | `account-list/account-list.csv` or `.json` | Collect only these accounts -Exclusion list | `account-list/excluded-linked-account-list.csv` | Exclude these accounts from Organization -Granular config | `account-list/granular-execution-config.csv` | Per-module allow/deny rules @@ -181 +200 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al -### Quick Start +For example: @@ -183 +201,0 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al - 1. Navigate to your CID data S3 bucket (typically `cid-data-<account-id>`). @@ -185 +203,3 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al - 2. Create the `account-list/` folder if it doesn’t exist. + *,A,r-xxxx + *,D,345678901234 + *,D,456789012345 @@ -187 +207 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al - 3. Upload the appropriate configuration file based on your requirements. +This ensures all accounts in the Organization are allowed by default, and you can then pare down the scope by adding targeted deny rules. @@ -189 +209,3 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al - 4. The next scheduled data collection run will use your configuration. +### Policy Evaluation + +The granular configuration follows IAM-style policy evaluation: @@ -190,0 +213 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al + 1. **Deny always wins** — If any deny rule matches an account, that account is excluded regardless of any allow rules. @@ -191,0 +215,3 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al + 2. **OU expansion** — When you specify an OU ID, the rule applies to all accounts within that OU and its child OUs. + + 3. **Region filtering** — When regions are specified, the rule applies only to those regions. An empty regions field means all regions. @@ -194 +220,16 @@ Granular config | `account-list/granular-execution-config.csv` | Per-module al -No changes to the deployed CloudFormation stack are required. The account collector Lambda automatically detects and applies these configuration files. + + +This allows you to create broad allow rules (such as allowing an entire OU) and then carve out specific exceptions with deny rules. + +### Precedence + +When a granular execution config file exists and contains rules for a module: + + 1. The granular config is used for that module. + + 2. Any inclusion and exclusion lists (as described before the granular operation) are ignored for that module. + + + + +If the granular config file exists but has no rules for a specific module, that module falls back to the standard inclusion/exclusion list behavior. @@ -204 +245,5 @@ No changes to the deployed CloudFormation stack are required. The account collec - * **Unexpected behavior:** Review CloudWatch Logs for the account-collector Lambda to see which configuration files were detected and how rules were applied. + * **Region restrictions not taking effect:** Verify that the regions you are restricting are included in the top-level **Regions in Scope** parameter of the Data Collection Stack. The granular policy cannot add regions outside of that scope. + + * **Wildcard not working as expected:** The ` ****` wildcard must be the only character in the field. It does not support pattern matching (e.g., `budget` is not valid). + + * **Unexpected behavior:** Review CloudWatch Logs for the Account Collector Lambda to see which configuration files were detected and how rules were applied. Set the Lambda’s logging level to `DEBUG` for detailed tracing of policy parsing, rule evaluation, and the final computed ruleset.