Chapter 1

Resource Management Overview

This book provides guidelines for creating a resource type for a software application such as Oracle, Sun™ One Web Server, DNS, and so on. As such, this book is targeted at resource type developers.

This chapter provides an overview of the concepts you need to understand in order to develop a data service and contains the following information.

Note - This book uses the terms resource type and data service interchangeably. The term agent, though rarely used in this book, is equivalent to resource type and data service.

Sun Cluster Application Environment

The Sun Cluster system enables applications to be run and administered as highly available and scalable resources. The cluster facility known as the Resource Group Manager, or RGM, provides the mechanism for high availability and scalability. The elements that form the programming interface to this facility include the following.

A set of callback methods you write that enable the RGM to control an application on the cluster
The Resource Management API (RMAPI ), a set of low-level API commands and functions that you can use to write the callback methods. These APIs are implemented in the libscha.so library.
Process management facilities for monitoring and restarting processes on the cluster
The Data Service Development Library (DSDL ), a set of library functions that encapsulates the low-level API and process-management functionality at a higher level and adds some additional functionality to ease the writing of callback methods. These functions are implemented in the libdsdev.so library.

The following figure shows the interrelationship of these elements.

Figure 1-1 Programming Architecture

Diagram showing interrelationship between callback methods, RMAPI, process management facility, and DSDL

Included in the Sun Cluster package is SunPlex Agent Builder™, a tool that automates the process of creating a data service (see Chapter 9, SunPlex Agent Builder). Agent Builder generates data service code in either C (using DSDL functions to write the callback methods) or in Korn shell (ksh) (using low-level API commands to write the callback methods).

The RGM runs as a daemon on each cluster node and automatically starts and stops resources on selected nodes according to preconfigured policies. The RGM makes a resource highly available in the event of a node failure or reboot by stopping the resource on the affected node and starting it on another. The RGM also automatically starts and stops resource-specific monitors that can detect resource failures and relocate failing resources onto another node or can monitor other aspects of resource performance.

The RGM supports both failover resources, which can be online on at most one node at a time, and scalable resources, which can be online on multiple nodes simultaneously.

RGM Model

This section introduces some fundamental terminology and explains in more detail the RGM and its associated interfaces.

The RGM handles three major kinds of interrelated objects: resource types, resources, and resource groups. One way to introduce these objects is by means of an example, as described below.

A developer implements a resource type, ha-oracle, that makes an existing Oracle DBMS application highly available. An end user defines separate databases for marketing, engineering, and finance, each of which is a resource of type ha-oracle. The cluster administrator places these resources in separate resource groups so they can run on different nodes and fail over independently. A developer creates a second resource type, ha-calendar, to implement a highly available calendar server that requires an Oracle database. The cluster administrator places the resource for the finance calendar into the same resource group as the finance database resource so that both resources run on the same node and fail over together.

Resource Types

A resource type consists of a software application to be run on the cluster, control programs used as callback methods by the RGM to manage the application as a cluster resource, and a set of properties that form part of the static configuration of a cluster. The RGM uses resource type properties to manage resources of a particular type.

Note - In addition to a software application, a resource type can represent other system resources such as network addresses.

The resource type developer specifies the properties for the resource type and sets their values in a resource type registration (RTR) file. The RTR file follows a well-defined format described in Setting Resource and Resource Type Properties and in the rt_reg(4) man page. See also Defining the Resource Type Registration File for a description of a sample resource type registration file.

Table A-1 provides a list of the resource type properties.

The cluster administrator installs and registers the resource type implementation and underlying application on a cluster. The registration procedure enters into the cluster configuration the information from the resource type registration file. The Sun Cluster 3.1 Data Service Planning and Administration Guide describes the procedure for registering a data service.

Resources

A resource inherits the properties and values of its resource type. In addition, a developer can declare resource properties in the resource type registration file. See Table A-2 for a list of resource properties.

The cluster administrator can change the values of certain properties depending on how they were specified in the resource type registration (RTR) file. For example, property definitions can specify a range of allowable values and specify when the property is tunable, for example, at creation, any time, or never. Within these specifications, the cluster administrator can make changes to properties using administration commands.

