OCF开发者指南 第五章

5 资源代理行为

每一个行为通常都使用一个分开的函数或者方法来实现。为了方便，通常命名为<agent>_<action>，所以，foobar的start行为的函数实现命名为 foobar_start().

按照通用的规则，任何时候资源代理遇到一个不可恢复的错误，资源代理可以马上退出，抛出异常，或者退出执行。这种情况往往发生在配置错误，缺失二进制文件，权限问题等时候。不必将这些错误传递到调用栈。

集群管理器有责任根据用户的配置实行合适的恢复行为。资源代理在有明确的配置说明时，不可以去猜的。

5.1 start action

当调用资源的start操作时，资源代理必须启动资源，除非资源已经启动了。这意味着资源代理必须确认资源的配置，查询他的状态，并只在资源没有启动的情况下才启动资源。通常的做法是首先调用validate_all 和 monitor 函数，如下面的例子：

 
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是一个强制操作----资源代理可以做任何事情来关闭，重启动或切断资源。看下面的例子：

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_ 来指明问题）

   
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函数。

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节有说明。

foobar_meta_data {
    cat <<EOF
<?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">
...
EOF
}

5.6 promote action

promote操作是可选的。它只支持有状态的资源代理，就是说，资源代理必须是两种角色中的一种：Master和slave。slave角色功能上和无状态的资源代理是相同的。这样，标准的无状态资源代理仅仅需要实现start和stop操作，而且有状态的资源代理必须实现started（slave）和master角色的切换。

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）角色的切换。

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类型的迁移：

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操作：

 
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类型的迁移：

 
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操作：

 
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通知就是为了这个目的。

下面的例子阐述这样的概念：

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会包含一个空格分隔的机器名列表，而不是上面例子一样的一个机器名。在那种环境里面，资源代理应该去处理一下这个列表。