Resource Tagger - AMS Accelerate Operations Plan

Resource Tagger

Tags are an important input for many of our services like patch, backup, and monitoring. You use tags to group and differentiate your resources and map them with different configurations. With Resource Tagger, you can specify rules to govern how AWS resources are tagged in your account. While onboarding an account, AMS Accelerate deploys your tagging policy to ensure resources within your managed accounts are tagged.

What is Resource Tagger?

Resource Tagger is an AMS Accelerate service offering you use to specify rules to govern how AWS resources are tagged in your account. It aims to provide you with complete visibility into how your tags are applied to your AWS resources.

Resource Tagger automatically creates, updates, and deletes tags on supported AWS resources, based on the tagging rules you specify in your configuration profiles. For example, you can specify a rule that applies a tag to a collection of Amazon EC2 instances, indicating that they should be managed by AMS Accelerate, which results in the instances being monitored or backed up. You can use tags like this to identify compliance status for the AWS resources based on the defined policy in your AWS AppConfig configuration profiles. For more information, see AWS AppConfig.

AMS Accelerate provides a default managed tagging configuration so you can have your resources monitored by AMS Accelerate. You define which resources should be managed by AMS Accelerate, and the managed tagging rules ensure that the resources having the appropriate tags are monitored by AMS Accelerate.

With Resource Tagger, if you choose, you can override or deactivate the default AMS Accelerate managed tags, provide your own tagging rules to meet your policies, and use other mechanisms, such as Terraform, to avoid drift. You can define the exceptions to scale, based on your operations. For example, you could define policy to apply tags for all Amazon EC2 instances with supported platforms (such as Windows and Linux), and exclude from tagging specific instance IDs.

Important

Resource Tagger controls all tags in your account that have the ams:rt: prefix. Any tags that begin with this prefix are deleted unless they are present in Resource Tagger's configuration rules. To summarize, any tag on supported resources that starts with ams:rt: is considered owned by Resource Tagger. If you manually tag something with, for example, ams:rt:, that tag would automatically be removed if it wasn't specified in one of the Resource Tagger configuration profiles.

How Resource Tagger works

When your account is onboarded to AMS Accelerate, two JSON configuration documents are deployed to your account in AWS AppConfig. The two documents, called Configuration profiles, are AMSManagedTags, referred to as the default configuration profile, and CustomerManagedTags, referred to as the customization configuration profile. You use the customization configuration profile to define your own policies and rules for your accounts, and those are not overwritten by AMS Accelerate.

Both profiles reside in the AMSResourceTagger application, and in the AMSInfrastructure environment. All tags applied by the resource tagger have the key prefix ams:rt:.

Customization configuration profile:

The customization configuration profile is initially empty at the time of account onboarding; however, any rules placed in the profile document are enforced, in addition to the rules in the default configuration profile. Any configuration in the customization configuration profile is entirely managed by you, and is not overwritten by AMS Accelerate, except by your request.

You can specify any custom tagging rules you want in the custom configuration profile for the supported AWS resources, and you can also specify modifications to the AMS Accelerate-managed default configuration here, see Working with Resource Tagger.

Important

If you update this profile, the Resource Tagger automatically enforces the changes across all relevant resources in your AWS account. The changes are enacted automatically, but they may take up to 60 minutes to take effect.

You can update this profile by using the AWS Management Console, or through AWS CLI/SDK tools. For information about updating a customization configuration profile, see the AWS AppConfig user guide: What Is AWS AppConfig?

Default configuration profile:

The default configuration profile document is internal to AMS Accelerate and it contains AMS Accelerate-supplied default rules that you can't modify or delete permanently. This profile can be updated at any time by AMS Accelerate and made available to you for review; any changes you have made to it are automatically deleted. If you want to modify or disable any of the default configuration rules you use the customization configuration profile, see Working with Resource Tagger.

Configuration profile document format

The default configuration profile document and the customization configuration profile document have the same format and follow the same structure:

{ "ResourceType": { "ConfigurationID": { "Enabled": true, "Filter": { ... }, "Tags": [ ... ] }, "ConfigurationID": { ... } }, "ResourceType": { ... } }

Definitions:

ResourceType: This key must be one of the following supported strings, and represents all configuration related to the resource type indicated:

  • AWS::EC2::Instance

  • AWS::RDS::DBInstance

  • AWS::RDS::DBCluster

  • AWS::Elasticsearch::Domain

  • AWS::Redshift::Cluster

  • AWS::ElasticLoadBalancing::LoadBalancer

  • AWS::ElasticLoadBalancingV2::LoadBalancer

  • AWS::EC2::NatGateways

  • AWS:EC2::VPNConnection

