Enforce "Required tag key" with IaC - Amazon Organizations
Enforce with Amazon CloudFormationEnforce with TerraformEnforce with Pulumi
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Enforce "Required tag key" with IaC

Tag policies help you maintain consistent tagging across your infrastructure as code (IaC) deployments. With "Required tag keys", you can ensure that all resources created through IaC tools like Amazon CloudFormation, Terraform, and Pulumi include the mandatory tags defined by your organization.

This capability checks your IaC deployments against your organization's tag policies before resources are created. When a deployment is missing required tags, you can configure your IaC settings to either warn your development teams or prevent the deployment entirely. This proactive approach maintains tagging compliance from the moment resources are created, rather than requiring manual remediation later. The enforcement works across multiple IaC tools using a single tag policy definition, eliminating the need to configure separate tagging rules for each tool your organization uses.

Enforce with Amazon CloudFormation

Note

To enforce required tag keys with Amazon CloudFormation, you must specify required tags for your resource type in tag policies. See the Reporting for "Required tag key" section for more details.

Setup Execution Role for the Amazon::TagPolicies::TaggingComplianceValidator Hook

Before activating the Amazon::TagPolicies::TaggingComplianceValidator hook, you must create an execution role that the hook uses to access Amazon services. The role must have the following Trust Policy attached to it: 

{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "resources.cloudformation.amazonaws.com",
                    "hooks.cloudformation.amazonaws.com"
                ]
            },
            "Action": [
                "sts:AssumeRole"
            ]
        }
    ]
}

The execution role must also have a Role Policy with at least the following permissions:

{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "tag:ListRequiredTags"
            ],
            "Resource": "*"
        }
    ]
}

For more information about setting up execution roles for public extensions, see Configure an execution role with IAM permissions and a trust policy for public extension access in the Amazon CloudFormation User Guide.

Activate the Amazon::TagPolicies::TaggingComplianceValidator Hook

Important

Before you continue, verify that you have the permissions required to work with Hooks and view proactive controls from the CloudFormation console. For more information, see Grant IAM permissions for CloudFormation Hooks.

After updating your tag policy, you must activate the Amazon::TagPolicies::TaggingComplianceValidator hook in every Amazon account and Region where you want to enforce required tagging compliance.

This Amazon-managed hook can be configured in two modes:

  • Warn mode: Allows deployments to proceed but generates warnings when required tags are missing

  • Fail mode: Blocks deployments that are missing required tags

To activate the hook using the Amazon CLI:

aws cloudformation activate-type \
    --type HOOK \
    --type-name AWS::TagPolicies::TaggingComplianceValidator \
    --execution-role-arn arn:aws:iam::123456789012:role/MyHookExecutionRole \
    --publisher-id aws-hooks \
    --region us-east-1
aws cloudformation set-type-configuration \
  --configuration '{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "WARN", "TargetOperations": ["STACK"], "Properties":{}}}}' \
  --type-arn "arn:aws:cloudformation:us-east-1:123456789012:type/hook/AWS-TagPolicies-TaggingComplianceValidator" \
  --region us-east-1

Replace region with your target Amazon region, and change "FailureMode":"FAIL" to "FailureMode":"WARN" if you prefer warning mode.

Activate the Amazon::TagPolicies::TaggingComplianceValidator Hook across multiple accounts and Regions with Amazon CloudFormation StackSets

For organizations with multiple Amazon accounts, you can use Amazon Amazon CloudFormation StackSets to activate the tagging compliance hook across all your accounts and Regions simultaneously.

Amazon CloudFormation StackSets allow you to deploy the same Amazon CloudFormation template to multiple accounts and Regions with a single operation. This approach ensures consistent tagging enforcement across your entire Amazon organization without requiring manual configuration in each account.

To use Amazon CloudFormation StackSets for this purpose:

  1. Create a Amazon CloudFormation template that activates the tagging compliance hook

  2. Deploy the template using Amazon CloudFormation StackSets to target your organizational units or specific accounts

  3. Specify all Regions where you want enforcement enabled

The Amazon CloudFormation StackSets deployment will automatically handle the activation process across all specified accounts and Regions, ensuring uniform tagging compliance throughout your organization. To learn how to deploy Amazon CloudFormation Hooks to an Organization with service-managed Amazon CloudFormation StackSets, see this Amazon blog.

Deploy the Amazon CloudFormation template below using Amazon CloudFormation StackSets to activate the Amazon::TagPolicies::TaggingComplianceValidator Hook for accounts in your organization.

Important

This hook only functions as a StackHook. It has no effect when used as a resource hook.

Resources:
  # Activate the AWS-managed hook type
  HookTypeActivation:
    Type: AWS::CloudFormation::TypeActivation
    Properties:
        AutoUpdate: True
        PublisherId: "AWS"
        TypeName: "AWS::TagPolicies::TaggingComplianceValidator"
  
  # Configure the hook
  HookTypeConfiguration:
    Type: AWS::CloudFormation::HookTypeConfig
    DependsOn: HookTypeActivation
    Properties:
      TypeName: "AWS::TagPolicies::TaggingComplianceValidator"
      TypeArn: !GetAtt HookTypeActivation.Arn
      Configuration: !Sub |
        {
          "CloudFormationConfiguration": {
            "HookConfiguration": {
              "TargetStacks": "ALL",
              "TargetOperations": ["STACK"],
              "Properties": {},
              "FailureMode": "Warn",
              "TargetFilters": {
                "Actions": [
                    "CREATE",
                    "UPDATE"
                ]}
            }
          }
        }
Note

For more information on running Amazon CloudFormation hooks, see Activate a proactive control-based Hook in your account.

Enforce with Terraform

To enforce required tag keys with Terraform, you need to update your Terraform Amazon Provider to 6.22.0 or above and enable tag policy validation in your provider configuration. For implementation details and configuration examples, see the Terraform Amazon Provider documentation on tag policy enforcement.

Enforce with Pulumi

To enforce required tag keys with Pulumi, you need to enable the Tag Policy Reporting policy pack in Pulumi Cloud and configure your IAM role with tag policy read permissions. For implementation details and configuration examples, see the Pulumi documentation on tag policy enforcement.