Use Amazon SageMaker custom tags for project resource governance and cost tracking

Amazon SageMaker announced a new feature that you can use to add custom tags to resources created through an Amazon SageMaker Unified Studio project. This helps you enforce tagging standards that conform to your organization’s service control policies (SCPs) and helps enable cost tracking reporting practices on resources created across the organization.

As a SageMaker administrator, you can configure a project profile with tag configurations that will be pushed down to projects that currently use or will use that project profile. The project profile is set up to pass either required key and value tag pairings or pass the key of the tag with a default value that can be modified during project creation. All tags passed to the project will result in the resources created by that project being tagged. This provides you with a governance mechanism that enforces that project resources have the expected tags across all projects of the domain.

The first release of custom tags for project resources is supported through an application programming interface (API), through Amazon DataZone SDKs. In this post, we look at use cases for custom tags and how to use the AWS Command Line Interface (AWS CLI) to add tags to project resources.

What we hear from customers

As customers continue to build and collaborate using AWS tools for model development, generative AI, data processing, and SQL analytics, they see the need to bring control and visibility into the resources being created. To support connectivity to these AWS tools from SageMaker Unified Studio projects, many different types of resources across AWS services need to be created. These resources are created through AWS CloudFormation stacks (through project environment deployment) by the Amazon SageMaker service. From customers we hear the following use cases:

• Customers need to enforce that tagging practices conform to company policies through the use of AWS controls, such as SCPs, for resource creation. These controls block the creation of resources unless specific tags are placed on the resource.
• Customers can also start with policies to enforce that the correct tags are placed when resources are created with the additional goal of standardizing on resource reporting. By placing identifiable information on resources when created, they enforce consistency and completeness when performing cost attribution reporting and observability.

Customer Swiss Life uses SageMaker as a single solution for cataloging, discovery, sharing, and governance of their enterprise data across business domains. They require all resources have a set of mandatory tags for their finance group to bill organizations across their company for the AWS resources created.

“The launch of project resource tags for Amazon SageMaker allows us to bring visibility to the costs incurred across our accounts. With this capability we are able to meet the resource tagging guidelines of our company and have confidence in attributing costs across our multi-account setup for the resources created by Amazon SageMaker projects.”

– Tim Kopacz, Software Developer at Swiss Life

Prerequisites

To get started with custom tags, you must have the following resources:

• A SageMaker Unified Studio domain.
• An AWS Identity and Access Management (IAM) entity with privileges to make AWS CLI calls to the domain.
• An IAM entity authorized to make changes to the domain IAM provisioning role. If SageMaker created this for you, it will be called AmazonSageMakerProvisioning-. The provisioning role provisions and manages resources defined in the selected blueprints in your account.

How to set up project resource tags

The following steps outline how you can configure custom tags for your SageMaker Unified Studio project resources:

1. (Optional) Update the SageMaker provisioning role to permit specific tag keys.
2. Create a new project profile with project resource tags configured.
3. Create a new project with project resource tags.
4. Update an existing project with project resource tags.
5. Validate that the resources are tagged.

(Optional) Update a SageMaker provisioning role to permit tag key values

The AmazonSageMakerProvisioning- role has an AWS managed policy with condition aws:TagKeys allowing tags to be created by this role only if the tag key begins with AmazonDataZone. For this example, we will change the tag key to begin with different strings. Skip to Create a new project profile with project resource tags configured if you don’t need tag keys to have a different structure (such as begins with, contains, and so on)