ConfigurationID: This key must be unique in the profile document, and uniquely names the following block of configuration. If two configuration blocks in the same ResourceType block have the same ConfigurationID, the one that appears last in the profile takes effect. If you specify a ConfigurationID in your customization profile that is the same as one specified in the default document, the configuration block defined in the customization profile takes effect.

Important

The ConfigurationID should not overlap with the AMS Accelerate profile; for example, it should not be AMSMonitoringLinux or AMSMonitoringWindows, otherwise it disables the respective configuration of the AMSManagedTags configuration profile.

Enabled (optional, defaults to true): Specifies if the configuration block takes effect. Set this to false to disable a configuration block. A disabled configuration block has no effect.

Filter: Specifies the resources that the configuration applies to. Each filter object can have any one (but only one) of the following fields:

  • AWS::EC2::Instance

    • InstanceId: The filter matches an EC2 instance with the specified instance ID. This field supports wildcard matching, so i-00000* would match any instance that has an instance ID starting with i-00000.

    • Platform: The filter matches an EC2 instance with the specified platform. Valid values are windows, linux or the wildcard * (to match any platform).

  • AWS::EC2::NatGateways:

    • NatGatewayId: The ID of the NAT Gateway. This field supports wildcard matching.

    • State: The state of the NAT gateway (pending | failed | available | deleting | deleted or wildcard "*")

    • VpcId: The ID of the VPC in which the NAT Gateway resides. This field supports wildcard matching.

    • SubnetId: The ID of the Subnet in which the NAT Gateway resides. This field supports wildcard matching

  • AWS::EC2::VPNConnection:

    • VpnConnectionId: The ID of the connection.

  • AWS::RDS::DBCluster

    • DBClusterIdentifier: The filter matches an RDS cluster identifier with the specified identifier. This field does not support wildcard matching, so a cluster identifier must be specified.

    • Engine: The engine in use by the RDS Instance. This field supports wildcard matching.

    • EngineVersion: The engine version. This field supports wildcard matching.

  • AWS::RDS::DBInstance

    • DBInstanceIdentifier: The filter matches an RDS instance with the specified instance ID. This field does not support wildcard matching, so an instance identifier must be specified.

    • Engine: The engine in use by the RDS Instance. This field supports wildcard matching.

    • EngineVersion: The engine version. This field supports wildcard matching.

  • AWS::Elasticsearch::Domain

    • DomainId: The DomainId of the Elasticsearch resource. This field supports wildcard matching.

    • DomainName: The DomainName of the Elasticsearch resource. This field supports wildcard matching.

    • HasMasterNode: Boolean; If the Domain has a dedicated master node, this can be set to true.

    • HasKmsKey: If the Domain has a KMS key for encryption at rest, this can be set to true.

  • AWS::Redshift::Cluster

    • ClusterIdentifier: The Cluster Identifier. This field supports wildcard matching.

  • AWS::ElasticLoadBalancing::LoadBalancer (Classic Load Balancer)

    • LoadBalancerName: The LoadBalancer Name. This field supports wildcard matching.

    • Scheme: Can be either "internet-facing", "internal" or wildcard "*".

    • VPCId: The VPCId in which the loadbalancer is deployed, can be wildcard "*".

  • AWS::ElasticLoadBalancingV2::LoadBalancer (Application Load Balancer (ALB))

    • LoadBalancerArn: The LoadBalancer Amazon Resource Name (ARN).

    • DNSName: The DNSName of the LoadBalancer. This field supports wildcard matching.

    • LoadBalancerName: The LoadBalancer Name. This field supports wildcard matching.

    Other Filter properties:

    • Tag: The filter applies to any resource that already has the given tag applied. The value for this property must be a JSON object with the following fields:

      • Key: Must be an exact string, and specifies that the resources must have a tag with that exact key.

      • Value: Specifies the matching value for the tag. Supports wildcards, so a value of *Sample matches any value that ends with the string Sample.

    • Fn::AND: A JSON array of JSON objects. Each object follows the same rules as the Filter configuration block. This specifies that the filter match any resource that matches all of the sub-filters.

    • Fn::OR: A JSON array of JSON objects. Each object follows the same rules as the Filter configuration block. This specifies that the filter match any resource that matches any of the sub-filters.

    • Fn::NOT: A JSON object that follows the same rules as the Filter configuration block. This specifies that the filter explicitly not match any resource that matches the sub-filter. Use this to specify exclusions to your tagging rules.

    Tags: The tags to be applied to the matched resources. This field is a JSON array, with each element being a JSON object containing the following fields:

    • Key: The key for the tag to be applied.

    • Value: The value for the tag to be applied.

