# Custom tag propagation
<a name="custom-tags"></a>

 Amazon SageMaker AI supports the ability to propagate custom tags set at the domain, user profile, and space level to all of the SageMaker AI resources created in the context of Amazon SageMaker Studio, JupyterLab, Code Editor, based on Code-OSS, Visual Studio Code - Open Source, and Amazon SageMaker Canvas. With custom tag propagation, users can propagate their own custom tags to resources to improve cost tracking and tie resources to specific projects and teams. 

 To activate this feature, use the `TagPropagation` attribute in the [CreateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateDomain.html) and [UpdateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) APIs. Custom tag propagation can only be set at the domain level, which means that all users and spaces in a domain use the feature when it is activated. It is not possible to modify custom tag propagation settings at the user profile or space level. For more information about using custom tag propagation, see [Add custom tags to resources](custom-tags-add.md). 

**Note**  
System tags added by AWS services on a domain, user profile, and space are not propagated. 

## Example use cases
<a name="custom-tags-use-cases"></a>

 Custom tag propagation is particularly useful for the following use cases. 
+  Track cost across all of the SageMaker AI resources created in Amazon SageMaker Studio. 
+  Track cost for SageMaker AI resources that are created in Amazon SageMaker Canvas. This includes models deployed on a SageMaker AI endpoint.
+  Track cost incurred for an Amazon DataZone project by propagating the Amazon DataZone project ID to all the resources created by Amazon SageMaker Studio. 

## Tag merging
<a name="custom-tags-use-merging"></a>

 With custom tag propagation activated, resources created at the user profile and space level take on the tags specified at the domain level, as well as those specified during user profile or space creation.

 SageMaker AI resources have a 50 tag limit. If the number of tags added to a resource exceeds 50, SageMaker AI returns an error during resource creation. We recommend limiting the number of tags to avoid this. For example, assume a user has 25 tags for their domain and 30 tags for their user profile. When the user creates a resource, a total of 55 tags propagate to the resource. Because the aggregate tag total exceeds 50, resource creation fails until the user removes at least 5 tags. 

**Note**  
By default, SageMaker AI automatically adds the `sagemaker:user-profile-arn`, `sagemaker:domain-arn`, or `sagemaker:space-arn` tag to SageMaker AI resources. SageMaker AI adds the ARN tag regardless of whether or not the domain is using custom tag propagation. These ARN tags also contribute toward the 50 tag limit. 

# Add custom tags to resources
<a name="custom-tags-add"></a>

 The following page demonstrates the steps needed to use custom tag propagation. Custom tag propagation requires the following steps: 
+  Opt-in to custom tag propagation 
+  Add custom tags to resources 

 When you activate custom tag propagation in an existing domain, tag propagation does not work for existing applications until the application is restarted. Similarly, tags are not updated on an existing resource when new custom tags are added. For example, assume a domain has two tags and a user creates a resource in that domain. The resource then has two tags. If a new tag is added to the domain, then that new tag is not added to the existing resource. However, any new resource created will have the new tag attached to the resource.

## Prerequisites
<a name="custom-tags-add-prereq"></a>
+  Users must have the `sagemaker:AddTags` permission for any resource creation. 
  +  For new domains created with the `SageMakerFullAccess` managed policy or using the SageMaker Role Manager, the `sagemaker:AddTags` permission is pre-populated. 
  +  For existing domains using custom AWS Identity and Access Management policies, you must update the policies to include the `sagemaker:AddTags` permission to allow users to create resources.

## Opt-in to custom tag propagation
<a name="custom-tags-add-opt-in"></a>

The process to opt-in to custom tag propagation differs based on if you are opting-in from the console or from the AWS CLI. From the console, you can only opt-in to custom tag propagation by updating an existing domain. From the AWS CLI, you can opt-in to custom tag propagation when creating a domain or updating an existing domain.



### Opt-in from the console
<a name="custom-tags-add-opt-in-console"></a>

The following steps outline how to opt-in to custom tag propagation from the console. You can only opt-in to custom tag propagation from the console by updating an existing domain.

1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/).

1. On the left navigation, select **Admin configurations**. Under **Admin configurations**, select **Domains**.

1. On the **Domains** page, select the domain that you want to activate custom tag propagation for.

1. From the **Domain details** page, select the **Domain settings** tab.

1. On the **Domain settings** tab, navigate to **Custom Tag Propagation**.

1. Select **Edit**.

1. From the **Edit custom tag propagation** page, select **Automatically propagate custom tags**