1. Open the AWS Management Console and go to IAM.
2. In the navigation pane, choose Roles.
3. In the list, choose AmazonSageMakerProvisioning-.
4. Choose the Permissions tab.
5. Choose Add permissions, and then choose Create inline policy.
6. Under Policy editor, select JSON.
7. Enter the following policy. Add the strings under the condition aws:TagKeys. In this example, tag keys beginning with ACME or tag keys with the exact match of CostCenter will be created by the role.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "CustomTagsUnTagPermissions",
               "Effect": "Allow",
               "Action": [
                   "codecommit:UntagResource",
                   "iam:UntagRole",
                   "logs:UntagResource",
                   "athena:UntagResource",
                   "redshift-serverless:UntagResource",
                   "scheduler:UntagResource",
                   "bedrock:UntagResource",
                   "neptune-graph:UntagResource",
                   "quicksight:UntagResource",
                   "glue:UntagResource",
                   "airflow:UntagResource",
                   "secretsmanager:UntagResource",
                   "lambda:UntagResource",
                   "emr-serverless:UntagResource",
                   "elasticmapreduce:RemoveTags",
                   "sagemaker:DeleteTags",
                   "ec2:DeleteTags"
               ],
               "Resource": "*",
               "Condition": {
                   "StringEquals": {
                       "aws:ResourceAccount": "${aws:PrincipalAccount}"
                   },
                   "ForAllValues:StringLike": {
                       "aws:TagKeys": [
                           "AmazonDataZone*",
                           "ACME*",
                           "CostCenter"
                       ]
                   },
                   "Null": {
                       "aws:ResourceTag/AmazonDataZoneProject": "false"
                   }
               }
           },
           {
               "Sid": "CustomTagsTaggingPermissions",
               "Effect": "Allow",
               "Action": [
                   "cloudformation:TagResource",
                   "codecommit:TagResource",
                   "iam:TagRole",
                   "glue:TagResource",
                   "athena:TagResource",
                   "lambda:TagResource",
                   "redshift-serverless:TagResource",
                   "logs:TagResource",
                   "secretsmanager:TagResource",
                   "sagemaker:AddTags",
                   "emr-serverless:TagResource",
                   "neptune-graph:TagResource",
                   "bedrock:TagResource",
                   "elasticmapreduce:AddTags",
                   "airflow:TagResource",
                   "scheduler:TagResource",
                   "quicksight:TagResource",
                   "emr-containers:TagResource",
                   "logs:CreateLogGroup",
                   "athena:CreateWorkGroup",
                   "scheduler:CreateScheduleGroup",
                   "cloudformation:CreateStack",
                   "ec2:*"
               ],
               "Resource": "*",
               "Condition": {
                   "ForAnyValue:StringLike": {
                       "aws:TagKeys": [
                           "AmazonDataZone*",
                           "ACME*",
                           "CostCenter"
                       ]
                   },
                   "StringEquals": {
                       "aws:ResourceAccount": "${aws:PrincipalAccount}"
                   }
               }
           }
       ]
   }

It’s possible to scope down the specific AWS service tag and un-tag permissions based on which blueprints or capabilities are being used.

Create a new project profile with project resource tags configured

Use the following steps to create a new SQL Analytics project profile with custom tags. The example uses AWS CLI commands.