Note

All tags applied by Resource Tagger always have the prefix ams:rt:. If you do not specify this prefix on your tag value here, it's automatically applied for you. This is to maintain a record of which tag values have been applied by Resource Tagger, as opposed to those applied by any other means.

For important information on tags, see Tag naming and usage conventions

Working with Resource Tagger

How to use AMS Accelerate Resource Tagger.

Viewing the tags applied by Resource Tagger

All tags applied by Resource Tagger have the key prefix ams:rt:. For example, the following tag definition results in a tag with key ams:rt:sampleKey and value sampleValue. All tags with this prefix are treated as being part of Resource Tagger.

{ "Key": "sampleKey", "Value": "sampleValue" }
Important

If you manually create your own tag with the ams:rt: prefix, it's considered managed by Resource Tagger. This means that if the resource is managed by Resource Tagger, but the configuration profiles do not indicate that the tag should be applied, then Resource Tagger removes your manually added tag. If you do manually tag resources managed by Resource Tagger, do not use the ams:rt: prefix for tag keys.

Example configuration profile

The following example profile document specifies that all Windows EC2 instances that are part of a stack-* CloudFormation stack be managed by AMS Accelerate; however, explicitly excludes a particular EC2 instance with ID i-00000000000000001.

{ "AWS::EC2::Instance": { "AMSMonitoringWindows": { "Enabled": true, "Filter": { "Fn::AND": [ { "Platform": "Windows" }, { "Tag": { "Key": "aws:cloudformation:stack-name", "Value": "stack-*" } }, { "Fn::NOT": { "InstanceId": "i-00000000000000001" } } ] }, "Tags": [ { "Key": "ams:rt:monitoring-policy", "Value": "AMS::FullyManaged" } ] } } }

Merging the default configuration

The default configuration profile is supplied by AMS Accelerate at the time of account onboarding. This profile provides default rules that are deployed in your account.

While you can't modify the default configuration profile, you can provide overrides to the defaults by specifying a configuration block in your customization configuration profile with the same ConfigurationID as the default configuration block. If you do this, your configuration block overwrites the default configuration block.

For example, consider the following default configuration document:

{ "AWS::EC2::Instance": { "AMSManagedBlock1": { "Enabled": true, "Filter": { "Platform": "Windows" }, "Tags": [{ "Key": "my-tag", "Value": "SampleValueA" }] } } }

In order to change the tag value applied here from SampleValueA to SampleValueB, and have the tag applied to all instances, not just Windows instances, you would provide the following customization configuration profile:

{ "AWS::EC2::Instance": { "AMSManagedBlock1": { "Enabled": true, "Filter": { "Platform": "*" }, "Tags": [{ "Key": "my-tag", "Value": "SampleValueB" }] } } }
Important

Remember to deploy your configuration changes after you have made them; for information, see Deploying configuration changes. In SSM AppConfig, you must deploy a new version of the configuration after creating it.

Disabling the default configuration

You can disable a default configuration rule by adding a configuration block with the same ConfigurationID to your customization configuration profile and giving the Enabled field for a value of false.

For example, if the following configuration were present in the default configuration profile:

{ "AWS::EC2::Instance": { "AMSManagedBlock1": { "Enabled": true, "Filter": { "Platform": "Windows" }, "Tags": [{ "Key": "my-tag", "Value": "SampleValueA" }] } } }

You could disable this tagging rule by including the following in your customization configuration profile:

{ "AWS::EC2::Instance": { "AMSManagedBlock1": { "Enabled": false } } }
Important

Remember to deploy your configuration changes after you have made them; for information, see Deploying configuration changes. In SSM AppConfig, you must deploy a new version of the configuration after creating it.

Removing tags applied by Resource Tagger

Any tags prefixed with ams:rt are removed by Resource Tagger if the tags do not exist in the configuration profiles, or, if they do exist, where the filter doesn't match. This means that you can remove tags applied by Resource Tagger by doing one of the following:

  • Modifying the customization configuration section that defines the tag.

  • Adding an exception for the specific resources so they no longer match the filter.

For example: if a Linux instance has the following tags:

