The OCF Resource Agent Developer’s Guide

The OCF Resource Agent Developer’s Guide
		Next

Florian Haas

hastexo

<florian.haas@hastexo.com>

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").

A summary of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/.
The full license text is available at http://creativecommons.org/licenses/by-sa/3.0/legalcode.
In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

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

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.