Skip to content

Commit

Permalink
ra/1.1: bring in proposed changes from next/
Browse files Browse the repository at this point in the history 
The only (slight) differences from "next/" is that this uses "1.1" instead of
"next" in URLs, and "status of this memo" is different (i.e. this is the
proposed draft of 1.1 standard).
  • Loading branch information
@kgaillot
kgaillot committed Mar 22, 2021
1 parent d1113ec commit f859ffc
Show file tree
Hide file tree
Showing 3 changed files with 634 additions and 312 deletions.
72 changes: 55 additions & 17 deletions ra/1.1/ra-api.rng
View file
Expand Up @@ -7,21 +7,53 @@

<element name="version"> <text /> </element>

<zeroOrMore><element name="longdesc">
<ref name="description" />
</element></zeroOrMore>

<zeroOrMore><element name="shortdesc">
<ref name="description" />
</element></zeroOrMore>

<element name="parameters"> <oneOrMore>
<element name="parameter">
<attribute name="name" />
<optional>
<attribute name="unique-group" />
</optional>
<optional>
<!-- "unique" is deprecated -->
<attribute name="unique"> <ref name="boolean-values" /> </attribute>
</optional>
<optional>
<attribute name="required"> <ref name="boolean-values" /> </attribute>
</optional>
<optional>
<attribute name="reloadable"> <ref name="boolean-values" /> </attribute>
</optional>

<optional><element name="deprecated">
<empty />
<interleave>
<zeroOrMore>
<element name="replaced-with">
<attribute name="name"> <text /> </attribute>
</element>
</zeroOrMore>
<zeroOrMore>
<element name="desc">
<ref name="description" />
</element>
</zeroOrMore>
</interleave>
</element></optional>

<oneOrMore> <element name="longdesc">
<attribute name="lang" />
<ref name="anyElement" />
<ref name="description" />
</element> </oneOrMore>

<oneOrMore> <element name="shortdesc">
<attribute name="lang" />
<ref name="anyElement" />
<ref name="description" />
</element> </oneOrMore>

<element name="content">
Expand All @@ -33,6 +65,16 @@
<value>integer</value>
</choice>
</attribute>
<group>
<attribute name="type">
<value>select</value>
</attribute>
<oneOrMore>
<element name="option">
<attribute name="value" />
</element>
</oneOrMore>
</group>
</choice>
<optional>
<attribute name="default"> <text /> </attribute>
Expand All @@ -43,27 +85,18 @@

<element name="actions"> <oneOrMore>
<element name="action">
<attribute name="name">
<choice>
<value>start</value>
<value>stop</value>
<value>recover</value>
<value>status</value>
<value>reload</value>
<value>meta-data</value>
<value>verify-all</value>
</choice>
</attribute>
<attribute name="name" />
<attribute name="timeout" />
<optional><attribute name="interval" /></optional>
<optional><attribute name="start-delay" /></optional>
<optional><attribute name="depth" /></optional>
<optional><attribute name="role" /></optional>
</element>
</oneOrMore> </element>
<element name="special">
<optional><element name="special">
<attribute name="tag" />
<ref name="anyElement" />
</element>
</element></optional>
</element></start>

<define name="boolean-values">
Expand All @@ -73,6 +106,11 @@
</choice>
</define>

<define name="description">
<attribute name="lang" />
<ref name="anyElement" />
</define>

<define name="any">
<zeroOrMore>
<choice>
Expand Down
220 changes: 156 additions & 64 deletions ra/1.1/ra-metadata-example.xml
View file
@@ -1,103 +1,195 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- This is example meta-data for an OCF Resource Agent. It is informational
only and not considered part of the standard.
-->

<!-- The root element gives the name of the resource agent, which should be
identical to the resource agent's file name. The name is provided here
because meta-data may be obtained alone, without the resource agent file.
<!-- Root element: give the name of the Resource agent -->
<resource-agent name="Filesystem" version="FailSafe 1.0.4">
The root element may optionally contain the resource agent's version,
which is a free-form text field.
-->
<resource-agent name="example-daemon" version="1.0.4">

<!-- Version number of the standard this complies with -->
<!-- Version number of the OCF Resource Agent API this agent complies with -->
<version>1.1</version>