"Tags": [{ "Key": "ams:rt:MyOwnTag", "Value": true },{ "Key": "myTag", "Value": true }]

And you deploy the following Resource Tagger configuration profile:

{ "AWS::EC2::Instance": { "AMSMonitoringWindows": { "Enabled": true, "Filter": { "Platform": "Windows" }, "Tags": [{ "Key": "ams:rt:monitoring-policy", "Value": "AMS::FullyManaged" }] } } }

Resource Tagger reacts to the new configuration changes, and the only tag on the instance becomes:

"Tags": [{ "Key": "myTag", "Value": true }]
Important

Remember to deploy your configuration changes after you have made them; for information, see Deploying configuration changes. In SSM AppConfig, you must deploy a new version of the configuration after creating it.

Viewing or making changes to the Resource Tagger configuration

The two JSON configuration profiles, AMSManagedTags and CustomerManagedTags, deployed to your account in AWS AppConfig at onboarding and residing in the AMSResourceTagger application, and in the AMSInfrastructure environment, can be reviewed through AppConfig’s GetConfiguration API.

The following is an example of this GetConfiguration call:

aws appconfig get-configuration --application AMSResourceTagger --environment AMSInfrastructure --configuration AMSManagedTags --client-id ANY_STRING outfile.json

Application: AppConfig logical unit to provide capabilities, for the Resource Tagger, this is AMSResourceTagger.

  • Environment: AMSInfrastructure.

  • Configuration: To view AMS Accelerate default tag definitions, the value is AMSManagedTags, while to view customer tag definitions, the value is CustomerManagedTags.

  • Client ID: The unique application instance identifier, this can be any string.

  • The tag definitions can then be viewed in the specified output file, in this case, outfile.json.

The alarm definitions can then be viewed in the specified output file, in this case, outfile.json.

You can see which version of configuration is deployed to your account by viewing the past deployments in the AMSInfrastructure environment.

To override tag rules:

Any of the existing tag rules can be overridden by updating the customization profile using AppConfig’s CreateHostedConfigurationVersion API. Using the same ConfigurationID as a default configuration tag rule overrides the default rule, and applies the custom rule in its place.

To deploy changes made to the CustomerManagedTags document:

After you make changes to the customization configuration profile, you must deploy the changes for them. To deploy the new changes, AppConfig’s StartDeployment API must be run using the AWS AppConfig Console or the CLI.

Deploying configuration changes

Once the customization is completed, these changes must be deployed through the AWS AppConfig StartDeployment API. The following instructions show how to deploy using the AWS CLI. Additionally, you can use the AWS Management Console to make these changes. For information, see Step 5: Deploying a configuration.

aws appconfig start-deployment --application-id <application_id> --environment-id <environment_id> --deployment-strategy-id <deployment_strategy_id> --configuration-profile-id <configuration_profile_id> --configuration-version 1
  • Application ID: The application ID of the application AMSResourceTagger. Get this with the ListApplications API call.

  • Environment ID: The environment ID; get this with the ListEnvironments API call.

  • Deployment Strategy ID: The deployment strategy ID; get this with the ListDeploymentStrategies API call.

  • Configuration Profile ID: The configuration profile ID of CustomerManagedTags; get this with the ListConfigurationProfiles API call.

  • Configuration Version: The version of the configuration profile you intend to deploy.

Important

Resource Tagger applies the tags as specified in the configuration profiles. Any manual modifications you make (with the AWS Management Console, or CloudWatch CLI/SDK) to the resource tags are automatically reverted back, so ensure your changes are defined through Resource Tagger. To know which tags are created by the Resource Tagger, look for tag keys prefixed with ams:rt:.

Restrict access to the deployment with the StartDeployment and the StopDeployment API actions to trusted users who understand the responsibilities and consequences of deploying a new configuration to your targets.

To learn more about how to use AWS AppConfig features to create and deploy a configuration, see the documentation at Working with AWS AppConfig.

Configuring Terraform to ignore Resource Tagger tags

If you use Terraform to provision your resources, and you want to use Resource Tagger to tag your resources, the Resource Tagger tags may be identified as drift by Terraform.

You can configure Terraform to ignore all Resource Tagger tags using the lifecycle configuration block, or the ignore_tags global configuration block. For more information, see the Terraform documentation on Resource Tagging at Resource Tagging.

The following example shows how to create a global configuration to ignore all tags that begin with the Resource Tagger tag prefix ams:rt::

provider "aws" { # ... potentially other configuration ... ignore_tags { key_prefixes = ["ams:rt:"] } }