AWS controltower documentation change
Summary
Updated documentation to emphasize global ARNs over regional ARNs for AWS Control Tower controls. Added sections on understanding control ARNs, finding global ARNs, migrating from regional ARNs, and finding OU identifiers. Provided ARN formats, benefits of global ARNs, and migration guidance.
Security assessment
The changes focus on clarifying ARN formats and migration paths for control identifiers. No evidence of a security vulnerability, incident, or weakness is addressed. The updates improve operational documentation but don't reference security fixes or vulnerabilities.
Diff
diff --git a/controltower/latest/controlreference/control-identifiers.md b/controltower/latest/controlreference/control-identifiers.md index 2a2e61c0f..299f7e9af 100644 --- a//controltower/latest/controlreference/control-identifiers.md +++ b//controltower/latest/controlreference/control-identifiers.md @@ -5 +5 @@ -Regional and global identifiers +Understand control ARNsFind global ARNsMigrate from regional ARNs to global ARNsFind identifiers for OUs @@ -9 +9 @@ Regional and global identifiers -Each control in AWS Control Tower has unique identifiers for use with the control APIs. You can call a control API using a global identifier or a Region-based identifier. +Each control in AWS Control Tower has unique Amazon Resource Names (ARNs) for use with the [AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/APIReference/Welcome.html) and [Control Catalog](https://docs.aws.amazon.com/controlcatalog/latest/APIReference/Welcome.html) APIs. You can call an API using a global ARN or a regional ARN. @@ -11 +11 @@ Each control in AWS Control Tower has unique identifiers for use with the contro - * The AWS Control Tower identifer is Region-based and has been available longer. + * We recommend that you use the global ARNs for all use cases. @@ -13 +13 @@ Each control in AWS Control Tower has unique identifiers for use with the contro - * We recommend that you use the global identifiers for most use cases in AWS Control Tower. + * The regional ARNs have been available longer but are considered as legacy ARNs. @@ -18 +18 @@ Each control in AWS Control Tower has unique identifiers for use with the contro -## Regional and global identifiers +## Understand control ARNs @@ -20 +20 @@ Each control in AWS Control Tower has unique identifiers for use with the contro -A _global identifier_ (ARN) is available for all controls that are part of AWS Control Catalog. This identifier is independent of any AWS Region. All AWS Control Tower controls are included in AWS Control Catalog, and each AWS Control Tower control has a global identifier. +AWS Control Tower supports two types of control ARNs. @@ -22 +22 @@ A _global identifier_ (ARN) is available for all controls that are part of AWS C -Also, each AWS Control Tower control has a Regional identifier (ARN), which is a unique identifier for each Region in which AWS Control Tower operates. The identifier for each control is shown in the [Tables of control metadata](https://docs.aws.amazon.com//controltower/latest/userguide/control-metadata-tables.html). +**Global ARNs (recommended)** @@ -24 +24 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a - * _The Regional identifier is not shown in the AWS Control Tower console, only in documentation._ +A global ARN is available for all controls that are part of [Control Catalog](https://docs.aws.amazon.com/controlcatalog/latest/userguide/what-is-controlcatalog.html). Global ARNs use the following format. @@ -26 +25,0 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a - * The global identifier is shown in the **API controlIdentifier** field, on the **Control details** page in the AWS Control Tower console. For a full list of global identifiers, see [All global identifiers for AWS Control Tower controls](./all-global-identifiers.html). @@ -27,0 +27 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a + arn:{PARTITION}:controlcatalog:::control/{GLOBAL_CONTROL_ID} @@ -28,0 +29 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a +For example, `arn:aws:controlcatalog:::control/k4izcjxhukijhajp6ks5mjxk`. Global ARNs are independent of any AWS Region. We recommend that you use global ARNs for all use cases. @@ -29,0 +31 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a +**Regional ARNs (legacy)** @@ -31 +33 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a -###### Note +Older Control Catalog controls also have regional ARNs. A regional ARN is a unique identifier for each Region in which AWS Control Tower operates. Regional ARNs use the following format. @@ -33 +34,0 @@ Also, each AWS Control Tower control has a Regional identifier (ARN), which is a -The **API controlIdentifier** is distinct from the **ControlID** field, which is a classification system for controls. @@ -35 +36 @@ The **API controlIdentifier** is distinct from the **ControlID** field, which is -### View the Regional control identifiers for all controls + arn:{PARTITION}:controltower:{REGION}::control/{REGIONAL_CONTROL_ID} @@ -37 +38 @@ The **API controlIdentifier** is distinct from the **ControlID** field, which is -To view the Regional `controlIdentifier` ARN for each control and Region, and other metadata, see [Tables of control metadata](https://docs.aws.amazon.com//controltower/latest/userguide/control-metadata-tables.html). The tables also include the identifiers for Security Hub CSPM controls that are part of the [**AWS Security Hub CSPM Service-Managed Standard: AWS Control Tower**](https://docs.aws.amazon.com//controltower/latest/userguide/security-hub-controls.html). +For example, `arn:aws:controltower:us-east-1::control/YEHYWYAUIQHZ`. Regional ARNs for the same control can be different in different Regions. @@ -39 +40 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot -###### How to change from AWS Control Tower control ARNs (Regional) to Control Catalog control ARNs (global) +**Benefits of using global ARNs** @@ -41 +42 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot - 1. Deactivate the enabled control that has the ARN you wish to change. +Global ARNs provide several advantages over Regional ARNs. @@ -43 +44 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot - 2. Re-enable the control and specify the Control Catalog ARN, which will create a new AWS resource that has the Control Catalog ARN. + * **Region independence** – The same ARN works across all AWS Regions within the same partition. @@ -44,0 +46 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot + * **Simplified management** – You don't need to maintain Region-specific identifiers. This simplifies multi-Region management and deployments. @@ -45,0 +48 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot + * **Future-proof** – New controls are assigned global ARNs only. @@ -48 +50,0 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot -###### Important @@ -50 +51,0 @@ To view the Regional `controlIdentifier` ARN for each control and Region, and ot -When you disable the control, your environment may experience a gap in governance until the new control resource is enabled. @@ -52 +53 @@ When you disable the control, your environment may experience a gap in governanc -### View global control identifiers in the console +## Find global ARNs @@ -54 +55 @@ When you disable the control, your environment may experience a gap in governanc -To view the global control identifiers and other details about AWS Control Tower controls in the console, navigate to the **Control details** page in the AWS Control Tower console. You can find the identifier in the **API controlIdentifier** field. +You can retrieve global ARNs for Control Catalog controls in the following ways. @@ -56 +57 @@ To view the global control identifiers and other details about AWS Control Tower -###### Example forms of identifiers +**AWS Control Tower console** @@ -58 +59 @@ To view the global control identifiers and other details about AWS Control Tower -Here are examples of identifiers you may see. +To view the global ARNs and other details about Control Catalog controls in the console, navigate to the **Control details** page in the AWS Control Tower console. You can find the identifier in the **API identifier** field. @@ -60 +61 @@ Here are examples of identifiers you may see. - * Security Hub example **API controlIdentifier** (regional): `arn:aws:controltower:us-east-1::control/OOTDCUSIKIZZ` +**ListControls API** @@ -62 +63 @@ Here are examples of identifiers you may see. - * Legacy control example **API controlIdentifier** (regional): `arn:aws:controltower:us-east-1::control/AWS-GR_LOG_GROUP_POLICY` +You can use the [ListControls API](https://docs.aws.amazon.com/controlcatalog/latest/APIReference/API_ListControls.html) to retrieve all controls with their global ARNs. @@ -64 +65 @@ Here are examples of identifiers you may see. - * Proactive control example **API controlIdentifier** (regional): `arn:aws:controltower:us-east-1::control/EHSOKSSMVFWF` +## Migrate from regional ARNs to global ARNs @@ -66 +67 @@ Here are examples of identifiers you may see. - * Control catalog example **API controlIdentifier** (global): `arn:aws:controlcatalog:::control/5mhjhod4ky44haldvja2v4x3a` +Regional ARNs are no longer displayed in the console or the documentation, in favor of global ARNs. If you're using existing regional ARNs in your automation, you can continue to use them with the [AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/APIReference/Welcome.html) and [Control Catalog](https://docs.aws.amazon.com/controlcatalog/latest/APIReference/Welcome.html) APIs. However, we recommend that you migrate to global ARNs. @@ -67,0 +69 @@ Here are examples of identifiers you may see. +**Retrieve global ARNs by using regional control ARNs** @@ -68,0 +71 @@ Here are examples of identifiers you may see. +You can use regional ARNs with the [GetControl API](https://docs.aws.amazon.com/controlcatalog/latest/APIReference/API_GetControl.html) to retrieve control metadata and global ARNs. For example: @@ -71 +74 @@ Here are examples of identifiers you may see. -Older controls (legacy controls) include the name of the control in the ARN, but newer controls have a different identifier, and that is expected. + aws controlcatalog get-control --control-arn arn:aws:controltower:us-east-1::control/YEHYWYAUIQHZ --region us-east-1 @@ -73 +76 @@ Older controls (legacy controls) include the name of the control in the ARN, but -Legacy control example: `arn:aws:controltower:us-east-1::control/AWS-GR_CLOUDTRAIL_CHANGE_PROHIBITED` +The response includes the corresponding global ARN, but not the Regional ARN. @@ -75,3 +78 @@ Legacy control example: `arn:aws:controltower:us-east-1::control/AWS-GR_CLOUDTRA -Newer control example: `arn:aws:controltower:us-east-1::control/WTDSMKDKDNLE` - -### Find identifiers for OUs +## Find identifiers for OUs