OCF开发者指南 第二章

2. API 定义

2.1 环境变量

一个资源代理通过环境变量来获得资源的全部配置信息。那些环境变量的名字往往前缀是OCF_RESKEY， 名字就是资源的名字。比如，如果资源有一个ip 参数设为 192.168.1.1， 资源代理就使用环境变量 OCF_RESKEY_ip来保存这个值。

对于任何不需要用户设置的资源----即在资源代理元数据参数定义没有被设置成 required="true"----资源代理必须：

• 提供一个合理的缺省值。这个必须在元数据里明确。为了方便，资源代理使用一个形如OCF_RESKEY_<parametername>_default 的变量保存这个值；
• 另一个选择，就是这个值为空，但程序可以正确运行；

另外，集群管理器也可以支持元资源参数。这些不直接应用到资源配置，而是指定集群资源管理器如何管理资源。比如，pacemaker使用target-role元参数来指定资源是应该启动还是停止。

元参数通过OCF_RESKEY_CRM_meta_ 命名方式传给资源代理，注意所有连字符都是转为下划线。这样 target-role 属性都映射都环境变量 OCF_RESKEY_CRM_meta_target_role。

2.2 Actions

任何资源代理必须支持一个命令行参数，这个参数指定资源代理的执行。下列的行为是资源代理必须支持的：

• start --- 启动资源
• stop ---  停止资源
• monitor --- 查询资源状态
• meta-data --- 导出资源代理元数据

另外，资源代理可以选择支持如下行为：

• promote --- 将一个资源提升为Master 角色 （只对 Master/Slave 资源）
• demote  --- 将一个资源转为Slave 角色（只对 Master/Slave 资源）
• migrate_to 和 migrate_from --- 实现资源的热迁移
• validate_all --- 校验资源的配置
• usage 或 help --- 显示usage信息或者help信息。是资源本身用命令行运行时候的显示
• status --- 已经丢弃。是monitor之前使用的行为

2.3 Timeouts

action timeouts 是用来从外部强制资源代理正确运行的。集群管理器负责监视资源代理的某个动作运行了多长时间，如果没有在限定时间内完成，则会终止这个程序。这样资源代理不用去检查时间过期。

然而，资源代理可以建议这个timeout值（这个值如果设置了，会被集群管理器按时强制实行）。后面章节会详细讲到细节。

2.4 Metadata (元数据)

每个资源代理都要必须在一个XML元数据里说明其目的支持的参数。这个元数据表被集群管理器用来提供在线帮助，资源代理的man手册也可以从这里导出。下面是一个虚构的资源代理元数据：

 
<?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>

上面定义resouce-agent 元素，必须有一个，并用name和version定义。

longdesc 和 shortdec 元素提供长的和短的资源代理功能描述。shortdesc只提供一句话，提供简介列表。longdesc提供更多细节的完整描述。

parameters 元素描述资源代理参数，可以有多个parameter 子元素，每一个都是资源代理支持的参数。

每一个parameter参数用应该有一个shortdesc和一个longdesc 用来描述参数的细节，一个content元素描述参数期望的内容。parameter支持如下属性：

• required 指示参数是强制的（required="0")还是可选的（require=""1)
• unique (允许值：0和1）指示指定的值在整个集群是唯一的。比如，一个高可用的浮动IP地址会被定义为unique，因为这个地址在整个集群里面只能有一个，不能重复。

content元素有两个属性：

• type 描述参数的类型（string，integer，或者是 boolean），如果未设置，type 缺省是string
• 对于一些可选parameter，通常通过default属性设置一个合适的

actions 列表定义了资源代理声明的支持的行为。

每一个action 都有自己的timeout值。这是指示用户这个行为最小的timeout值。这种方式适应某些可以很快启动的资源（如IP地址、文件系统）和需要数分钟才启动的资源（如数据库）。

另外，一些重复的行为（如monitor）则应该有一个推荐的最小时间间隔 interval，这个时间间隔是两次相同行为的连续调用的时间。和timeout一样，这个值没有缺省值。这个值仅仅提供一个参考的最小值。