diff --git a/ra/1.1/ra-api.rng b/ra/1.1/ra-api.rng index a288997..154a43f 100644 --- a/ra/1.1/ra-api.rng +++ b/ra/1.1/ra-api.rng @@ -1,103 +1,141 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + - - + boolean string integer + + + select + + + + + + + - - - start - stop - recover - status - reload - meta-data - verify-all - - + + - + - + 0 1 + + + + + diff --git a/ra/1.1/ra-metadata-example.xml b/ra/1.1/ra-metadata-example.xml index bb7e38d..adf8a4f 100644 --- a/ra/1.1/ra-metadata-example.xml +++ b/ra/1.1/ra-metadata-example.xml @@ -1,105 +1,197 @@ + + + - + The root element may optionally contain the resource agent's version, + which is a free-form text field. +--> + - + 1.1 - + + + This resource agent manages the example daemon, which does many wondrous + things. + + + - - - - + + + + + + +The full path to the example daemon configuration file. + + + +Configuration filename + + + + + + + + -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. +IP address + + - -Mountpoint + + +The port number the example daemon should accept requests on. + +Port number + + - - + + + +The mode the example daemon should operate in. Allowed values are "dry-run" and +"live". + +Run mode + + - + + + -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. -Device to be mounted - +Unused + - + + + + + -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. -Type of the filesystem - +Configuration filename + - + + + + + Don't use foo, it's bad. + Nepoužívej foo, sic to schytáš + -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 -Mount options for this filesystem - +Foo factor + - + - - + + + + + + + + + + + - - - - - - - + + + + + - + 403 diff --git a/ra/1.1/resource-agent-api.md b/ra/1.1/resource-agent-api.md index ff4c6d2..d97e9c9 100644 --- a/ra/1.1/resource-agent-api.md +++ b/ra/1.1/resource-agent-api.md @@ -1,498 +1,690 @@ -**DRAFT - DRAFT - DRAFT** +# Open Cluster Framework Resource Agent API -**JOIN THE developers@clusterlabs.org MAILING LIST AND FOLLOW PULL REQUESTS -AT https://github.com/ClusterLabs/OCF-spec/ TO DISCUSS CHANGES** +URL: https://github.com/ClusterLabs/OCF-spec/blob/master/ra/1.1/resource-agent-api.md -# Open Clustering Framework Resource Agent API -Editor: Lars Marowsky-Brée +## Abstract -URL: https://github.com/ClusterLabs/OCF-spec/blob/master/ra/1.1/resource-agent-api.md +The Open Cluster Framework Resource Agent (RA) API provides an abstraction +layer between diverse, computer-hosted resources and diverse types of software +managing such resources in a clustered environment. -## License +The RA API allows resources to be managed without any modification to the +actual resource providers, by providing a standardized interface to common +management tasks. It also allows (but does not require) RAs to be designed +without consideration of specific software that might invoke them, and thus +shared by any such software. - Copyright (c) 2002, 2018 Lars Marowsky-Brée. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with no - Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A - copy of the license can be found at http://www.gnu.org/licenses/fdl.txt. +## Status of This Memo -## Abstract +This is an Open Cluster Framework (OCF) document produced by ClusterLabs +. -Resource Agents (RA) are the middle layer between the Resource Manager -(RM) and the actual resources being managed. They aim to integrate the -resource type with the RM without any modifications to the actual -resource provider itself, by encapsulating it carefully and providing -generic methods (actions) to operate on them. +This document is a proposed draft of the 1.1 version of the OCF RA API. It has +not yet been adopted as a standard, and should be considered for discussion +purposes only. -The RAs are obviously very specific to the resource type they operate -on, however there is no reason why they should be specific to a -particular RM. -The API described in this document should be general enough that a -compliant Resource Agent can be used by all existing resource managers / -switch-over systems who chose to implement this API either exclusively -or in addition to their existing one. +## Copyright Notice +Originally Copyright 2002,2018 Lars Marowsky-Brée +Later changes copyright 2020-2021 the Open Cluster Framework project contributors -### Scope +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license can be found at https://www.gnu.org/licenses/fdl.txt. -This document describes a common API for the RM to call the RAs so the -pool of available RAs can be shared by the different clustering -solutions. -It does NOT define any libraries or helper functions which RAs might share -with regard to common functionality like external command execution, cluster -logging et cetera, as these are NOT specific to RA and are defined in the -respective standards. +## Terms Used in This Document +### Resource -### API version described +A _resource_, also known as a _resource instance_, is a logical entity that +provides a particular computer-hosted service. Examples of resources include a +disk volume, a network address, a web server, or a virtual machine. -This document currently describes version 1.1 of the API. +### Cluster +A _cluster_ is a collection of one or more computers under common +administration running a set of resources. -## Terms used in this document +### Resource Manager -### "Resource" +A _resource manager_ (RM), also known as a _cluster resource manager_ (CRM), +is software that manages resources in a cluster. -A single physical or logical entity that provides a service to clients or -other resources. For example, a resource can be a single disk volume, a -particular network address, or an application such as a web server. A resource -is generally available for use over time on two or more nodes in a cluster, -although it usually can be allocated to only one node at any given time. +### Resource Type -Resources are identified by a name that must be unique to the particular -resource type. This is any name chosen by the administrator to identify -the resource instance and passed to the RA as a special environment -variable. +A _resource type_ is a name indicating the service provided by a resource. This +name should be suitable for use as a file name. -A resource may also have instance parameters which provide additional -information required for Resource Agent to control the resource. +A resource type beginning with a leading dot (.) is a hint to RMs and other +tools that the resource type should be omitted from lists provided in response +to user queries. +### Resource Agent -### "Resource types" +A _resource agent_ (RA) is a software application implementing the RA API for a +particular resource type. An RA allows a resource manager to perform specific +management tasks for resource instances. -A resource type represents a set of resources which share a common set of -instance parameters and a common set of actions which can be performed on -resource of the given type. +### Resource Agent Provider -The resource type name is chosen by the provider of the RA. +A _resource agent provider_ is an entity supplying one or more resource agents +for installation on cluster hosts. Each provider should have a unique name +suitable for use as a file system directory name. +A resource agent provider beginning with a leading dot (.) is a hint to RMs and +other tools that the resource agent provider should be omitted from lists +provided in response to user queries. -### "Resource agent" +A provider may choose to supply multiple, separate collections of resource +agents. In this case, each collection should have a unique name, and _provider_ +may refer either to the entity as a whole, or to an individual collection. -A RA provides the actions ("member functions") for a given type of -resources; by providing the RA with the instance parameters, it is used -to control a specific resource. +Currently, there is no central registry for provider names. Providers should +choose names that do not appear to be already in use for publicly available +resource agents. -They are usually implemented as shell scripts, but the API described here does -not require this. +Each provider also chooses the resource type names used for the resource agents +it provides. These do not need to be unique across providers. -Although this is somewhat similar to LSB init scripts, there are some -differences explained below. +### Resource Name +A _resource name_ is a unique identifier chosen by the cluster administrator +to identify a particular resource instance. -### "Instance parameters" +### Resource Parameters -Instance parameters are the attributes which describe a given resource -instance. It is recommended that the implementor minimize the set of -instance parameters. +_Resource parameters_, also known as _instance parameters_, are attributes +describing a particular resource instance. Each parameter has a name and a +value, which must satisfy the requirements of POSIX environment variable names +and values. -The meta data allows the RA to flag one or more instance parameters as -`unique`. This is a hint to the RM or higher level configuration tools -that the combination of these parameters must be unique to the given -resource type. +The resource agent defines the names, meanings, and allowed values of +parameters available for its resource type. -An instance parameter has a given name and value. They are both case -sensitive and must satisfy the requirements of POSIX environment -name/value combinations. +The cluster administrator specifies the particular parameters used for each +resource instance. + +### Role + +A _role_ is a mode of operation that a service may have, with two possible +values: _unpromoted_ and _promoted_. Resource agent support for roles is +optional. ## API ### API Version Numbers The version number is of the form `x.y`, where `x` and `y` are positive -numbers greater or equal to zero. `x` is referred to as the "major" +numbers greater than or equal to zero. `x` is referred to as the "major" number, and `y` as the "minor" number. The major number must be increased if a _backwards incompatible_ change is made to the API. A major number mismatch between the RA and the RM must be reported as an error by both sides. The minor number must be increased if _any_ change at all is made to the API. If the major is increased, the minor number should be reset to zero. The minor number can be used by both sides to see whether a certain additional feature is supported by the other party. -### Paths +### The Resource Agent Directory + +Resource agents are executable files that must be made available beneath a +location on a host's file system, referred to as the _resource agent +directory_. + +In the 1.0 version of this standard, the only acceptable location of this +directory was `/usr/ocf/resource.d`. However, in practice, installations +typically used the nonconforming location `/usr/lib/ocf/resource.d`. + +For strict backward compatibility with the 1.0 standard, RAs should be +available in the 1.0 location, and RMs should look for agents there. + +For widest compatibility, RAs should allow the installer to choose the location +of the directory, and RMs should provide an installation or configuration +option to specify the directory (and may optionally support multiple +directories) to be searched, with a reasonable default. + + +### The Resource Agent Directory Tree + +Each provider shall install its resource agents in a subdirectory of the +resource agent directory, using the provider's name. This allows installation +of multiple resource agents for the same type, but from different suppliers or +package versions. -The Resource Agents are located in subdirectories under -`/usr/ocf/resource.d`. +Each resource agent should be installed as a file within the provider +subdirectory, named according to the resource type. -The subdirectories allow the installation of multiple RAs for the same -type, but from different vendors or package versions. +The provider subdirectory and resource agent file may be links to the actual +locations. -The filename within the directories equals the resource type name -provided by the RA and may be a link to the real location. +A simple example of a resource agent directory tree containing a single +provider `acme` that provides resource agents `widget` and `gadget`: -Example directory structure: + acme/ + acme/widget + acme/gadget - FailSafe -> FailSafe-1.1.0/ - FailSafe-1.0.4/ - FailSafe-1.1.0/ - heartbeat -> heartbeat-1.1.2/ - heartbeat-1.1.2/ - heartbeat-1.1.2/IPAddr - heartbeat-1.1.2/IP -> IPAddr +Another example where multiple versions of acme's agents are installed: -How the RM choses an agent for a specific resource type name from the -available set is implementation specific. + acme -> acme-2.0/ + acme-1.0/ + acme-1.0/widget + acme-1.0/gadget + acme-2.0/ + acme-2.0/widget + acme-2.0/gadget +An example with two providers, an agent available from two providers, and an +agent available under multiple names from the same provider: -### Execution syntax + acme/ + acme/widget + acme/gadget + betterco/ + betterco/widget + betterco/IP -> IPAddr + betterco/IPAddr + +Resource managers may choose an agent for a specific resource type name from +the available set in any manner they choose. + + +### Execution Syntax After the RM has identified the executable to call, the RA will be called with the requested action as its sole argument. To allow for further extensions, the RA shall ignore all other arguments. -### Resource Agent actions +### Resource Agent Actions -A RA must be able to perform the following actions on a given resource -instance on request by the RM; additional actions may be supported by -the script for example for LSB compliance. +Resource agents must accept a single command-line argument specifying an +action to be performed. RAs must be able to perform actions listed in this +section as mandatory, and must advertise them as described in +**Resource Agent Meta-Data**. RAs may support any additional actions, including +but not limited to those listed in this section as optional. -The actions are all required to be idempotent. Invoking any operation -twice - in particular, the start and stop actions - shall succeed and -leave the resource instance in the requested state. +RMs are not required to support or utilize any particular actions. -In general, a RA should not assume it is the only RA of its type running -at any given time because the RM might start several RA instances for -multiple independent resource instances in parallel. +Actions must be idempotent. Invoking an already successfully performed action +additional times must be successful and leave the resource instance in the +requested state. For example, a start command given to a resource that has +already been successfully started should return success without changing the +state of the resource. -_Mandatory_ actions must be supported; _optional_ operations must be -advertised in the meta data if supported. If the RM tries to call a -unsupported action the RA shall return an error as defined below. +An RA should not assume it is the only RA of its type running at any given +time. Multiple resource instances of the same type may be running in parallel. +An RA must return a well-defined status, as described under +**Exit Status Codes**. This includes improper usage such as being called with +an unsupported action. + +#### Mandatory Actions - `start` - - Mandatory. - This brings the resource instance online and makes it available for + This must bring the resource instance online and make it available for use. It should NOT terminate before the resource instance has either been fully started or an error has been encountered. It may try to implement recovery actions for certain cases of startup failures. `start` must succeed if the resource instance is already running. `start` must return an error if the resource instance is not fully started. -- `stop` + If the resource agent supports roles, a successful start must put the + resource in the unpromoted role. - Mandatory. +- `stop` - This stops the resource instance. After the `stop` command has - completed, no component of the resource shall remain active and it - must be possible to start it on the same node or another node or an + This must stop the resource instance. After the `stop` command has + completed, no component of the resource shall remain active, and it + must be possible to start it on the same node or another node, otherwise an error must be returned. The `stop` request by the RM includes the authorization to bring down the - resource even by force as long data integrity is maintained; breaking + resource even by force as long as data integrity is maintained. Breaking currently active transactions should be avoided, but the request to offline the resource has higher priority than this. If this is not possible, - the RA shall return an error to allow higher level recovery. + the RA shall return an error, to allow higher-level recovery. - The `stop` action should also perform clean-ups of artifacts like leftover - shared memory segments, semaphores, IPC message queues, lock files etc. + The `stop` action should also clean up any artifacts such as leftover + shared memory segments, semaphores, IPC message queues, lock files, etc. `stop` must succeed if the resource is already stopped. `stop` must return an error if the resource is not fully stopped. - + - `monitor` - Mandatory. + This must check the current status of the resource instance. The + thoroughness of the check may optionally be influenced by **Check Levels**. + Service must remain available during the monitor, regardless of check + level. - Checks and returns the current status of the resource instance. The - thoroughness of the check is further influenced by the weight of the - check, which is further explained under **Action specific extensions**.. +- `meta-data` - It is accepted practice to have additional instance parameters which - are not strictly required to identify the resource instance but are - needed to monitor it or customize how intrusive this check is allowed - to be. + This must display the information described under + **Resource Agent Meta-Data** via standard output. - Note that `monitor` shall also return a well defined error code (see - below) for stopped instances, ie before `start` has ever been - invoked. - -- `recover` +#### Optional Actions + +- `demote` + + If the resource agent supports roles, this action must put an active + resource in the unpromoted role. + +- `notify` - Optional. + If the resource requires special coordination when multiple instances are + run simultaneously in the cluster, the resource agent should support this + action, which should perform such coordination. + + When the RA supports this action, RMs should call the action for all active + instances of this particular resource in the cluster before and after any + demote, promote, start, or stop action performed on any instance of it. + + How the RM passes useful information to the RA when performing this action + is currently left to the RM and RA, but may be formalized in a future + version of this standard. + +- `promote` + + If the resource agent supports roles, this action must put an active + resource in the promoted role. + +- `recover` A special case of the `start` action, this should try to recover a resource - locally. + locally. It is recommended that this action is not advertised unless it is - advantageous to use when compared to a stop/start operation. + advantageous to use when compared to a stop and start action sequence. - If this is not supported, it may be mapped to a stop/start action by - the RM. + If this is not supported, it may be mapped to a stop and start action + sequence by the RM. An example includes "recovering" an IP address by moving it to another interface; this is much less costly than initiating a full resource group - fail over to another node. + fail-over to another node. - `reload` - Optional. + Because the RA API originated as an extension to LSB init script syntax, and + such scripts often supported a `reload` action, it is common for RAs to + support one as well. - Notifies the resource instance of a configuration change external to - the instance parameters; it should reload the configuration of the - resource instance without disrupting the service. + If implemented, this action should notify the resource instance of a + configuration change external to the cluster configuration (that is, one + that does not involve a change to instance parameters). This notification + should cause changes to the resource instance's native configuration to take + effect without disrupting the service. - It is recommended that this action is not advertised unless it is - advantageous to use when compared to a stop/start operation. - - If this is not supported, it may be mapped to a stop/start action by - the RM. + If this action is supported by the RM but not the agent, the RM may, but is + not required to, map it to a stop and start action sequence. -- `meta-data` +- `reload-agent` - Mandatory. + This action should make effective any changes in instance parameters + marked as `reloadable` as described under **Resource Agent Meta-Data**. - Returns the resource agent meta data via stdout. + The difference between the `reload` and `reload-agent` actions is that + `reload` is called after changes to the service's native configuration, + while `reload-agent` is called after changes to reloadable instance + parameters, which might or might not require interaction with the service + itself. Most commonly, a user would manually initiate a `reload` action + after modifying the service's native configuration, while an RM would + automatically initiate `reload-params` after the user modifies reloadable + instance parameters. - `validate-all` - Optional. + This should validate the instance parameters provided. The thoroughness of + the check may optionally be influenced by **Check Levels**. - Validate the instance parameters provided. - Perform a syntax check and if possible, a semantic check on the - instance parameters. - - -### Parameter passing +### Parameter Passing The instance parameters and some additional attributes are passed in via the environment; this has been chosen because it does not reveal the parameters to an unprivileged user on the same system and environment variables can be easily accessed by all programming languages and shell scripts. The entire environment variable name space starting with `OCF_` is considered to be reserved for OCF use. -#### Syntax for instance parameters +#### Syntax for Instance Parameters They are directly converted to environment variables; the name is prefixed with `OCF_RESKEY_`. The instance parameter `force` with the value `yes` thus becomes `OCF_RESKEY_force=yes` in the environment. See the terms section on instance parameters for a more formal explanation. -#### Global OCF attributes +#### Global OCF Attributes Currently, the following additional environment variables are defined: * `OCF_RA_VERSION_MAJOR` * `OCF_RA_VERSION_MINOR` - Version number of the OCF Resource Agent API. If the script does + Version number of the OCF Resource Agent API. If the script does not support this revision, it should report an error. - + See **API Version Numbers** for an explanation of the versioning scheme used. The version number is split into two numbers for ease of use in shell scripts. These two may be used by the RA to determine whether it is run under an OCF compliant RM. Example: ``` OCF_RA_VERSION_MAJOR=1 - OCF_RA_VERSION_MINOR=0 + OCF_RA_VERSION_MINOR=1 ``` * `OCF_ROOT` Referring to the root of the OCF directory hierarchy. - - Example: `OCF_ROOT=/usr/ocf` + + Example: `OCF_ROOT=/usr/lib/ocf` * `OCF_RESOURCE_INSTANCE` The name of the resource instance. * `OCF_RESOURCE_TYPE` The name of the resource type being operated on. -### Action specific extensions +* `OCF_OUTPUT_FORMAT` + + Resource agents may optionally support multiple formats for output generated + by an action. The specific formats supported and values used to indicate + them are left to agents, but it is recommended to use "text" for readable + text output, "xml" for XML output, and "html" for HTML output. + + The `meta-data` action must support, and default to, XML output. The default + for other actions is left to agents. -These environment variables are not required for all actions, but only -supported by some. +#### Check Levels -#### Parameters specific to the 'monitor' action +Resource agents may optionally support the `OCF_CHECK_LEVEL` +environment variable when called with the `monitor` or `validate-all` actions, +to allow requests for more or less intensive checks. Agents that support +`OCF_CHECK_LEVEL` may choose their own default value if it is not specified. + +Agents that support `OCF_CHECK_LEVEL` should indicate so by specifying actions +with `depth` attributes in agent meta-data, as described in +**Resource Agent Meta-Data**. - `OCF_CHECK_LEVEL` - `0` - The most lightweight check possible, which should not - have an impact on the QoS. + The most lightweight check possible. + + For `validate-all` actions, this should verify the internal consistency + (syntax and compatibility) of specified parameters, but should not + verify the local environment in any fashion. This allows tools to + validate parameters even if running on a node that will not run the + agent. + For `monitor` actions, this should not affect quality of service. Example: Check for the existence of the process. - `10` - A medium weight check, expected to be called multiple - times per minute, which should not have a noticeable - impact on the QoS. + A medium-weight check. - Example: Send a request for a static page to a - webserver. + For `validate-all` actions, this may verify the suitability of the + local environment, in addition to the internal consistency of + parameters. - - `20` + For `monitor` actions, this should be suitable for being called + multiple times per minute, with minimal impact on quality of service. + Example: Send a request for a static page to a Web server. - A heavy weight check, called infrequently, which may - impact system or service performance. + - `20` - Example: An internal consistency check to verify service - integrity. + A heavyweight check. This is expected to be called infrequently, and + may affect system or service performance. -Service must remain available during all of these operation. -All other number are reserved. + - All other numbers are reserved. It is recommended that if a requested level is not implemented, the RA should perform the next lower level supported. -### Exit status codes +### Exit Status Codes -These exit status codes are the ones documented in the LSB 1.1.0 -specification, with additional explanations of how they shall be used by -RAs. In general, all non-zero status codes shall indicate failure in -accordance to the best current practices. +These exit status codes are identical to those documented in the LSB 5.0 Core +specification for non-status "Init Script Actions" +, +with additional explanations of how they shall be used by RAs. -#### All operations +Although non-zero status codes are referred to in this document as errors, RA +developers should keep in mind that RMs decide whether a status code is a +failure or not (for example, if a particular error is the expected situation, +it may not be considered a failure). - `0` - No error, action succeeded completely + Success. The requested action finished and succeeded completely, or + for a "monitor" action, the service was found to be properly active. - `1` - Generic or unspecified error (current practice) - The "monitor" operation shall return this for a crashed, hung or - otherwise non-functional resource. + Unspecified error. The action did not completely succeed for some reason, + or for a "monitor" action, the service was malfunctioning or in an + undetermined state. A more specific status code should be used if + applicable. - `2` - Invalid or excess argument(s) - Likely error code for validate-all, if the instance parameters - do not validate. Any other action is free to also return this - exit status code for this case. + Invalid parameter(s). Note: there is some variance in the actual use of + this status; it may refer to parameters that are inherently invalid (for + example, text provided for a parameter value that must be an integer), or + to parameters that are invalid in the context of the local host (for + example, a supplied file name does not exist). It is recommended to use + the latter meaning, so RMs can decide to try running the resource on a + different host after receiving this status. - `3` - Unimplemented feature (for example, "reload") + Unimplemented feature. The RA does not support the requested action. - `4` - User had insufficient privilege + Insufficient privilege. The user executing the RA lacked some necessary + authorization. - `5` - Program is not installed + Not installed. Some software required for the operation of the service is + not available on the local host. - `6` - Program is not configured + Not configured. Note: there is some variance in the actual use of this + status; it may mean the service's own configuration on the local host is + invalid, or it may mean the parameters supplied to the RA are inherently + invalid. It is recommended to use the latter meaning, so that RMs may + decide to fail the action without retrying elsewhere. - `7` - Program is not running + Not running. A "monitor" action shall return this if it finds the service + to be completely stopped (if there is doubt, some other status such as 1 + should be returned). Note: A successful "stop" operation shall return 0, + not 7. - Note: This is not the error code to be returned by a successful - "stop" operation. A successful "stop" operation shall return 0. - The "monitor" action shall return this value only for a - _cleanly_ stopped resource. If in doubt, it should return 1. +- `8` -- `8-99` + Running promoted. A "monitor" action shall return this if the + resource agent supports roles, and the service is both properly active and + in the promoted role. Note: The LSB reserves this value for future use in + the context of init scripts, but it is used here for compatibility with + established practice. - Reserved for future LSB use +- `9` -- `100-149` + Failed promoted. A "monitor" action shall return this if the resource agent + supports roles, and the service may be in the promoted role, but it is not + functioning properly. Note: The LSB reserves this value for future use in + the context of init scripts, but it is used here for compatibility with + established practice. - Reserved for distribution use +- `190` -- `150-199` + Degraded success. A "monitor" action may return this if the service is + found to be properly active, but in such a condition that future failures + are more likely. - Reserved for application use +- `191` -- `200-254` + Degraded promoted. A "monitor" action may return this if the resource agent + supports roles, and the service is found to be properly active in the + promoted role, but in such a condition that future failures are more + likely. - Reserved +- Other values + + This standard does not explicitly reserve any other values. In the context + of init scripts, the LSB standard sets aside `150-199` for application use, + and reserves `8-99` for LSB use, `100-149` for distribution use, and + `200-254`. Many shells use values `129-255` to indicate termination by a + signal, which could be ambiguous when a resource agent is run via a shell. -## Relation to the LSB -It is required that the current LSB spec is fully supported by the system. +## Relation to the LSB -The API tries to make it possible to have RA function both as a normal LSB -init script and a cluster-aware RA, but this is not required functionality. -The RAs could however use the helper functions defined for LSB init scripts. +The RA API aims to make it possible for (but does not require) an RA to +function as both an LSB-compliant init script and a cluster-aware RA. +RAs may use helper functions defined for LSB init scripts. -## RA meta data +## Resource Agent Meta-Data ### Format -The API has the following requirements which are not fulfilled by the -LSB way of embedding meta data into the beginning of the init scripts: +While the LSB uses shell script comments at the beginning of init scripts to +provide meta-data, OCF RA meta-data is described using XML so that the +meta-data can be: -- Independent of the language the RA is actually written in, +- Independent of the language the RA itself is written in, - Extensible, -- Structured, +- Structured, and - Easy to parse from a variety of languages. -This is why the API uses simple XML to describe the RA meta data. The -DTD for this API can be found at [this location](http://www.opencf.org/standards/ra-api-1.dtd). +Resource agents must at least support XML output for the `meta-data` action, +and such XML shall conform to the XML schema formally described at +. -### Semantics +### Example -An example of a valid meta data output is provided in -`ra-metadata-example.xml`. +An example of a valid meta-data output is provided at +. -## To-do list +### Semantics -- Move the terminology definitions out into a separate document - common to all OCF work. -- An interface where the RA asynchronously informs the RM of - failures is planned but not defined yet. +Certain meta-data XML elements warrant further explanation: + +- `resource-agent`: The optional `version` attribute should describe the + version of the agent itself. + +- `version`: This is the version of the OCF RA standard with which the RA + claims compatibility. + +- `longdesc`, `shortdesc`, and `desc`: These elements, wherever they occur in + meta-data, are natural-language descriptions of what is specified by their + parent element, intended as hints to tools for display to users. These + elements must contain a `lang` attribute whose value is a standard language + identifier ("BCP 47" ). + Multiple elements with different values for `lang` may be specified, to + provide translations. These elements may contain any XML, but it is strongly + recommended to limit the content to a text string. + +- `parameter`: + - `unique-group` attribute: This is a hint to RMs and other tools that the + combination of all parameters with the same value should be unique to the + resource type. That is, no two instances of the same resource type should + have the same combination of these parameters. If not specified, multiple + instances of the same resource type may have the same value of this + parameter. + + Note: a boolean `unique` attribute was formerly used for a similar + purpose, but was commonly misused, and is now deprecated. An RA may + provide it for backward compatibility, but because it is only a hint in + any case, RMs and tools are free to ignore it. + + - `required` attribute: This is a hint to RMs and other tools that every + resource instance of this resource type must specify a value for this + parameter. + + - `reloadable` attribute: If set to 1, this is a hint to indicate that a + change in this instance can take effect via the `reload-agent` action as + described under **Optional Actions**. Changes to any instance parameter + not marked as `reloadable` require a stop and start to take effect. + + - `deprecated` child element: When present, this element is a hint to RMs + and other tools that the parameter is supported for backward + compatibility only. + - `replaced-with` child element: This must contain a `name` attribute + with the name of another parameter that should be used instead of the + deprecated parameter. Multiple such elements may be specified. + +- `action`: Resource agents should advertise each action they support, + including all mandatory actions, with an `action` element. + - `name` attribute (required): This is a unique identifier for the action + as described in **Resource Agent Actions**. There may be multiple + `action` entries with the same name and different values for other + attributes (for example, to recommend different timeout and interval + values for status actions of different depths). + - `timeout` attribute (required): This is a hint to RMs and other tools + that every resource instance of this resource type should specify a + timeout equal to or greater than this value (when used with any other + attribute values specified in this entry). + - `interval` attribute (optional): This is a hint to RMs and other tools + that every resource instance of this resource type should repeat this + action at intervals equal to this value (when used with any other + attribute values specified in this entry). + - `depth` attribute (optional): This is a hint to RMs and other tools + that this action of the resource agent utilizes the depth parameter with + this value, as described in **Resource Agent Actions** and + **Check Levels**. + - `role` attribute (optional): This is a hint to RMs and other tools + that this action of the resource agent recognizes this role value + (promoted or unpromoted). ## Contributors - James Bottomley - Greg Freemyer - Simon Horman - Ragnar Kjørstad - Lars Marowsky-Brée - Alan Robertson -- Yixiong Zou +- Yixiong Zou +- Ken Gaillot