AWS Proton resources and tagging

AWS Proton resources that are assigned an Amazon Resource Name (ARN) include environment templates and their major and minor versions, service templates and their major and minor versions, environments, services, service instances, components, and repositories. You can tag these resources to help you organize and identify them. You can use tags to categorize resources by purpose, owner, environment, or other criteria. For more information, see Tagging Strategies. To track and manage your AWS Proton resources, you can use the tagging features described in the following sections.

AWS tagging

You can assign metadata to your AWS resources in the form of tags. Each tag consists of a customer defined key and optional value. Tags can help you manage, identify, organize, search for, and filter resources.

AWS Proton tagging

With AWS Proton, you can use both the tags that you create as well as the tags that AWS Proton automatically generates for you.

AWS Proton​ AWS managed tags

When you create an AWS Proton resource, AWS Proton automatically generates AWS managed tags for your new resource as shown in the following diagram. AWS managed tags later propagate to other AWS Proton resources that are based on your new resource. For example, managed tags from an environment template propagate to its versions, and managed tags from a service propagate to its service instances.

Tag propagation to provisioned resources

If provisioned resources, such as those defined in service and environment templates, support AWS tagging, the AWS managed tags propagate as customer managed tags to provisioned resources. These tags won't propagate to a provisioned resource that doesn't support AWS tagging.

AWS Proton applies tags to your resources by AWS Proton accounts, registered templates and deployed environments, as well as services and service instances as described in the following table. You can use AWS managed tags to view and manage your AWS Proton resources, but you can't modify them.

The following is an example of an AWS managed tag for an AWS Proton resource.

"aws:proton:template" = "arn:aws:proton:region-id:account-id:environment-template/env-template"

The following is an example of a customer managed tag applied to a provisioned resource that was propagated from an AWS managed tag.

"proton:environment:database" = "arn:aws:proton:region-id:account-id:rds/env-db"

With AWS-managed provisioning, AWS Proton applies propagated tags directly to provisioned resources.

With self-managed provisioning, AWS Proton makes propagated tags available together with the rendered IaC files that it submits in the provisioning pull request (PR). Tags are provided in the string map variable proton_tags. We recommend that you make a reference to this variable in your Terraform configuration to include AWS Proton tags in default_tags. This propagates AWS Proton tags to all provisioned resources.

The following example shows this method of tag propagation in an environment Terraform template.

Here's the proton_tags variable definition:

proton.environment.variables.tf:

variable "environment" {
  type = object({
    inputs = map(string)
    name = string
  })
}

variable "proton_tags" {
  type = map(string)
  default = null
}

Here's how tag values are assigned to this variable:

proton.auto.tfvars.json:

{
  "environment": {
    "name": "dev",
    "inputs": {
      "ssm_parameter_value": "MyNewParamValue"
    }
  }

  "proton_tags" : {
    "proton:account" : "123456789012",
    "proton:template" : "arn:aws:proton:us-east-1:123456789012:environment-template/fargate-env",
    "proton:environment" : "arn:aws:proton:us-east-1:123456789012:environment/dev"
  }
}

And here's how you can add AWS Proton tags to your Terraform configuration so that they're added to provisioned resources:

# Configure the AWS Provider
provider "aws" {
  region = var.aws_region
  default_tags {
    tags = var.proton_tags
  }
}

Customer managed tags

Each AWS Proton resource has a maximum quota of 50 customer managed tags. Customer managed tags propagate to child AWS Proton resources in the same way that AWS managed tags do, except they don't propagate to existing AWS Proton resources or to provisioned resources. If you apply a new tag to an AWS Proton resource with existing child resources and you want the existing child resources to be tagged with the new tag, you need to tag each existing child resource manually, using the console or AWS CLI.

Create tags using the console and CLI

When you create an AWS Proton resource using the console, you're given the opportunity to create customer managed tags either on the first or second page of the create procedure as shown in the following console snapshot. Choose Add new tag, enter the key and value and proceed.

After you create a new resource using the AWS Proton console, you can view its list of AWS managed and customer managed tags from the detail page.

Create tags using the AWS Proton​ AWS CLI

You can view, create, remove and edit tags using the AWS Proton AWS CLI.

You can create or edit a tag for a resource as shown in the following example.

$ aws proton tag-resource \
    --resource-arn "arn:aws:proton:region-id:account-id:service-template/webservice" \
    --tags '[{"key":"mykey1","value":"myval1"},{"key":"mykey2","value":"myval2"}]'

You can remove a tag for a resource as shown in the next example.

$ aws proton untag-resource \
    --resource-arn "arn:aws:proton:region-id:account-id:service-template/webservice" \
    --tag-keys '["mykey1","mykey2"]'

You can list tags for a resource as shown in the final example.

$ aws proton list-tags-for-resource \
    --resource-arn "arn:aws:proton:region-id:account-id:service-template/webservice"