The OCF Resource Agent Developer’s Guide

Florian Haas

hastexo

License information

The text of and illustrations in this document are licensed under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA").

Revision History
Revision 1.0.3July 26, 2012FGH
Revision 1.0.2November 18, 2011FGH
Revision 1.0.1January 3, 2011FGH
Revision 1.0.0December 13, 2010FGH

Table of Contents

1. Introduction
1.1. What is a resource agent?
1.2. Who or what uses a resource agent?
1.3. Which language is a resource agent written in?
2. API definitions
2.1. Environment variables
2.2. Actions
2.3. Timeouts
2.4. Metadata
3. Return codes
3.1. OCF_SUCCESS (0)
3.2. OCF_ERR_GENERIC (1)
3.3. OCF_ERR_ARGS (2)
3.4. OCF_ERR_UNIMPLEMENTED (3)
3.5. OCF_ERR_PERM (4)
3.6. OCF_ERR_INSTALLED (5)
3.7. OCF_ERR_CONFIGURED (6)
3.8. OCF_NOT_RUNNING (7)
3.9. OCF_RUNNING_MASTER (8)
3.10. OCF_FAILED_MASTER (9)
4. Resource agent structure
4.1. Resource agent interpreter
4.2. Author and license information
4.3. Initialization
4.4. Functions implementing resource agent actions
4.5. Execution block
5. Resource agent actions
5.1. start action
5.2. stop action
5.3. monitor action
5.4. validate-all action
5.5. meta-data action
5.6. promote action
5.7. demote action
5.8. migrate_to action
5.9. migrate_from action
5.10. notify action
6. Script variables
6.1. $OCF_ROOT
6.2. $OCF_FUNCTIONS_DIR
6.3. $OCF_RESOURCE_INSTANCE
6.4. $__OCF_ACTION
6.5. $__SCRIPT_NAME
6.6. $HA_RSCTMP
7. Convenience functions
7.1. Logging: ocf_log
7.2. Testing for binaries: have_binary and check_binary
7.3. Executing commands and capturing their output: ocf_run
7.4. Locks: ocf_take_lock and ocf_release_lock_on_exit
7.5. Testing for numerical values: ocf_is_decimal
7.6. Testing for boolean values: ocf_is_true
7.7. Pseudo resources: ha_pseudo_resource
8. Conventions
8.1. Well-known parameter names
8.2. Parameter defaults
8.3. Honoring PATH for binaries
9. Special considerations
9.1. Licensing
9.2. Locale settings
9.3. Testing for running processes
9.4. Specifying a master preference
10. Testing resource agents
10.1. Testing with ocf-tester
10.2. Testing with ocft
11. Installing and packaging resource agents
11.1. Installing resource agents
11.2. Packaging resource agents
11.3. Submitting resource agents
11.4. Maintaining resource agents

1. Introduction

This document is to serve as a guide and reference for all developers, maintainers, and contributors working on OCF (Open Cluster Framework) compliant cluster resource agents. It explains the anatomy and general functionality of a resource agent, illustrates the resource agent API, and provides valuable hints and tips to resource agent authors.

1.1. What is a resource agent?

A resource agent is an executable that manages a cluster resource. No formal definition of a cluster resource exists, other than "anything a cluster manages is a resource." Cluster resources can be as diverse as IP addresses, file systems, database services, and entire virtual machines — to name just a few examples.

1.2. Who or what uses a resource agent?

Any Open Cluster Framework (OCF) compliant cluster management application is capable of managing resources using the resource agents described in this document. At the time of writing, two OCF compliant cluster management applications exist for the Linux platform:

  • Pacemaker, a cluster manager supporting both the Corosync and Heartbeat cluster messaging frameworks. Pacemaker evolved out of the Linux-HA project.
  • RGmanager, the cluster manager bundled in Red Hat Cluster Suite. It supports the Corosync cluster messaging framework exclusively.

1.3. Which language is a resource agent written in?

An OCF compliant resource agent can be implemented in any programming language. The API is not language specific. However, most resource agents are implemented as shell scripts, which is why this guide primarily uses example code written in shell language.