2.4. Metadata

Every resource agent must describe its own purpose and supported parameters in a set of XML metadata. This metadata is used by cluster management applications for on-line help, and resource agent man pages are generated from it as well. The following is a fictitious set of metadata from an imaginary resource agent:

<?xml version="1.0"?>
<!DOCTYPE resource-agent SYSTEM "ra-api-1.dtd">
<resource-agent name="foobar" version="0.1">
  <version>0.1</version>
  <longdesc lang="en">
This is a fictitious example resource agent written for the
OCF Resource Agent Developers Guide.
  </longdesc>
  <shortdesc lang="en">Example resource agent
  for budding OCF RA developers</shortdesc>
  <parameters>
    <parameter name="eggs" unique="0" required="1">
      <longdesc lang="en">
      Number of eggs, an example numeric parameter
      </longdesc>
      <shortdesc lang="en">Number of eggs</shortdesc>
      <content type="integer"/>
    </parameter>
    <parameter name="superfrobnicate" unique="0" required="0">
      <longdesc lang="en">
      Enable superfrobnication, an example boolean parameter
      </longdesc>
      <shortdesc lang="en">Enable superfrobnication</shortdesc>
      <content type="boolean" default="false"/>
    </parameter>
    <parameter name="datadir" unique="0" required="1">
      <longdesc lang="en">
      Data directory, an example string parameter
      </longdesc>
      <shortdesc lang="en">Data directory</shortdesc>
      <content type="string"/>
    </parameter>
  </parameters>
  <actions>
    <action name="start"        timeout="20" />
    <action name="stop"         timeout="20" />
    <action name="monitor"      timeout="20"
                                interval="10" depth="0" />
    <action name="reload"       timeout="20" />
    <action name="migrate_to"   timeout="20" />
    <action name="migrate_from" timeout="20" />
    <action name="meta-data"    timeout="5" />
    <action name="validate-all"   timeout="20" />
  </actions>
</resource-agent>

The resource-agent element, of which there must only be one per resource agent, defines the resource agent name and version.

The longdesc and shortdesc elements in resource-agent provide a long and short description of the resource agent’s functionality. While shortdesc is a one-line description of what the resource agent does and is usually used in terse listings, longdesc should give a full-blown description of the resource agent in as much detail as possible.

The parameters element describes the resource agent parameters, and should hold any number of parameter children — one for each parameter that the resource agent supports.

Every parameter should, like the resource-agent as a whole, come with a shortdesc and a longdesc, and also a content child that describes the parameter’s expected content. parameter supports the following attributes:

On the content element, there may be two attributes:

The actions list defines the actions that the resource agent advertises as supported.

Every action should list its own timeout value. This is a hint to the user what minimal timeout should be configured for the action. This is meant to cater for the fact that some resources are quick to start and stop (IP addresses or filesystems, for example), some may take several minutes to do so (such as databases).

In addition, recurring actions (such as monitor) should also specify a recommended minimum interval, which is the time between two consecutive invocations of the same action. Like timeout, this value does not constitute a default — it is merely a hint for the user which action interval to configure, at minimum.