5 资源代理行为
每一个行为通常都使用一个分开的函数或者方法来实现。为了方便，通常命名为
按照通用的规则，任何时候资源代理遇到一个不可恢复的错误，资源代理可以马上退出，抛出异常，或者退出执行。这种情况往往发生在配置错误，缺失二进制文件，权限问题等时候。不必将这些错误传递到调用栈。
集群管理器有责任根据用户的配置实行合适的恢复行为。资源代理在有明确的配置说明时，不可以去猜的。
5.1 start action
当调用资源的start操作时，资源代理必须启动资源，除非资源已经启动了。这意味着资源代理必须确认资源的配置，查询他的状态，并只在资源没有启动的情况下才启动资源。通常的做法是首先调用validate_all 和 monitor 函数，如下面的例子：
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 |
foobar_start() { # exit immediately if configuration is not valid foobar_validate_all || exit $? # if resource is already running, bail out early if foobar_monitor; then ocf_log info "Resource is already running" return $OCF_SUCCESS fi # actually start up the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ... # After the resource has been started, check whether it started up # correctly. If the resource starts asynchronously, the agent may # spin on the monitor function here -- if the resource does not # start up within the defined timeout, the cluster manager will # consider the start action failed while ! foobar_monitor; do ocf_log debug "Resource has not started yet, waiting" sleep 1 done # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
5.2 stop action
当调用stop行为时，如果资源正在运行资源代理必须停止资源。这意味着，资源代理必须检测资源配置，查询其状态，在其正常运行的情况下，则stop。通常的做法是先调用validate_all 和 monitor 函数。必须清楚的是，stop是一个强制操作----资源代理可以做任何事情来关闭，重启动或切断资源。看下面的例子：
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 |
foobar_stop() { local rc # exit immediately if configuration is not valid foobar_validate_all || exit $? foobar_monitor rc=$? case "$rc" in "$OCF_SUCCESS") # Currently running. Normal, expected behavior. ocf_log debug "Resource is currently running" ;; "$OCF_RUNNING_MASTER") # Running as a Master. Need to demote before stopping. ocf_log info "Resource is currently running as Master" foobar_demote || \ ocf_log warn "Demote failed, trying to stop anyway" ;; "$OCF_NOT_RUNNING") # Currently not running. Nothing to do. ocf_log info "Resource is already stopped" return $OCF_SUCCESS ;; esac # actually shut down the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ... # After the resource has been stopped, check whether it shut down # correctly. If the resource stops asynchronously, the agent may # spin on the monitor function here -- if the resource does not # shut down within the defined timeout, the cluster manager will # consider the stop action failed while foobar_monitor; do ocf_log debug "Resource has not stopped yet, waiting" sleep 1 done # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
注意：
stop行为运行成功的返回码是$OCF_SUCCESS，不是 $OCF_NOT_RUNNING
重要：
stop行为失败会造成潜在的危险，集群管理器总是试着通过fencing来解决这个问题。换句话说，就是强制将一个节点从集群中剔除。这种方法最终是为了保护数据，但是的确让用户应用中断。所以，资源代理返回错误一定要非常慎重，确保合适合理的资源关闭方法都已经使用了。
5.3 monitor action
monitor 行为查询资源的状态。必须明确下面三种状态：
资源正在运行（返回 $OCF_SUCCESS）
资源安全的关闭（返回 $OCF_NOT_RUNNING)
资源运行出现问题，判断为一种错误（返回最接近的那个 $OCF_ERR_ 来指明问题）
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 |
foobar_monitor(){ local rc # exit immediately if configuration is not valid foobar_validate_all || exit $? ocf_run frobnicate --test # This example assumes the following exit code convention # for frobnicate: # 0: running, and fully caught up with master # 1: gracefully stopped # any other: error case "$?" in 0) rc=$OCF_SUCCESS ocf_log debug "Resource is running" ;; 1) rc=$OCF_NOT_RUNNING ocf_log debug "Resource is not running" ;; *) ocf_log err "Resource has failed" exit $OCF_ERR_GENERIC esac return $rc } |
有状态的（master/slave) 资源代理则需要另外一种精心定制的monitoring模式，这种模式可以提示集群管理器哪一个实例最合适做Master节点。第9.4节《确定master特征》会解释细节。
注意：
集群管理器的probe是测试资源是否运行的，会调用monitor行为。正常情况下，monitor操作在被probe调用和直接运行时是一样的。如果有些特别的资源需要特别定义probe，ocf_is_probe函数就是为这个目的的。
5.4 validate-all action
validate-all 行为测试资源代理的配置和工作环境。validate-all 退出会返回如下值：
$OCF_SUCCESS ---- 一切正常，配置正常可用；
$OCF_ERR_CONFIGURED ---- 资源配置出错；
$OCF_ERR_INSTALLED ---- 资源可能配置正确，但是在validate-all执行的节点，可能有关键组件丢失；
$OCF_ERR_PERM ---- 资源配置正确，也不缺组件，但是可能有权限问题（比如无法创建必要的文件）。
validate-all 通常封装成一个函数，不单是在相应行为时显式的调用，也可以由其他函数调用。所以，开发者一定要记得：这个函数也可能会在start，stop和monitor行为时候调用。
Probes 也引出了另外一个对于校验的挑战。在probe时（当集群管理器可能期望资源不要运行在probe运行的节点上），可能期望一些需要的组件在受影响的节点上是不可得的。比如，在probe时，期望在存储设备上的共享数据不可读。validate-all 函数可能需要特别对待probe，可以使用ocf_is_probe函数。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
foobar_validate_all() { # Test for configuration errors first if ! ocf_is_decimal $OCF_RESKEY_eggs; then ocf_log err "eggs is not numeric!" exit $OCF_ERR_CONFIGURED fi # Test for required binaries check_binary frobnicate # Check for data directory (this may be on shared storage, so # disable this test during probes) if ! ocf_is_probe; then if ! [ -d $OCF_RESKEY_datadir ]; then ocf_log err "$OCF_RESKEY_datadir does not exist or is not a directory!" exit $OCF_ERR_INSTALLED fi fi return $OCF_SUCCESS } |
5.5 meta-data action
meta_data 操作导出资源代理元数据到标准输出。输出必须遵循元数据格式----在2.4节有说明。
1 2 3 4 5 6 7 8 9 10 |
foobar_meta_data { cat < ... EOF } |
5.6 promote action
promote操作是可选的。它只支持有状态的资源代理，就是说，资源代理必须是两种角色中的一种：Master和slave。slave角色功能上和无状态的资源代理是相同的。这样，标准的无状态资源代理仅仅需要实现start和stop操作，而且有状态的资源代理必须实现started（slave）和master角色的切换。
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 46 47 48 49 50 51 52 53 54 55 |
foobar_promote() { local rc # exit immediately if configuration is not valid foobar_validate_all || exit $? # test the resource's current state foobar_monitor rc=$? case "$rc" in "$OCF_SUCCESS") # Running as slave. Normal, expected behavior. ocf_log debug "Resource is currently running as Slave" ;; "$OCF_RUNNING_MASTER") # Already a master. Unexpected, but not a problem. ocf_log info "Resource is already running as Master" return $OCF_SUCCESS ;; "$OCF_NOT_RUNNING") # Currently not running. Need to start before promoting. ocf_log info "Resource is currently not running" foobar_start ;; *) # Failed resource. Let the cluster manager recover. ocf_log err "Unexpected error, cannot promote" exit $rc ;; esac # actually promote the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ocf_run frobnicate --master-mode || exit $OCF_ERR_GENERIC # After the resource has been promoted, check whether the # promotion worked. If the resource promotion is asynchronous, the # agent may spin on the monitor function here -- if the resource # does not assume the Master role within the defined timeout, the # cluster manager will consider the promote action failed. while true; do foobar_monitor if [ $? -eq $OCF_RUNNING_MASTER ]; then ocf_log debug "Resource promoted" break else ocf_log debug "Resource still awaiting promotion" sleep 1 fi done # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
5.7 demote action
promote操作是可选的。它只支持有状态的资源代理，就是说，资源代理必须是两种角色中的一种：Master和slave。slave角色功能上和无状态的资源代理是相同的。这样，标准的无状态资源代理仅仅需要实现start和stop操作，而且有状态的资源代理必须实现master和started（slave）角色的切换。
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 46 47 48 49 50 51 52 53 54 55 56 57 |
foobar_demote() { local rc # exit immediately if configuration is not valid foobar_validate_all || exit $? # test the resource's current state foobar_monitor rc=$? case "$rc" in "$OCF_RUNNING_MASTER") # Running as master. Normal, expected behavior. ocf_log debug "Resource is currently running as Master" ;; "$OCF_SUCCESS") # Alread running as slave. Nothing to do. ocf_log debug "Resource is currently running as Slave" return $OCF_SUCCESS ;; "$OCF_NOT_RUNNING") # Currently not running. Getting a demote action # in this state is unexpected. Exit with an error # and let the cluster manager recover. ocf_log err "Resource is currently not running" exit $OCF_ERR_GENERIC ;; *) # Failed resource. Let the cluster manager recover. ocf_log err "Unexpected error, cannot demote" exit $rc ;; esac # actually demote the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ocf_run frobnicate --unset-master-mode || exit $OCF_ERR_GENERIC # After the resource has been demoted, check whether the # demotion worked. If the resource demotion is asynchronous, the # agent may spin on the monitor function here -- if the resource # does not assume the Slave role within the defined timeout, the # cluster manager will consider the demote action failed. while true; do foobar_monitor if [ $? -eq $OCF_RUNNING_MASTER ]; then ocf_log debug "Resource still awaiting promotion" sleep 1 else ocf_log debug "Resource demoted" break fi done # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
5.8 migrate_to action
migrate_to 操作服务于下面两个目的中的一个：
为资源提供一种本地push方式的迁移发起过程。换句话说，指导资源从当前运行的地方迁移到指定节点。资源代理通过环境变量 $OCF_RESKEY_CRM_meta_migrate_target 获得目标节点。
在freeze/thaw（或suspend/resume）模式的迁移中冻住资源，这种模式下资源不需要知道目的地。
下面的例子描述了push类型的迁移：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
foobar_migrate_to() { # exit immediately if configuration is not valid foobar_validate_all || exit $? # if resource is not running, bail out early if ! foobar_monitor; then ocf_log err "Resource is not running" exit $OCF_ERR_GENERIC fi # actually start up the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ocf_run frobnicate --migrate \ --dest=$OCF_RESKEY_CRM_meta_migrate_target \ || exit OCF_ERR_GENERIC ... # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
相应的，freeze/thaw 类型的迁移可以按如下方法实现freeze操作：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
foobar_migrate_to() { # exit immediately if configuration is not valid foobar_validate_all || exit $? # if resource is not running, bail out early if ! foobar_monitor; then ocf_log err "Resource is not running" exit $OCF_ERR_GENERIC fi # actually start up the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ocf_run frobnicate --freeze || exit OCF_ERR_GENERIC ... # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
5.9 migrate_from action
migrate_from 操作服务于下面两个目的中的一个：
为资源提供一种本地push方式的迁移完成过程。换句话说，检查资源是否正确的迁移，并在本地运行起来了。资源代理通过环境变量 OCF_RESKEY_CRM_meta_migrate_source 获得源节点
在freeze/thaw（或suspend/resume）模式的迁移中解冻资源，这种模式下资源不需要知道源地址
下面的例子描述了push类型的迁移：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
foobar_migrate_from() { # exit immediately if configuration is not valid foobar_validate_all || exit $? # After the resource has been migrated, check whether it resumed # correctly. If the resource starts asynchronously, the agent may # spin on the monitor function here -- if the resource does not # run within the defined timeout, the cluster manager will # consider the migrate_from action failed while ! foobar_monitor; do ocf_log debug "Resource has not yet migrated, waiting" sleep 1 done # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
相应的，freeze/thaw 类型的迁移可以按如下方法实现thaw操作：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
foobar_migrate_from() { # exit immediately if configuration is not valid foobar_validate_all || exit $? # actually start up the resource here (make sure to immediately # exit with an $OCF_ERR_ error code if anything goes seriously # wrong) ocf_run frobnicate --thaw || exit OCF_ERR_GENERIC # After the resource has been migrated, check whether it resumed # correctly. If the resource starts asynchronously, the agent may # spin on the monitor function here -- if the resource does not # run within the defined timeout, the cluster manager will # consider the migrate_from action failed while ! foobar_monitor; do ocf_log debug "Resource has not yet migrated, waiting" sleep 1 done # only return $OCF_SUCCESS if _everything_ succeeded as expected return $OCF_SUCCESS } |
5.10 notify action
通过通知，clone的实例（包括master/slave 资源，这种资源是clone资源的一种扩展）可以相互通知各自的状态。当通知机制被启用，每一个克隆实例都会携带 pre 和 post 通知。然后，集群管理器对所有克隆实例调用notify操作。notify操作执行是，会用到如下附加的环境变量：
$OCF_RESKEY_CRM_meta_notify_type—通知类型 (pre 或 post)
$OCF_RESKEY_CRM_meta_notify_operation—操作(action)，这是指通知做什么(start, stop, promote, demote 等.)
$OCF_RESKEY_CRM_meta_notify_start_uname—资源启动所在的节点名字(仅仅对启动通知)
$OCF_RESKEY_CRM_meta_notify_stop_uname—资源停止所在的节点名字(仅仅对停止通知)
$OCF_RESKEY_CRM_meta_notify_master_uname—Master 角色资源运行所在节点的名字
$OCF_RESKEY_CRM_meta_notify_promote_uname—正提升为Master角色的资源所在节点的节点名字 (仅仅 promote 通知)
$OCF_RESKEY_CRM_meta_notify_demote_uname—正在降级为slave角色的资源所在节点的节点名字 (仅仅 demote 通知)
对于master/slave资源，使用push模式的通知是很便利的，在种模式下，master为发布者，slave为订阅者。既然master只有在提升为master时能发通知，那slave就可以利用一个pre-promote通知来配置他们自己指向正确的发布者。
同样的，订阅者也希望在master角色状态不再延续时取消订阅。post-demote通知就是为了这个目的。
下面的例子阐述这样的概念：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
foobar_notify() { local type_op type_op="${OCF_RESKEY_CRM_meta_notify_type}-${OCF_RESKEY_CRM_meta_notify_operation}" ocf_log debug "Received $type_op notification." case "$type_op" in 'pre-promote') ocf_run frobnicate --slave-mode \ --master=$OCF_RESKEY_CRM_meta_notify_promote_uname \ || exit $OCF_ERR_GENERIC ;; 'post-demote') ocf_run frobnicate --unset-slave-mode || exit $OCF_ERR_GENERIC ;; esac return $OCF_SUCCESS } |
注意:
master/slave资源代理可支持多master配置，这样可能在某个时间内不止一个master。这种情况下，$OCF_RESKEY_CRM_meta_notify_*_uname会包含一个空格分隔的机器名列表，而不是上面例子一样的一个机器名。在那种环境里面，资源代理应该去处理一下这个列表。