The cluster administrator can create many resources of the same type, each resource having its own name and set of property values, so that more than one instance of the underlying application can run on the cluster. Each instantiation requires a unique name within the cluster.

Resource Groups

Each resource must be configured in a resource group. The RGM brings all resources in a group online and offline together on the same node. When the RGM brings a resource group online or offline, it invokes callback methods on the individual resources in the group.

The nodes on which a resource group is currently online are called its primaries or primary nodes. A resource group is mastered by each of its primaries. Each resource group has an associated Nodelist property, which is set by the cluster administrator, that identifies all potential primaries or masters of the resource group.

A resource group also has a set of properties. These properties include configuration properties that can be set by the cluster administrator and dynamic properties, set by the RGM, that reflect the active state of the resource group.

The RGM defines two types of resource groups, failover and scalable . A failover resource group can be online on one node only at any time while a scalable resource group can be online on multiple nodes simultaneously. The RGM provides a set of properties to support the creation of each type of resource group. See Transferring a Data Service to a Cluster and Implementing Callback Methods for details about these properties.

See Table A-3 for a list of resource group properties.

Resource Group Manager

The Resource Group Manager (RGM) is implemented as a daemon, rgmd, that runs on each member node of the cluster. All of the rgmd processes communicate with each other and act together as a single cluster-wide facility.

The RGM supports the following functions:

Whenever a node boots or crashes, the RGM attempts to maintain availability of all managed resource groups by automatically bringing them online on appropriate masters.
If a particular resource fails, its monitor program can request that the resource group be restarted on the same master or switched to a new master.
The cluster administrator can issue an administrative command to request one of the following actions:
- Change mastery of a resource group
- Enable or disable a particular resource within a resource group
- Create, delete, or modify a resource, a resource group, or a resource type

