Working with tags

As an Organization administrator with the Assembler admin service role, you can use the Tags endpoints to create, manage, or delete tags in Automation Assembler.

For information about working with tags using the UI, see How do I use tags to manage Automation Assembler resources and deployments.

Note:

Tag filters are case-insensitive.
There is no way to query for unused tags using the IaaS API. However, you can submit a request to check for tag usage of specific tag IDs.

Prerequisites for working with tags

Verify that all general prerequisites and prerequisites for the Automation Assembler Infrastructure as a Service (IaaS) service have been satisfied. See Prerequisites for API Use Case Examples.

Filtering for tags

You can filter for tags based on a key, value, or origin and the tag filters are case-insensitive.

The following example shows how to filter for a tag with location in the key name.

curl -X GET \
  "$url/iaas/api/tags?$filter=key%20eq%20'location’&apiVersion=$api_version" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" | jq "."

A sample response shows "key": "location".

{
    "content": [
        {
            "key": "location",
            "value": "MUM",
            "id": "9aabbe23-d4bf-3d55-89f7-dc7e67317442"
        }
    ],
    "totalElements": 1,
    "numberOfElements": 1
}

To filter for the origin of a tag, you specify USER_DEFINED or DISCOVERED for the origin value. The following example filters for tags with the DISCOVERED origin.

curl -X GET \
  "$url/iaas/api/tags?$filter=origins.item%20eq%20%27DISCOVERED%27&apiVersion=$api_version" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" | jq "."

Tag origins can also be both USER_DEFINED and DISCOVERED as in the following cases:

If a tag's origin is USER_DEFINED and another tag with the same case-sensitive key/value pair is assigned to an endpoint resource from which Automation Assembler collects data, Automation Assembler adds the DISCOVERED origin.
If a user assigns a tag with the DISCOVERED origin to any Automation Assembler resource such as a network profile, Automation Assembler also assigns the USER_DEFINED origin to the tag.

Creating tags

You create a tag with a name and an optional value. The following example shows how to create a tag named environment with the value prod that you could add to resources in your production environment.

curl -X POST \
  "$url/iaas/api/tags?apiVersion=$api_version"
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $access_token" 
  -d '{ 
    "key" : "environment",
    "value" : "prod" 
  }' | jq "."

The response provides the tag ID.

 {
    "key": "environment",
    "value": "prod",
    "id": "ca0ed5ef-72b5-3d9f-bc6d-0707defff540"
}

Listing and deleting tags

To delete a tag, you specify the tag ID. To get the tag ID, you list all tags in your infrastructure.

curl -X GET \
  "$url/iaas/api/tags?apiVersion=$api_version"
  -H 'Content-Type: application/json' 
  -H "Authorization: Bearer $access_token"  
  }' | jq "."

The response lists all the tag names, values, and IDs as in the following example.

{
    "content": [
        {
            "key": "location",
            "value": "MUM",
            "id": "9aabbe23-d4bf-3d55-89f7-dc7e67317442"
        }
        {
            "key": "Application",
            "value": "testing",
            "id": "57ead12-523a-3cd2-9447-06e757dcf382"
        }
    ],
    "totalElements": 2,
    "numberOfElements": 2
}

Before deleting a tag, a best practice is to check the tag usage of the ID that you plan to delete. The following example checks for usage of the tag with ID 9aabbe23-d4bf-3d55-89f7-dc7e67317442.

curl -X POST \
  "$url/iaas/api/tags/tags-usage?apiVersion=$api_version" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" \
  -d '{ 
    "tagIds" : ["9aabbe23-d4bf-3d55-89f7-dc7e67317442"]  
  }' | jq "."

If the tag is being used, the response shows where it is being used. This sample response shows that the tag is being used in a network profile.

