OCI CLI: Query By Tags

Tagging your resources is a must. Not only for billing purposes, but also for staying organized and knowing who to yell at when something goes wrong. 😁

We typically use a set of defined tags to track our resources. Defined tags have a tag namespace, which is the overarching name for the various tags. The tag key is the name of the tag, and the tag value is the value of the tag.

Example: Namespace: required_tags. Keys: contact_email, project, purpose
The tags are represented in JSON format and look something like this:

"defined_tags" : {
     "required_tags": {
          "contact_email": "john.doe@example.com",
          "project": "Cool Web Application",
          "purpose": "Testing web server"
      }
}

Now you may want to find all the resources that have these particular tags. To do this quickly, we’ll use a Bash script to invoke the OCI CLI:

#!/bin/bash

if [ -z "$1" ] || [ -z "$2" ] || [ -z "$3" ]
  then
    echo "Usage:"
    echo "  " ${0##*/} "<tag namespace> <tag key> <tag value>"
    exit
fi

oci search resource structured-search \
  --query-text "query all resources where (definedTags.namespace = '$1' \
  && definedTags.key = '$2' \
  && definedTags.value = '$3')" \
  --output table \
  --query "data.items[*] | \
  sort_by(@,&\"resource-type\") \
  [].{Name:\"display-name\",Type:\"resource-type\",ID:identifier,AD:\"availability-domain\"}"

The output looks something like this:

+----------------------+--------------------------------+------------------------------------+--------------+
| AD                   | ID                             | Name                               | Type         |
+----------------------+--------------------------------+------------------------------------+--------------+
| FfLG:US-ASHBURN-AD-2 | ocid1.bootvolume.oc1.iad.abc   | DataNode4 (Boot Volume)            | BootVolume   |
| FfLG:US-ASHBURN-AD-1 | ocid1.bootvolume.oc1.iad.abc   | DataNode2 (Boot Volume)            | BootVolume   |
| FfLG:US-ASHBURN-AD-2 | ocid1.bootvolume.oc1.iad.abc   | DataNode3 (Boot Volume)            | BootVolume   |
| FfLG:US-ASHBURN-AD-1 | ocid1.bootvolume.oc1.iad.abc   | DataNode1 (Boot Volume)            | BootVolume   |
| FfLG:US-ASHBURN-AD-1 | ocid1.bootvolume.oc1.iad.abc   | MasterNode1 (Boot Volume)          | BootVolume   |
| FfLG:US-ASHBURN-AD-2 | ocid1.bootvolume.oc1.iad.abc   | MasterNode2 (Boot Volume)          | BootVolume   |
| FfLG:US-ASHBURN-AD-3 | ocid1.bootvolume.oc1.iad.abc   | MasterNode3 (Boot Volume)          | BootVolume   |
| FfLG:US-ASHBURN-AD-1 | ocid1.bootvolume.oc1.iad.abc   | BastionHost (Boot Volume)          | BootVolume   |
| FfLG:US-ASHBURN-AD-3 | ocid1.instance.oc1.iad.abc     | MasterNode3                        | Instance     |
| FfLG:US-ASHBURN-AD-2 | ocid1.instance.oc1.iad.abc     | DataNode3                          | Instance     |
| FfLG:US-ASHBURN-AD-2 | ocid1.instance.oc1.iad.abc     | MasterNode2                        | Instance     |
| FfLG:US-ASHBURN-AD-2 | ocid1.instance.oc1.iad.abc     | DataNode4                          | Instance     |
| FfLG:US-ASHBURN-AD-1 | ocid1.instance.oc1.iad.abc     | DataNode1                          | Instance     |
| FfLG:US-ASHBURN-AD-1 | ocid1.instance.oc1.iad.abc     | MasterNode1                        | Instance     |
| FfLG:US-ASHBURN-AD-1 | ocid1.instance.oc1.iad.abc     | DataNode2                          | Instance     |
| FfLG:US-ASHBURN-AD-1 | ocid1.instance.oc1.iad.abc     | BastionHost                        | Instance     |
| None                 | ocid1.routetable.oc1.iad.abc   | OCI_ES_RTB                         | RouteTable   |
| None                 | ocid1.routetable.oc1.iad.abc   | OCI_PUB_RTB                        | RouteTable   |
| None                 | ocid1.routetable.oc1.iad.abc   | Default Route Table for MY_VCN     | RouteTable   |
| None                 | ocid1.securitylist.oc1.iad.abc | PrivSecList                        | SecurityList |
| None                 | ocid1.securitylist.oc1.iad.abc | LBSecList                          | SecurityList |
| None                 | ocid1.securitylist.oc1.iad.abc | BastionSecList                     | SecurityList |
| None                 | ocid1.securitylist.oc1.iad.abc | Default Security List for MY_VCN   | SecurityList |
| FfLG:US-ASHBURN-AD-3 | ocid1.subnet.oc1.iad.abc       | PrivateSubnetAD3                   | Subnet       |
| FfLG:US-ASHBURN-AD-2 | ocid1.subnet.oc1.iad.abc       | PrivateSubnetAD2                   | Subnet       |
| FfLG:US-ASHBURN-AD-1 | ocid1.subnet.oc1.iad.abc       | PrivateSubnetAD1                   | Subnet       |
| FfLG:US-ASHBURN-AD-2 | ocid1.subnet.oc1.iad.abc       | LBSubnetAD2                        | Subnet       |
| FfLG:US-ASHBURN-AD-1 | ocid1.subnet.oc1.iad.abc       | LBSubnetAD1                        | Subnet       |
| FfLG:US-ASHBURN-AD-1 | ocid1.subnet.oc1.iad.abc       | BastionSubnetAD1                   | Subnet       |
| None                 | ocid1.vcn.oc1.iad.abc          | MY_VCN                             | Vcn          |
+----------------------+--------------------------------+------------------------------------+--------------+

To search by freeform tags use

#!/bin/bash

if [ -z "$1" ] || [ -z "$2" ]
  then
    echo "Usage:"
    echo "  " ${0##*/} "<tag key> <tag value>"
    exit
fi

oci search resource structured-search \
  --query-text "query all resources where (    \
                   freeformTags.key   = '$1'   \
                && freeformTags.value = '$2')" \
  --output table \
  --query "data.items[*] | \
  sort_by(@,&\"resource-type\") \
  [].{Name:\"display-name\",Type:\"resource-type\",ID:identifier,AD:\"availability-domain\",State:\"lifecycle-state\"}"

Please give it a try and leave a comment.