1. Select **Submit**.

### Opt-in using the AWS CLI
<a name="custom-tags-add-opt-in-cli"></a>

 To opt-in to custom tag propagation using the AWS CLI, use the `TagPropagation` attribute in the [CreateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateDomain.html) and [UpdateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) APIs. By default, the value of this field is `DISABLED`. An empty value also defaults to `DISABLED`. The following example shows how to activate custom tag propagation. 

```
aws sagemaker update-domain \
--domain-id domain-id \
--region region \
--tag-propagation ENABLED
```

## Add custom tags
<a name="custom-tags-add-tags"></a>

The process to add custom tags propagation differs based on if you are adding them from the console or from the AWS CLI.

### Add from the console
<a name="custom-tags-add-tags-console"></a>

The following steps outline how to add custom tags to a domain from the console.

1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/).

1. On the left navigation, select **Admin configurations**. Under **Admin configurations**, select **Domains**.

1. On the **Domains** page, select the domain that you want to add custom tags to.

1. From the **Domain details** page, select the **Domain settings** tab.

1. On the **Domain settings** tab, navigate to **Tags**.

1. Select **Edit**.

1. From the **Tags** page, select **Add tag**. Add a key and value pair for the custom tag.

1. Select **Save**. This custom tag is now propagated to the SageMaker AI resources created in the domain.

The following steps outline how to add custom tags to a user profile from the console.

1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/).

1. On the left navigation, select **Admin configurations**. Under **Admin configurations**, select **Domains**.

1. On the **Domains** page, select the domain containing the user profile that you want to add custom tags to.

1. From the **Domain details** page, select the **User profiles** tab.

1. On the **User profiles** tab, select the user profile you want to add custom tags to.

1. On the **User Details** tab, navigate to the **Details** section.

1. Select **Edit**.

1. From the **Tags** section, select **Add tag**. Add a key and value pair for the custom tag.

1. Select **Submit**. This custom tag is now propagated to the SageMaker AI resources created in the domain.

### Add using the AWS CLI
<a name="custom-tags-add-tags-cli"></a>

 After you have activated custom tag propagation, you can add custom tags using the AWS CLI at the domain, user profile, or space level during creation or update. The method to add custom tags differs depending on you are creating a new resource or adding tags to an existing resource.

 The following example shows how to add custom tags at the domain level during creation. 

```
aws sagemaker create-domain \
    --domain-name domain-id \
    --auth-mode IAM \
    --default-user-settings '{"ExecutionRole": "execution-role"}' \
    --subnet-ids subnet-id \
    --vpc-id vpc-id \
    --tags Key=key,Value=value \
    --tag-propagation ENABLED
```

 You must use the [AddTags](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_AddTags.html) API to add custom tags for existing domain, user profile, and spaces as follows. 

```
aws sagemaker add-tags \
--resource-arn resource-arn-to-attach-tags \
--tags Key=key, Value=value
```

# Opt-out of custom tag propagation
<a name="custom-tags-opt-out"></a>

 The process to opt-out of custom tag propagation differs based on if you are opting-out from the console or from the AWS CLI.

## Opt-out from the console
<a name="custom-tags-opt-out-console"></a>

The following steps outline how to opt-out of custom tag propagation from the console. You can only opt-out of custom tag propagation from the console by updating an existing domain.

1. Open the Amazon SageMaker AI console at [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/).

1. On the left navigation, select **Admin configurations**. Under **Admin configurations**, select **Domains**.

1. On the **Domains** page, select the domain that you want to opt-out of custom tag propagation for.

1. From the **Domain details** page, select the **Domain settings** tab.

1. On the **Domain settings** tab, navigate to **Custom Tag Propagation**.

1. Select **Edit**.

1. From the **Edit custom tag propagation** page, select **Automatically propagate custom tags**

1. Select **Submit**.

## Opt-out using the AWS CLI
<a name="custom-tags-opt-out-cli"></a>

To opt-out of custom tag propagation, set the `TagPropagation` attribute in the [CreateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateDomain.html) and [UpdateDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateDomain.html) APIs to `DISABLED` as shown in the following example. By default, the value of this field is `DISABLED`. An empty value also defaults to `DISABLED`.  

**Note**  
Tag propagation is not automatically turned off for existing applications when `TagPropagation` is set to `DISABLED`. Applications must be restarted for opt-out to take effect for existing apps. 

```
aws sagemaker update-domain \
--domain-id domain-id \
--region region \
--tag-propagation DISABLED
```