Tagging your Amazon IoT SiteWise resources
With tags, you can organize and manage your resources in Amazon IoT SiteWise. You can use tags to assign metadata to your resources, and you can use tags in Amazon Identity and Access Management (IAM) policies to define conditional access to your resources.
Using tags in Amazon IoT SiteWise
You can use tags to categorize your Amazon IoT SiteWise resources by purpose, owner, environment, or any other classification for your use case. When you have many resources of the same type, you can quickly identify a specific resource based on its tags.
Each tag consists of a key and an optional value, both of which you define. For example, you could define a set of tags for your asset models that helps you track them by the industrial processes to which assets of each model contribute. We recommend that you create a set of tag keys that meets your needs for each kind of resource. By using a consistent set of tag keys, you can more easily manage your resources.
Tagging with the Amazon Web Services Management Console
The Tag Editor in the Amazon Web Services Management Console provides a central, unified way for you to create and manage your tags for resources from all Amazon services. For more information, see Tag Editor in the Amazon Resource Groups User Guide.
Tagging with the Amazon IoT SiteWise API
You can also work with tags by using the Amazon IoT SiteWise API. Before you create tags, be aware of tagging restrictions. For more information, see Tag naming and usage conventions in the Amazon Web Services General Reference.
-
To add tags when you create a resource, define them in the
tagsproperty of the resource. -
To add tags to an existing resource, or to update tag values, use the TagResource operation.
-
To remove tags from a resource, use the UntagResource operation.
-
To retrieve the tags that are associated with a resource, use the ListTagsForResource operation, or describe the resource and inspect its
tagsproperty.
The following table lists resources you can tag using the Amazon IoT SiteWise API and their
corresponding Create and Describe operations.
Taggable Amazon IoT SiteWise resources | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Resource | Create operation | Describe operation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Asset model or component model | CreateAssetModel | DescribeAssetModel | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Asset | CreateAsset | DescribeAsset | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Gateway | CreateGateway | DescribeGateway | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Portal | CreatePortal | DescribePortal | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Project | CreateProject | DescribeProject | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Dashboard | CreateDashboard | DescribeDashboard | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Access policy | CreateAccessPolicy | DescribeAccessPolicy | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Time series | BatchPutAssetPropertyValue | DescribeTimeSeries | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
For BatchPutAssetPropertyValue, you can configure your data sources to send industrial data to Amazon IoT SiteWise before you create asset models and assets. Amazon IoT SiteWise automatically creates data streams to receive streams of raw data from your equipment. For more information, see Managing data ingestion.
Use the following operations to view and manage tags for resources that support tagging:
-
TagResource – Adds tags to a resource, or updates an existing tag's value.
-
ListTagsForResource – Lists the tags for a resource.
-
UntagResource – Removes tags from a resource.
You can add or remove tags for a resource at any time. To change the value of a tag key, add a tag to the reosurce that defines the same key and the new value. The new value replaces the old value. You can set a value to an empty string, but you can't set a value to null.
When you delete a resource, tags that are associated with that resource are also deleted.
Using tags with IAM policies
In your IAM policies, you can use resource tags to control user access and permissions. For example, policies can allow users to create only those resources that have a specific tag. Policies can also restrict users from creating or modifying resources that have certain tags.
Note
If you use tags to allow or deny users' access to resources, you should deny users the ability to add or remove those tags for the same resources. Otherwise, a user could circumvent your restrictions and gain access to a resource by modifying its tags.
You can use the following condition context keys and values in the Condition
element (also called the Condition block) of a policy statement.
aws:ResourceTag/tag-key:tag-value-
Allow or deny actions on resources with specific tags.
aws:RequestTag/tag-key:tag-value-
Require that a specific tag be used (or not used) when creating or modifying a taggable resource.
aws:TagKeys: [tag-key, ...]-
Require that a specific set of tag keys be used (or not used) when creating or modifying a taggable resource.
Note
The condition context keys and values in an IAM policy apply only to actions that have a taggable resource as a required parameter. For example, you can set tag-based conditional access for ListAssets. You can't set tag-based conditional access on PutLoggingOptions because no taggable resource is referenced in the request.
For more information, see Controlling access to Amazon resources using resource tags and IAM JSON policy reference in the IAM User Guide.
Example IAM policies using tags