Tag Policies

src/config/policies/tag-policies/ contains the tag policies that define which tag keys and values your accounts may use. The landing zone ships two, attached to the workload OUs by default. You can use them as-is, modify their content, or add your own.

Tag policies attach in organization-structure.ts through the same policies array as SCPs and declarative policies. AWS Organizations allows at most 10 directly attached tag policies per root, OU, or account, counted separately from other policy types.

Shipped tag policies

Both policies live in environment-tags.ts.

Each policy is enforced for EC2 resource types. A request that tags an EC2 resource with another value, or with the key in another casing such as Environment, fails. The key and value are locked with @@operators_allowed_for_child_policies, so policies attached lower in the hierarchy can't change them (policy inheritance). See Enforce tagging consistency for how enforcement works.

Workloads apply the environment tag; the landing zone only governs it.

Example

The starter builds both policies from one helper and exports the tag key as ENVIRONMENT_TAG_KEY. Written out, the production policy is:

export const productionEnvironmentTagPolicy: OrganizationPolicy = {
  policyName: 'ProductionEnvironmentTag',
  policyType: PolicyType.TAG_POLICY,
  description: 'Allows only environment=production on EC2 resources',
  content: {
    tags: {
      environment: {
        tag_key: { '@@assign': 'environment', '@@operators_allowed_for_child_policies': ['@@none'] },
        tag_value: { '@@assign': ['production'], '@@operators_allowed_for_child_policies': ['@@none'] },
        enforced_for: { '@@assign': ['ec2:ALL_SUPPORTED'] },
      },
    },
  },
};

Write content in the tag policy syntax.

Adding a tag policy

1. Create a policy file in src/config/policies/tag-policies/ and export an OrganizationPolicy with policyType: PolicyType.TAG_POLICY.
2. Export it from src/config/policies/tag-policies/index.ts.
3. Import it in organization-structure.ts and add it to the policies array of the root, OU, or account that should receive it.
4. Run pnpm run organization:diff to preview the change, then deploy the organization phase.

Before you deploy

Enforced tag policies also reject tags that AWS services copy onto the resources they create. AWS warns that enforcement can block dynamic scaling and provisioning when a group or cluster propagates tags that the policy doesn't allow (best practices).

Before the first deployment, check the existing environment tags in your Development and Production accounts, including tags on Auto Scaling groups, EMR clusters, and similar services that pass tags to the EC2 instances they launch. A workload that tags environment=staging in the Production OU, for example, starts failing. Fix the tags first, or change the allowed values in the policy. AWS recommends testing enforcement on a single account before widening it.

Things to know

• A tag policy doesn't block resources created without the tag. Untagged resources, and keys that are spelled differently such as enviroment, aren't evaluated (tag policies). To require a tag at creation, use an SCP, as described in Create a Custom SCP.
• Enforcement covers EC2 resource types only. Other services' resources aren't blocked by these policies.
• Both the TAG_POLICY type and tag policy trusted access must stay enabled. Both are on by default. See Organization Policy Types and Trusted Access.
• Moving an account between OUs changes its policy. An account moved from the Development OU to the Production OU is held to environment=production.