<!-- List all the instance parameters the RA supports or requires. -->
<!-- A description of what the agent does, suitable for showing to a user -->
<longdesc lang="en">
This resource agent manages the example daemon, which does many wondrous
things.
</longdesc>

<!-- All instance parameters the RA supports must be listed in meta-data -->
<parameters>

<!-- Note that parameters flagged with 'unique' must be unique; ie no
other resource instance of this resource type may have the same set
of unique parameters.
-->

<parameter name="Mountpoint" unique="1">
<!-- This is the long, helpful description of what the parameter is all
about. A user interface might display it to the user if he asks for
elaborate help with an option, and it would obviously also provide
examples etc.
You can have multiple ones with different "lang" attributes, but this is
not required.
<!-- The combination of parameters flagged with the same "unique-group"
attribute should be unique. That is, no other instance of this resource
type should have the same set of these parameters. This is a hint to RMs
and other tools, which may, but are not required to, enforce it.
-->

<!-- These attributes indicate that each instance of this agent must specify a
value for the "config-file" parameter, and (since no other parameter uses
the same unique group) the value should be unique across all instances.
-->
<parameter name="config-file" unique-group="config-file" required="1">

<!-- A helpful, extended description of the parameter. A user interface might
display it to the user when asked for help with an option. You may include
examples, etc.
Each parameter must have at least one longdesc, and may have multiple with
different "lang" attributes.
-->
<longdesc lang="en">
The full path to the example daemon configuration file.
</longdesc>

<!-- A brief description of the parameter's purpose. A user interface might
display it to the user as a tooltip or similar.
Each parameter must have at least one shortdesc, and may have multiple with
different "lang" attributes.
-->
<shortdesc lang="en">Configuration filename</shortdesc>

<!-- Allowed values, and optionally the default value. Type may be boolean,
string, integer, or select; with select, this must have "option" child
elements specifying each allowed value.
-->
<content type="string"/>

</parameter>

<!-- Since the "ip" and "port" parameters share the same unique group, the
combination of the two should be unique across all instances of this
resource type.
If required is 0 or unspecified, an instance of this resource type may
omit this parameter (typically, a default value will be used in that
case).
-->
<parameter name="ip" unique-group="address">
<longdesc lang="en">
The resource name is the directory where the filesystem will be actually
mounted. Please make sure it exists.
The local IP address the example daemon should bind to and accept requests on.
If omitted, the wildcard address will be used.
</longdesc>
<shortdesc lang="en">IP address</shortdesc>
<content type="string" default="*"/>
</parameter>

<!-- The shortdesc may be displayed by the resource manager as a tooltip or
equivalent -->
<shortdesc lang="en">Mountpoint</shortdesc>
<parameter name="port" unique-group="address">
<longdesc lang="en">
The port number the example daemon should accept requests on.
</longdesc>
<shortdesc lang="en">Port number</shortdesc>
<content type="string" default="65535"/>
</parameter>

<!-- Further definition of the content -->
<content type="string" default="/mnt" />
<!-- Example of a parameter that is reloadable and uses select. Marking "mode"
as reloadable implies that a change in it can be made effective by calling
the agent's "reload-agent" action, without requiring a restart of
example-daemon. As an example, perhaps the "reload-agent" action contacts
the daemon via a REST API to change its mode. This constrasts with the
"reload" action, which is meant to reload the service itself, usually
after changes to its native configuration (for example, many daemons will
reload a configuration file after receiving a signal).
If no unique group is specified, different instances of this
resource type may have the same value for this parameter.
-->
<parameter name="mode" reloadable="1">
<longdesc lang="en">
The mode the example daemon should operate in. Allowed values are "dry-run" and
"live".
</longdesc>
<shortdesc lang="en">Run mode</shortdesc>
<content type="select" default="live">
<option value="dry-run" />
<option value="live" />
</content>
</parameter>

<parameter name="Device" unique="1">
<!-- Example of a deprecated parameter with no replacement -->
<parameter name="archaic1">
<deprecated />
<longdesc lang="en">
When mounting a filesystem on a specific mountpoint, you have to specify which
device should be mounted; this will usually be similiar to /dev/sda1 or
/dev/volumegroup/logicalvolume when using LVM.
This parameter is no longer used.
</longdesc>
<shortdesc lang="en">Device to be mounted</shortdesc>
<content type="string" default="/dev/"/>
<shortdesc lang="en">Unused</shortdesc>
<content type="string" />
</parameter>