1. Open the AWS CloudShell console.
2. Create a project profile using the following CLI command.
   1. The project-resource-tags parameter consists of key (tag key), value (tag value), and isValueEditable (boolean indicating if the tag value can be modified during project creation or update).
   2. The allow-custom-project-resource-tags parameter set to true permits the project creator to create additional key-value pairs. The key needs to conform to the inline policy of the AmazonSageMakerProvisioning- role.
   3. The project-resource-tags-description parameter is a description field for project resource tags. The max character limit is 2,048. The description needs to be passed in every time create-project-profile or update-project-profile is called.

   aws datazone create-project-profile \
     --name "SQL Analytics with Project Resource Tags" \
     --description "Analyze your data in SageMaker Lakehouse using SQL" \
     --domain-identifier "$DOMAIN_ID" \
     --region "$REGION" \
     --status ENABLED \
     --project-resource-tags '[
       {
           "key": "ACME-Application",
           "value": "SageMaker",
           "isValueEditable": false
       },
       {
           "key": "CostCenter",
           "value": "123",
           "isValueEditable": true
       }
     ]' \
     --allow-custom-project-resource-tags \
     --environment-configurations '[
       {
           "name": "Tooling",
           "description": "Configuration for the Tooling Environment",
           "environmentBlueprintId": "",
           "deploymentMode": "ON_CREATE",
           "deploymentOrder": 0,
           "awsAccount": {
           "awsAccountId": "$ACCOUNT"
       },
       "awsRegion": {
           "regionName": "$REGION"
       },
           "configurationParameters": {
               "parameterOverrides": [
                   {
                       "name": "enableSpaces",
                       "value": "false",
                       "isEditable": false
                   },
                   {
                       "name": "maxEbsVolumeSize",
                       "isEditable": false
                   },
                   {
                       "name": "idleTimeoutInMinutes",
                       "isEditable": false
                   },
                   {
                       "name": "lifecycleManagement",
                       "isEditable": false
                   },
                   {
                       "name": "enableNetworkIsolation",
                       "isEditable": false
                   }
               ]
           }
       },
       {
           "name": "Lakehouse Database",
           "description": "Creates databases in Amazon SageMaker Lakehouse for storing tables in S3 and Amazon Athena resources for your SQL workloads",
           "environmentBlueprintId": "",
           "deploymentMode": "ON_CREATE",
           "deploymentOrder": 1,
           "awsAccount": {
               "awsAccountId": "$ACCOUNT"
           },
           "awsRegion": {
           "regionName": "$REGION"
           },
           "configurationParameters": {
               "parameterOverrides": [
                   {
                       "name": "glueDbName",
                       "value": "glue_db",
                       "isEditable": true
                   }
               ]
           }
       },
       {
           "name": "OnDemand RedshiftServerless",
           "description": "Enables you to create an additional Amazon Redshift Serverless workgroup for your SQL workloads",
           "environmentBlueprintId": "",
           "deploymentMode": "ON_DEMAND",
           "awsAccount": {
           "awsAccountId": "$ACCOUNT"
           },
           "awsRegion": {
               "regionName": "$REGION"
           },
           "configurationParameters": {
               "parameterOverrides": [
                   {
                       "name": "redshiftDbName",
                       "value": "dev",
                       "isEditable": true
                       },
                       {
                       "name": "redshiftMaxCapacity",
                       "value": "512",
                       "isEditable": true
                       },
                       {
                       "name": "redshiftWorkgroupName",
                       "value": "redshift-serverless-workgroup",
                       "isEditable": true
                       },
                       {
                       "name": "redshiftBaseCapacity",
                       "value": "128",
                       "isEditable": true
                       },
                       {
                       "name": "connectionName",
                       "value": "redshift.serverless",
                       "isEditable": true
                       },
                       {
                       "name": "connectToRMSCatalog",
                       "value": "false",
                       "isEditable": false
                       }
                   ]
               }
           },
           {
               "name": "OnDemand Catalog for Redshift Managed Storage",
               "description": "Enables you to create additional catalogs in Amazon SageMaker Lakehouse for storing data in Redshift Managed Storage",
               "environmentBlueprintId": "",
               "deploymentMode": "ON_DEMAND",
               "awsAccount": {
               "awsAccountId": "$ACCOUNT"
               },
               "awsRegion": {
                   "regionName": "$REGION"
               },
               "configurationParameters": {
                   "parameterOverrides": [
                       {
                           "name": "catalogName",
                           "isEditable": true
                       },
                       {
                           "name": "catalogDescription",
                           "value": "RMS catalog",
                           "isEditable": true
                       }
                   ]
               }
           }
     ]'

This project profile will have the tag ACME-Application = SageMaker placed on all projects associated to the project profile and cannot be modified by the project creator. The tag CostCenter = 123 can have the value modified by the project creator because the isValueEditable property is set to true.

Grant permissions for users to use the project profile during project creation. In the Authorization section of the project profile set either Selected users or groups or Allow all users and groups.