{
    "documentLinks": [
        "/provisioning/resources/network-profiles/8615bbfe-ea90-420a-a1cf-8048ba4271d4"
    ],
    "documents": {
        "/provisioning/resources/network-profiles/8615bbfe-ea90-420a-a1cf-8048ba4271d4": {
            "id": "a30929ec-3b06-484e-8785-cc43619b5b01",
            "name": "23360",
            "customProperties": {
                "edgeClusterRouterStateLink": "/resources/routers/2d57f1c4-fbe0-46ce-a061-3a5f1396f37b",
                "tier0LogicalRouterStateLink": "/resources/routers/9c965abe-9d69-40c0-99e0-be5aa7e52097",
                "onDemandNetworkIPAssignmentType": "mixed"
            },
            "tagLinks": [
                "/resources/tags/ef254637-594d-3960-a642-f157f859a830",
                "/resources/tags/9aabbe23-d4bf-3d55-89f7-dc7e67317442"
            ],
            "expandedTags": [
                {
                    "tag": "23360\n"
                },
                {
                    "tag": "location\nMUM"
                }
            ],
            "documentVersion": 11,
            "documentKind": "com:vmware:admiral:compute:profile:NetworkProfileService:NetworkProfile",
            "documentSelfLink": "/provisioning/resources/network-profiles/8615bbfe-ea90-420a-a1cf-8048ba4271d4",
            "documentUpdateTimeMicros": 1696947968305000,
            "documentExpirationTimeMicros": 0
        }
    },
    "documentCount": 1,
    "documentVersion": 0,
    "documentUpdateTimeMicros": 0,
    "documentExpirationTimeMicros": 0}

If the tag is not being used, the response shows no resource links.

{
    "documentLinks": [],
    "documents": {},
    "documentCount": 0,
    "documentVersion": 0,
    "documentUpdateTimeMicros": 0,
    "documentExpirationTimeMicros": 0
}

To delete the unused tag, specify the tag ID. The delete action first checks to ensure that the tag is not associated with a resource before deleting it. The following example deletes the tag with ID 9aabbe23-d4bf-3d55-89f7-dc7e67317442.

curl -X DELETE \
  "$url/iaas/api/tags/9aabbe23-d4bf-3d55-89f7-dc7e67317442?apiVersion=$api_version" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token"  \
  }' | jq "."

Note: To delete a tag that is associated with a resource, you can use the ignoreUsage query parameter as in the following example that forces the deletion of a tag with ID 9aabbe23-d4bf-3d55-89f7-dc7e67317442. However, this removes all tag assignments from all the resources associated with the tag.

curl -X DELETE \
  "$url/iaas/api/tags/9aabbe23-d4bf-3d55-89f7-dc7e67317442?ignoreUsage=true&apiVersion=$api_version" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token"  | jq "."

Updating tags

You can use the IaaS API to add, remove, or update the tags associated with a resource. Using the ID of the resource, you submit a request get the details about the resource including the tag definitions. Then you submit a request to update the resource with new tag key/value pairs.

The following example shows how to update tags for a vSphere datastore

List all vSphere datastores.

curl -X GET \
  "$url/iaas/api/fabric-vsphere-datastores?apiVersion=$api_version"
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" | jq "."

Examine the response to find the ID of the datastore that you want to use and use the ID to get details about the datastore. The following request uses the datastore ID 002e0a62-846d-4fb2-a153-3dcd80e57ba9.

curl -X GET \
  "$url/iaas/api/fabric-vsphere-datastores/002e0a62-846d-4fb2-a153-3dcd80e57ba9/?apiVersion=$api_version"
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" | jq "."

A snippet of the response lists the tags on the datastore.

...
    "tags": [
        {
            "key": "Team",
            "value": "E2E"
        },
        {
            "key": "Owner/Requestor",
            "value": "User1"
        },
        {
            "key": "Product",
            "value": "vRA"
        }
    ],
...

Update the tags for the datastore. The following example payload:

Removes the Team and Owner/Requestor keys.
Adds the environment key.
Updates the Product key.

curl -X PATCH \
  "$url/iaas/api/fabric-vsphere-datastore/002e0a62-846d-4fb2-a153-3dcd80e57ba9?apiVersion=$api_version" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $access_token" \
  -d {
    "tags": [
        {
            "key": "environment",
            "value": "dev"
        },
        {
            "key": "Product",
            "value": "saltstack"
        }
    ],
  }' | jq "."