Resource Tags¶

Resource tags allows you to add key-value metadata to both storage resources and VSAs to group related resources together. For example we might have storages and VSAs situated in different locations, and we want to tag these resources to denote which ones are located in one region and which ones are in onther region.

The resource tags are denoted as resourceTag in the resource documents and is a data type that can consist of one to many K/V-pairs where the key is in the form [A-Za-z][A-Za-z-]*[A-Za-z] and value is a comma-separated list.

For storages there is an inheritance from storage groups to storages, and then from storages to storage methods. So by adding a storage to a storage group with resource tags the tags are inherited down to both the storage and any storage method.

A storage can override resourceTag values inherited from storage group(s) by adding matching key directly on storage. A storage method can override resourceTag values inherited from storage by adding matching key on storage method.

Adding resource tags to VSA¶

Resource tags for VSAs are configured by adding the resourceTags to the agent.conf for the VSA and a read upon VSA startup.

Example:

resourceTag.location = Stockholm

This will then be reflected in the VSAs resource document

Example:

<VXAListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  ..
  <vxa>
    <uuid>e5844fdb-9bfb-4f25-a689-72349a34507a</uuid>
    ..
    <resourceTag>
      <key>location</key>
      <value>Stockholm</value>
    </resourceTag>
  </vxa>
  ..
 </VXAListDocument>

Adding resource tags to storage¶

Resource tags for storage groups, storages or storage methods are added by providing the resourceTag in either the StorageGroup-, Storage- or StorageMethodDocument.

Example for a storage:

POST /storage
Content-Type: application/xml

<StorageDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <type>LOCAL</type>
  <capacity>150000000000</capacity>
  <method>
    <uri>file:///mnt/ingest/</uri>
    <read>true</read>
    <write>true</write>
    <browse>true</browse>
  </method>
  <lowWatermarkPercentage>90</lowWatermarkPercentage>
  <highWatermarkPercentage>75</highWatermarkPercentage>
  <showImportables>true</showImportables>
  <resourceTag>
    <key>location</key>
    <value>Stockholm</value>
  </resourceTag>
</StorageDocument>

Once the storage has been added we can see that both the storage and the storage method have the resourceTag set and where it has been inherited from.

<StorageDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1</id>
  <state>NONE</state>
  <priority>MEDIUM</priority>
  <type>LOCAL</type>
  ..
  <method>
    <id>VX-1</id>
    <uri>file:///mnt/ingest/</uri>
    <read>true</read>
    <write>true</write>
    <browse>true</browse>
    ..
    <resourceTag sourceName="VX-1" sourceType="storage">
      <key>location</key>
      <value>Stockholm</value>
    </resourceTag>
  </method>
  <metadata/>
  ..
  <showImportables>true</showImportables>
  <resourceTag>
    <key>location</key>
    <value>Stockholm</value>
  </resourceTag>
</StorageDocument>

Removing resource tags¶

Resource tags are removed by posting an empty value together with the resource key which we want to update.

Example:

POST /storage
Content-Type: application/xml

<StorageDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <type>LOCAL</type>
  <capacity>150000000000</capacity>
  <method>
    <uri>file:///mnt/ingest/</uri>
    <read>true</read>
    <write>true</write>
    <browse>true</browse>
  </method>
  <lowWatermarkPercentage>90</lowWatermarkPercentage>
  <highWatermarkPercentage>75</highWatermarkPercentage>
  <showImportables>true</showImportables>
  <resourceTag>
    <key>location</key>
    <value></value>
  </resourceTag>
</StorageDocument>

Using resource tags in jobs¶

For most VidiCore jobs making use of a transcoder or a VSA, the resourceTag parameter can be used to restrict the source file storage and/or transcoders/VSAs used in the jobs.

Note

Resources that do NOT have a resourceTag set will always be considered as candidates for a job.

Changed in version 25.2.4: Whether a resource having one or more resourceTag keys will be considered as candidate depends on the resourceTagRelaxedMatch configuration property.

In strict matching mode (resourceTagRelaxedMatch is false) only the storages or transcoders that do not have a resource tag set, or the ones containing resource tags matching the criteria will be used in the job.

In relaxed matching mode (resourceTagRelaxedMatch is true) only the storages or trancoders will be used in a job if the resourceTag query parameter results in a match or if the resourceTag query parameter does not refer to any of the resourceTag keys present on the resource.

For example, consider an item transcode job is started with criteria like

POST /item/(item-id)/transcode?resourceTag=location:stockhom OR location:berlin

and assume the resources have tags set like below:

Storage:

VX-1,     no tags set
VX-2,     tier:prod
VX-3,     location:europe,stockholm tier:prod
VX-4,     location:europe,berlin tier:prod

Transcoder:

VX-6,     no tags set
VX-7,     tier:prod
VX-8,     location:europe,stockholm tier:prod
VX-9,     location:europe,berlin tier:prod

In strict matching mode (resourceTagRelaxedMatch is false) storage VX-1, VX-3, VX-4 and transcoder VX-6, VX-8 VX-9 would the eligible for this job. Storage VX-2 and transcoder VX-7 are not eligible as the criterion location:stockhom OR location:berlin cannot be fulfilled.

In relaxed matching mode (resourceTagRelaxedMatch is true) storage VX-1, VX-2, VX-3, VX-4 and transcoder VX-6, VX-7, VX-8 VX-9 would the eligible for this job. Storage VX-2 and transcoder VX-7 are eligible as the resource tag location is not set on them.

If no transcoder matches the desired criteria, a TranscoderResourceTagProblem will be created, and the job will be put into a WAITING state until a transcoder matching the criteria is available.