2. API 定义

2.1 环境变量


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


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


  • 提供一个合理的缺省值。这个必须在元数据里明确。为了方便，资源代理使用一个形如OCF_RESKEY__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手册也可以从这里导出。下面是一个虚构的资源代理元数据：


1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

 0.1

 

This is a fictitious example resource  agent written for the

OCF Resource Agent Developers Guide.

 

 Example  resource agent

 for budding OCF RA  developers

 

   

     

     Number  of eggs, an example numeric parameter

     

     Number  of eggs

     

   

   

     

     Enable  superfrobnication, an example boolean parameter

     

     Enable  superfrobnication

     

   

   

     

     Data  directory, an example string parameter

     

     Data  directory

     

   

 

 

   

   

   

                               interval="10" depth="0" />

   

   

   

   

   

 


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


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


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


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


  • required 指示参数是强制的（required="1")还是可选的（require="0") （经测试1代表必须的）

  • unique (允许值：0和1）指示指定的值在整个集群是唯一的。比如，一个高可用的浮动IP地址会被定义为unique，因为这个地址在整个集群里面只能有一个，不能重复。（经测试1代表唯一的，不能重复）

content元素有两个属性：

  • type 描述参数的类型（string，integer，或者是 boolean），如果未设置，type 缺省是string

  • 对于一些可选parameter，通常通过default属性设置一个合适的


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


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


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