Manage Tags for a Service Instance

A tag is a key or a key-value pair that you can assign to your Oracle Java Cloud Service instances. You can use tags to organize and categorize your instances, and to search for them.

Topics:

• Create, Assign, and Unassign Tags

• Find Tags and Instances Using Search Expressions

Create, Assign, and Unassign Tags

You can create and assign tags to Oracle Java Cloud Service instances while creating the instances or later. When you no longer need certain tags for an instance, you can unassign them.

To assign tags to an instance or to unassign tags:

1. Navigate to the Overview page for the instance for which you want to assign or unassign tags.
2. Click Manage this instance in the instance name bar at the top.
3. Select Manage Tags or Add Tags.
   If any tags are already assigned, then the menu shows Manage Tags; otherwise, it shows Add Tags.
4. In the Manage Tags dialog box, create and assign the required tags, or unassign tags:
   • In the Assign section, in the Tags field, select the tags that you want to assign to the instance.
   • If the tags that you want to assign don't exist, then select Create and Assign in the Tags field, and click just above the field. Enter the required new tags in the Enter New Tags field.
   • To unassign a tag, in the Unassign section, look for the tag that you want to unassign, and click the X button next to the tag.

     Note:

     You might see one or more tags with the key starting with ora_. Such tags are auto-assigned and used internally. You can’t assign or unassign them.
   • To exit without changing any tag assignments for the instance, click Cancel.
5. After assigning and unassigning tags, click OK for the tag assignments to take effect.

List Tags

You can get the details of all the tags available in the account as well as the tags assigned to a service instance by using the REST API.

For each tag, the API request returns the key, the value if it exists, and a list of the instances that are assigned the tag. See Tags and Assignments in REST API for Oracle Java Cloud Service.

Find Tags and Instances Using Search Expressions

A tag is an arbitrary key or a key-value pair that you can create and assign to your Oracle Java Cloud Service instances. You can use tags to organize and categorize your instances, and to search for them. Over time, you might create dozens of tags, and you might assign one or more tags to your instances. To search for specific tags and to find instances that are assigned specific tags, you can use filtering expressions.

Search for Instances with Tags

From the Instances page of the web console, select Tags, and then enter a search expression in the Search field.

For example, you can search for the instances that are assigned a tag with the key env and any value starting with dev (example: env:dev1, env:dev2), by entering the search expression 'env':'dev%'.

Similarly, when you use the REST API to find tags or to find instances that are assigned specific tags, you can filter the results by appending the optional tagFilter=expression query parameter to the REST endpoint URL.

• To find specific tags: GET paas/api/v1.1/tags/{identity_domain}/tags?tagFilter={expression}
• To get a list of instances that are assigned specific tags: GET paas/api/v1.1/instancemgmt/{identity_domain}/instances?tagFilter={expression}

Syntax and Rules for Building Tag-Search Expressions

• When using cURL to send tag-search API requests, enclose the URL in double quotation marks.

  Example:

  curl -s -u username:password -H "X-ID-TENANT-NAME:acme" "restEndpointURL/paas/api/v1.1/instancemgmt/acme/instances?tagFilter='env'"

  This request returns all the tags that have the key env.

• Enclose each key and each value in single quotation marks. And use a colon (:) to indicate a key:value pair.

  Examples:

  'env'
  'env':'dev'

• You can include keys or key:value pairs in a tag-filtering expression.

  Sample Expression	Description	Sample Search Result
  'env'	Finds the tags with the key env, or the instances that are assigned the tags with that key.	The following tags, or the instances that are assigned any of these tags: env:dev env:qa
  'env':'dev'	Finds the tag with the key env and the value dev, or the instances that are assigned that tag.	The following tag, or the instances that are assigned this tag env:dev

• You can build a tag-search expression by using actual keys and key values, or by using the following wildcard characters.

  % (percent sign): Matches any number of characters.

  _ (underscore): Matches one character.

  Sample Expression	Description	Sample Search Result
  'env':'dev%'	Finds the tags with the key env and a value starting with dev, or the instances that are assigned such tags. Note: When you use curl or any command-line tool to send tag-search REST API requests, encode the percent sign as %25.	The following tags, or the instances that are assigned any of these tags: env:dev env:dev1
  'env':'dev_'	Finds the tags with the key env and the value devX where X can be any one character, or finds the instances that are assigned such tags.	The following tags, or the instances that are assigned any of these tags: env:dev1 env:dev2

• To use a single quotation mark ('), the percent sign (%), or the underscore (_) as a literal character in a search expression, escape the character by prefixing a backslash (\).

  Sample Expression	Description	Sample Search Result
  'env':'dev\_%'	Finds the tags with the key env and a value starting with dev_, or the instances that are assigned such tags.	The following tags, or the instances that are assigned any of these tags: env:dev_1 env:dev_admin

• You can use the Boolean operators AND, OR, and NOT in your search expressions:

  Sample Expression	Description	Sample Search Result
  'env' OR 'owner'	Finds the tags with the key env or the key owner, or the instances that are assigned either of those keys.	The following tags, or the instances that are assigned any of these tags: env:dev owner:admin
  'env' AND 'owner'	Finds the instances that are assigned the tags env and owner. Note: This expression won’t return any results when used to search for tags, because a tag can have only one key.	The instances that are assigned all of the following tags: env:dev owner:admin
  NOT 'env’	Finds the tags that have a key other than env, or the instances that are assigned such tags. Note: Untagged instances as well will satisfy this search expression.	The following tags, or the instances that are assigned any of these tags or no tags: owner:admin department
  ('env' OR 'owner') AND NOT 'department'	Finds the tags that have the key env or the key owner but not the key department, or the instances that are assigned such tags.	The following tags, or the instances that are assigned any of these tags: env:dev owner:admin

Delete Tags

You can delete tags by using the REST API.

See Tags and Assignments in REST API for Oracle Java Cloud Service.