Working with Object Metadata

The VMware Cloud Director API provides a general-purpose facility for associating user-defined metadata with an object. An administrator or object owner can use the metadata link in the object's representation to access an object's metadata.

Object metadata gives cloud operators and tenants a flexible way to associate user-defined properties (name=value pairs) with objects. Object metadata is preserved when objects are copied, and can be included in query filter expressions (see Add a Metadata Filter to a Query).

VMware Cloud Director API Object Metadata Links

The representation of any object that supports metadata includes a link that you can use to retrieve the object's Metadata element. This example shows the metadata link from a VApp element. 
<Link
   rel="down"
   type="application/vnd.vmware.vcloud.metadata+xml" 
   href="https://vcloud.example.com/api/vApp/vapp-7/metadata"/>

The following elements can include a link to a Metadata element.

  • Catalog
  • CatalogItem
  • Disk
  • Media
  • OrgVdcNetwork
  • ProviderVdc
  • ProviderVdcStorageProfile
  • VApp
  • VAppTemplate
  • Vdc
  • VdcStorageProfile
  • Vm

A Metadata element can contain up to 1024 MetadataEntry elements (name=value pairs) that the object owner or an administrator can create, retrieve, update, and delete. It also contains a group of name=value pairs that are under the control of the system administrator.

VMware Cloud Director API Object Metadata Contents

Each MetadataEntry includes a single name=value pair, represented in its Key and TypedValue elements. Key element contents specify key names. A key name is a UTF-8 (Unicode) string encoded as described in RFC3986 (pct-encoded).

The key name must be unique within the scope of the containing Metadata element. Because key names are implicitly qualified by the Domain value of the containing MetadataEntry, the two key names in this example are considered to be unique. 
<Metadata
 ...
   <MetadataEntry>
      <Domain
         visibility="READONLY">SYSTEM</Domain>
      <Key>Foo</Key>
      ...   
   </MetadataEntry>
  <MetadataEntry>
      <Key>Foo</Key>
      ...   
   </MetadataEntry>
</Metadata>
See Access Control for VMware Cloud Director API Object Metadata for more information about the Domain element.

The type of a Value is expressed in the xsi:type attribute of the containing TypedValue element. Values have various restrictions, based on their type.

Table 1. Metadata TypedValue Types
Type Name Restrictions on Value Size of Value
MetadataStringValue UTF-8 character set. Strings longer than 1000 characters cannot be searched for in a query. Depends on length of string.
MetadataNumberValue Must be a signed 8-byte integer. 8 bytes
MetadataDateTimeValue UTC date and time in the format defined by http://www.w3.org/TR/xmlschema-2/#dateTime. For example, 2012-06-18T12:00:00-05:00 8 bytes
MetadataBooleanValue Must be one of: 1, 0, true, false 1 byte

The following rules apply when you update a Metadata element.

  • When the content of a Key element in the update does not match the content of an existing Key element in the same Domain, the MetadataEntry containing that Key is added to the Metadata element.
  • When the content of Key element in the update matches the content of an existing Key element in the same Domain, the MetadataEntry containing that Key is replaced.

Access Control for VMware Cloud Director API Object Metadata

The Domain element of a MetadataEntry controls access to that entry by users and system administrators. There are two access domains, only one of which can be specified explicitly.

GENERAL
This is the default access domain for metadata, and cannot be explicitly specified in a Domain element. A MetadataEntry that does not include a Domain element is considered to be in the GENERAL domain. User access to metadata in the GENERAL domain is controlled by the user's rights to the object to which the Metadata is attached. The owner of the object can create, read, update, or delete any MetadataEntry in the GENERAL domain.
SYSTEM
To be placed in the SYSTEM domain, a MetadataEntry must be created by the system administrator. The system administrator controls whether a MetadataEntry in the SYSTEM domain is visible to tenant users.
SYSTEM
To be placed in the SYSTEM domain, a MetadataEntry must include a Domain element with a value of SYSTEM. Metadata in the SYSTEM domain can be created, updated, and deleted only by a system administrator. User access to metadata in the SYSTEM domain is controlled by the value of the visibility attribute of the Domain element.
Table 2. Domain Visibility Attribute Values
Value Meaning
PRIVATE The metadata is visible to system administrators only.
READONLY the metadata is visible to system administrators and the object owner.
VCENTER
Object metadata in the VCENTER domain can be applied to Vm objects, including Vm objects contained in VAppTemplate objects, by users in roles that have the right vApp: Allow metadata mapping domain to vCenter. The system uses metadata in this domain to deploy virtual machines on specific ESXi hosts that your service provider configures. Your service provider establishes the set of legal values for metadata in this domain. See Specifying Advanced Virtual Machine Settings with ExtraConfig Elements.
Note: Object metadata in the VCENTER domain is not displayed in the VMware Cloud Director Web Console.

VMware Cloud Director API Object Metadata Limits

The following limits apply to VMware Cloud Director API object metadata:
Metadata key size
The contents of a Key element in a MetadataEntry cannot exceed 256 UTF-8 characters.
Metadata size

In VMware Cloud Director 10.2, the size of all Metadata for an object, computed as the sum of all Key and TypedValue UTF-8 strings in all MetadataEntry elements in the GENERAL domain, cannot exceed 128 KB. An additional 16 KB of MetadataEntry content can be created in the SYSTEM domain.

Starting with VMware Cloud Director 10.2.1, the size of all Metadata for an object, computed as the sum of all Key and TypedValue UTF-8 strings in all MetadataEntry elements are configurable. The default size is 128 KB for all domains.

You can configure the size through the configuration properties in the format com .vmware.vcloud.metadata.impl.config.<domain>.<target>. You can change the configuration properties at runtime by using JMX configuration MBean.
com.vmware.vcloud.metadata.impl.config.GENERAL.maxBytesPerEntity = 262144
com.vmware.vcloud.metadata.impl.config.SYSTEM.maxBytesPerEntity = 512
MetadataEntry limit

In VMware Cloud Director 10.2, the total metadata associated with an object cannot exceed 1024 MetadataEntry elements in the GENERAL domain and 128 MetadataEntry elements in the SYSTEM domain.

Starting with VMware Cloud Director 10.2.1, you can configure the total MetadataEntry items associated with an object.

com.vmware.vcloud.metadata.impl.config.GENERAL.maxItemsPerEntity = 1000
com.vmware.vcloud.metadata.impl.config.SYSTEM.maxItemsPerEntity = 50