The use of the allow-custom-project-resource-tags parameter means the project creator can add their own tags (key-value pair). The key must conform to the condition check in the policy of the provisioning role (AmazonSageMakerProvisioning-). If the allow-custom-project-resource-tagsparameter is changed to false after a project created tags, tags created by the project will be removed during the next project update.

Updates to the project profile

Updates to project resource tags are possible through the update-project-profile command. The command will replace all values in the project-resource-tags section so be sure to include the exhaustive set of tags. Updates to the project profile are reflected in projects after running the update-project command or when a new project is created using the project profile. The following example adds a new tag, ACME-BusinessUnit = Retail.

There are three ways to work with the project-resource-tags parameter when updating the project profile.

• Passing a non-empty list of project resource tags will replace the tags currently configured on the project profile.
• Passing an empty list of project resource tags will clear out all previously configured tags:
  • --project-resource-tags '[]'
• Not including the project resource tag parameter will keep previously configured tags as-is.

aws datazone update-project-profile \
  --domain-identifier "$DOMAIN_ID" \
  --identifier "$PROJECT_PROFILE_ID" \
  --region "$REGION" \
  --project-resource-tags '[
    {
        "key": "ACME-Application",
        "value": "SageMaker",
        "isValueEditable": false
    },
    {
        "key": "CostCenter",
        "value": "123",
        "isValueEditable": true
    },
    {
        "key": "ACME-BusinessUnit",
        "value": "Retail",
        "isValueEditable": false
    }
  ]'

Create a new project with project resource tags

The following steps walk you through creating a new project that inherits tags from the project profile and lets the project creator modify one of the tag values.

1. Create a project using the following example CLI command.
2. Modify the CostCenter tag value using the --resource-tags parameter. Tags configured on the project profile where the isValueEditable attribute is false will be pushed to the project automatically.

   aws datazone create-project \
     --domain-identifier "$DOMAIN_ID" \
     --region "$REGION" \
     --name "$PROJECT_NAME" \
     --description "New project with tags" \
     --project-profile-id "$PROJECT_PROFILE_ID" \
     --resource-tags '{
           "CostCenter": "456"
       }'

Update existing project with project resource tags

For existing projects associated to the project profile, you must update the project for the new tags to be applied.

1. Update the project using the following example CLI command.
2. In this scenario, an editable value needs to be updated and a new tag added. Tag CostCenter will have its default value overwritten as “789” and the new ACME-Department = Finance tag will be added.

   aws datazone update-project \
     --domain-identifier "$DOMAIN_ID" \
     --identifier "$PROJECT_ID" \
     --project-profile-version "latest" \
     --region "$REGION" \
     --resource-tags '{
           "CostCenter": "789",
           "ACME-Department": "Finance"
       }' 

Project level tags (those not configured from the project profile) need to be passed during project update to be preserved. For tags with isValueEditable = true configured from the project profile, any override previously set needs to be applied or the value will revert to the default from the project profile.

Validating resources are tagged

Validate that tags are placed correctly. An example resource that is created by the project is the project IAM role. Viewing the tags for this role should show the tags configured from the project profile.

1. Open SageMaker Unified Studio to get the project role from the Project details section of the project. The role name begins with datazone_usr_role_.
2. Open the IAM console.
3. In the navigation pane, choose Roles.
4. Search for the project IAM role.
5. Select the Tags tab.
   
   

Conclusion

In this post, we discussed tagging related use cases from customers and walked through getting started with custom tags in Amazon SageMaker to place tags on the resources created by the project. By giving administrators a way to configure project profiles with standardized tag configurations, you can now help ensure consistent tagging practices across all SageMaker Unified Studio projects while maintaining compliance with SCPs. This feature addresses two critical customer needs: enforcing organizational tagging standards through automated governance mechanisms and enabling accurate cost attribution reporting across multi-service deployments.

To learn more, visit Amazon SageMaker, then get started with Project resource tags.

About the authors