Whenever the RGM activates configuration changes, it coordinates its actions across all member nodes of the cluster. This kind of activity is known as a reconfiguration. To effect a state change on an individual resource, the RGM invokes a resource-type specific callback method on that resource.


	Chapter 1 Resource Management Overview This book provides guidelines for creating a resource type for a software application such as Oracle, Sun™ One Web Server, DNS, and so on. As such, this book is targeted at resource type developers. This chapter provides an overview of the concepts you need to understand in order to develop a data service and contains the following information. Sun Cluster Application Environment RGM Model Resource Group Manager Callback Methods Programming Interfaces Resource Group Manager Administrative Interface Note - This book uses the terms resource type and data service interchangeably. The term agent, though rarely used in this book, is equivalent to resource type and data service. Sun Cluster Application Environment The Sun Cluster system enables applications to be run and administered as highly available and scalable resources. The cluster facility known as the Resource Group Manager, or RGM, provides the mechanism for high availability and scalability. The elements that form the programming interface to this facility include the following. A set of callback methods you write that enable the RGM to control an application on the cluster The Resource Management API (RMAPI ), a set of low-level API commands and functions that you can use to write the callback methods. These APIs are implemented in the `libscha.so` library. Process management facilities for monitoring and restarting processes on the cluster The Data Service Development Library (DSDL ), a set of library functions that encapsulates the low-level API and process-management functionality at a higher level and adds some additional functionality to ease the writing of callback methods. These functions are implemented in the `libdsdev.so` library. The following figure shows the interrelationship of these elements. Figure 1-1 Programming Architecture Included in the Sun Cluster package is SunPlex Agent Builder™, a tool that automates the process of creating a data service (see Chapter 9, SunPlex Agent Builder). Agent Builder generates data service code in either C (using DSDL functions to write the callback methods) or in Korn shell (`ksh`) (using low-level API commands to write the callback methods). The RGM runs as a daemon on each cluster node and automatically starts and stops resources on selected nodes according to preconfigured policies. The RGM makes a resource highly available in the event of a node failure or reboot by stopping the resource on the affected node and starting it on another. The RGM also automatically starts and stops resource-specific monitors that can detect resource failures and relocate failing resources onto another node or can monitor other aspects of resource performance. The RGM supports both failover resources, which can be online on at most one node at a time, and scalable resources, which can be online on multiple nodes simultaneously. RGM Model This section introduces some fundamental terminology and explains in more detail the RGM and its associated interfaces. The RGM handles three major kinds of interrelated objects: resource types, resources, and resource groups. One way to introduce these objects is by means of an example, as described below. A developer implements a resource type, `ha-oracle`, that makes an existing Oracle DBMS application highly available. An end user defines separate databases for marketing, engineering, and finance, each of which is a resource of type `ha-oracle`. The cluster administrator places these resources in separate resource groups so they can run on different nodes and fail over independently. A developer creates a second resource type, ha-calendar, to implement a highly available calendar server that requires an Oracle database. The cluster administrator places the resource for the finance calendar into the same resource group as the finance database resource so that both resources run on the same node and fail over together. Resource Types A resource type consists of a software application to be run on the cluster, control programs used as callback methods by the RGM to manage the application as a cluster resource, and a set of properties that form part of the static configuration of a cluster. The RGM uses resource type properties to manage resources of a particular type. Note - In addition to a software application, a resource type can represent other system resources such as network addresses. The resource type developer specifies the properties for the resource type and sets their values in a resource type registration (RTR) file. The RTR file follows a well-defined format described in Setting Resource and Resource Type Properties and in the `rt_reg`(4) man page. See also Defining the Resource Type Registration File for a description of a sample resource type registration file. Table A-1 provides a list of the resource type properties. The cluster administrator installs and registers the resource type implementation and underlying application on a cluster. The registration procedure enters into the cluster configuration the information from the resource type registration file. The Sun Cluster 3.1 Data Service Planning and Administration Guide describes the procedure for registering a data service. Resources A resource inherits the properties and values of its resource type. In addition, a developer can declare resource properties in the resource type registration file. See Table A-2 for a list of resource properties. The cluster administrator can change the values of certain properties depending on how they were specified in the resource type registration (RTR) file. For example, property definitions can specify a range of allowable values and specify when the property is tunable, for example, at creation, any time, or never. Within these specifications, the cluster administrator can make changes to properties using administration commands. The cluster administrator can create many resources of the same type, each resource having its own name and set of property values, so that more than one instance of the underlying application can run on the cluster. Each instantiation requires a unique name within the cluster. Resource Groups Each resource must be configured in a resource group. The RGM brings all resources in a group online and offline together on the same node. When the RGM brings a resource group online or offline, it invokes callback methods on the individual resources in the group. The nodes on which a resource group is currently online are called its primaries or primary nodes. A resource group is mastered by each of its primaries. Each resource group has an associated `Nodelist` property, which is set by the cluster administrator, that identifies all potential primaries or masters of the resource group. A resource group also has a set of properties. These properties include configuration properties that can be set by the cluster administrator and dynamic properties, set by the RGM, that reflect the active state of the resource group. The RGM defines two types of resource groups, failover and scalable . A failover resource group can be online on one node only at any time while a scalable resource group can be online on multiple nodes simultaneously. The RGM provides a set of properties to support the creation of each type of resource group. See Transferring a Data Service to a Cluster and Implementing Callback Methods for details about these properties. See Table A-3 for a list of resource group properties. Resource Group Manager The Resource Group Manager (RGM) is implemented as a daemon, `rgmd`, that runs on each member node of the cluster. All of the `rgmd` processes communicate with each other and act together as a single cluster-wide facility. The RGM supports the following functions: Whenever a node boots or crashes, the RGM attempts to maintain availability of all managed resource groups by automatically bringing them online on appropriate masters. If a particular resource fails, its monitor program can request that the resource group be restarted on the same master or switched to a new master. The cluster administrator can issue an administrative command to request one of the following actions: Change mastery of a resource group Enable or disable a particular resource within a resource group Create, delete, or modify a resource, a resource group, or a resource type Whenever the RGM activates configuration changes, it coordinates its actions across all member nodes of the cluster. This kind of activity is known as a reconfiguration. To effect a state change on an individual resource, the RGM invokes a resource-type specific callback method on that resource.