Nearly every resource in Oracle Cloud Infrastructure can be tagged. Either at creation time or later. And you set/edit/remove those tags via the console, the CLI, or through the APIs.
Read about what/why/how here:
In my blog post above I mention that the bulk API isn't super convenient as it requires JSON inputs and only works on one compartment. This tool simplifies things quite a bit.
It lets you:
- operate on resources anywhere in the tenancy
- specify an update to be made to their tags
- see the changes that would be done (i.e. dry run)
- and optionally, actually make those changes
This tool uses similar command line arguments as many other OCI tools, so it should be familiar to many users.
$ ./ott.py
2024-07-26 13:32:53,702 MainThread INFO ott:<module> -> Parsing command line and configuring...
usage: ott [-h] [-cf CONFIG_FILE] [-cp CONFIG_PROFILE] [-l LOG_FILE] [-d] [-n] [-rg REGIONS] query {set,delete} tag value
ott: error: the following arguments are required: query, action, tag, value
| Option | Meaning |
|---|---|
| -h | Show help |
| -cf CONFIGFILE | Specify the OCI config file |
| -cp PROFILE | Specify the Profile in the OCI config file |
| -l LOG_File | If you want a log file instead of just stdout |
| -d | Enable debug logging - useful for me. Maybe not for you |
| -w | Wait for the work requests to complete before exiting |
| -rg | OTT works one region at a time. If you want to work in multiple you may do that here |
| query | An OCI Resource Search query (see below) |
| action | The action to take - currently only set or delete |
| tag | the tag to update - specified as Namespace.Key |
| value | the value to set the key to |
Remember that whatever you specify for query needs to be quoted. And if "value" contains a string you need to quote that too. So it's probably best to just always quote both. That means something like:
./ott.py 'query Instance resources where compartmentId="ocid1.compartment.oc1..XXX"' set Chris.MyTag "The value I want"
On a Unix or Unix-like system (e.g. Linux, Cloud Shell, or on a Mac) what I showed above works. Or as in this example:
./ott.py 'query all resources where compartmentId="ocid1.compartment.oc1..XXX"' set Oracle-Standard.OwnerEmail [email protected]
Note how I use single quotes (AKA an apostrophe) to enclose the entire query. And then I can use regular quotes (i.e. ") inside there.
On Windows not so much. So you have to do something like this instead:
python ott.py "query all resources where compartmentId="""ocid1.compartment.oc1..XXX""" " set Oracle-Standard.OwnerEmail [email protected]
There's no way I could teach you the query syntax here. Check these docs for the full syntax reference. Or use the samples in Resource Explorer in the OCI console.
But here's a couple to get you started:
query instance resources where compartmentId="ocid1.compartment.oc1..XXX
query all resources where (definedTags.namespace = "Oracle-Standard" && definedTags.key = "OwnerEmail" && definedTags.value = "[email protected]"
e.g. so you can tag their owner
query all resources where compartmentId="ocid1.compartment.oc1..XXXX"
e.g. if you wanted to tag only one kinds of resource
query Compartment resources where compartmentId="ocid1.compartment.oc1..XXX"
query Vnic resources where additionalDetails.subnetId="ocid1.subnet.oc1.iad.XXX"
query IntegrationInstance resources return allAdditionalFields where integrationInstanceType="STANDARD"
query IntegrationInstance resources return allAdditionalFields where integrationInstanceType="STANDARDX"
e.g. so you can change the "OwnerEmail"
query all resources where (definedTags.namespace = "Oracle-Standard" && definedTags.key = "OwnerEmail" && definedTags.value != "[email protected]")
This tool was built for our own use but we find it quite useful. So I'm publishing it for others to benefit from.
These are the known issues
- OTT doesn't support on Freeform tags (because the Bulk Tagging API doesn't)
- We are working with engineering on roadmap for this
- If the bulk API won't include this in the near term I will likely enhance OTT
- some resource types that supposedly work don't
- if you find one please flag it for us and we'll get it fixed
- OTT relies on Search to have updated tag values
- Search is "eventually consistent" with the actual resources in OCI
- when making a large number of changes you should anticipate unnecessary updates or failures to update
As always, I'm happy to take contributions - just do the usual fork, branch, change, pull request, and I'll happily include them!