<parameter name="FSType">
<!-- Example of a deprecated parameter with a replacement -->
<parameter name="cf">
<deprecated>
<replaced-with name="config-file"/>
</deprecated>
<longdesc lang="en">
You should chose a journaled filesystem for the shared storage to ensure that
the filesystem remains consistent and that it can be mounted without an
expensive fsck run; recommendations include reiserfs, ext3 and XFS.
The full path to the example daemon configuration file.
</longdesc>
<shortdesc lang="en">Type of the filesystem</shortdesc>
<content type="string" default="reiserfs"/>
<shortdesc lang="en">Configuration filename</shortdesc>
<content type="string" />
</parameter>

<parameter name="mount_options">
<!-- Example of a deprecated parameter with a description of why the parameter
was deprecated (in multiple translations).
-->
<parameter name="foo">
<deprecated>
<replaced-with name="mode"/>
<desc lang="en">Don't use foo, it's bad.</desc>
<desc lang="cs">Nepoužívej foo, sic to schytáš</desc>
</deprecated>
<longdesc lang="en">
The mount options used for mounting a filesystem; normally this is set to
defaults, but you may want to modify this if you require a read-only
mount or something similar.
Whether the example daemon should operate with foo factor
</longdesc>
<shortdesc lang="en">Mount options for this filesystem</shortdesc>
<content type="string" default="defaults" />
<shortdesc lang="en">Foo factor</shortdesc>
<content type="string" />
</parameter>

</parameters>

<!-- List the actions supported by the RA -->
<!-- All actions supported by the RA must be listed in meta-data. Timeouts are
given in seconds (or s, m, h, d suffix with the usual meanings) and should
be a reasonable hint how long a certain action might take in the worst
case.
-->
<actions>
<!-- Valid actions: start, stop, recover, status, reload, verify-all
The timeout is given in seconds (or s, m, h, d postfix and their
usual meanings) and should be a reasonable _hint_ to the RM how
long a certain action might take in the worst case.
-->
<action name="start" timeout="2m30s" />

<!-- The OCF RA API mandates support for start, stop, monitor, and meta-data
-->
<action name="start" timeout="2m" />
<action name="stop" timeout="100" />
<action name="meta-data" timeout="5" />

<!-- Monitor actions should specify an interval, which is a hint for how often
the service status should be polled. Monitor may optionally support
multiple depths and/or roles, in which case a separate entry with a unique
interval should be given for each.
-->
<action name="monitor" depth="0" timeout="20" interval="10" />
<action name="monitor" depth="10" timeout="60" interval="1h" role="promoted" start-delay="1m" />
<action name="monitor" depth="20" timeout="2m" interval="1d" start-delay="2m" />

<!-- The OCF RA API specifies several actions that may optionally be supported
but should have a specific meaning if so.
-->
<action name="recover" timeout="150" />
<!-- In what intervals the RM should poll the RA for status; and how early
after the start of the RA is should start. Again, this are just
_defaults_ and can be overridden by the RM. -->
<action name="status" depth="0" timeout="20" interval="10" start-delay="1m" />
<action name="status" depth="10" timeout="60" interval="1h" start-delay="5m" />
<action name="status" depth="20" timeout="2m" interval="1d" start-delay="1d" />
<action name="reload" timeout="60" />
<action name="meta-data" timeout="5" />
<!-- As with all not mandatory actions, this one is only listed if supported
-->
<action name="verify-all" timeout="30" />
<action name="reload-agent" timeout="10" />
<action name="validate-all" timeout="30" />

<!-- Agents may also support arbitrary other actions as desired -->
<action name="anything" timeout="15" />

</actions>

<!-- Vendor specific attributes; as the content _inside_ the special tag is
obviously not covered by the RA-API DTD, it will not validate, but oh
well...
-->
<!-- Vendors may add their own custom information inside a "special" element,
which must have a "tag" attribute, and may contain any arbitrary content.
-->
<special tag="FailSafe">
<Ordering>403</Ordering>
</special>
Expand Down

0 comments on commit f859ffc

Please sign in to comment.