Chapter 4 Modifying a Resource Type

This chapter discusses the issues that you need to understand to modify a resource type. Information about the means by which you enable a cluster administrator to upgrade a resource is also included.

This chapter covers the following topics:

• Overview of Modifying a Resource Type

• Setting Up the Contents of the Resource Type Registration File

• What Happens When a Cluster Administrator Upgrades

• Implementing Resource Type Monitor Code

• Determining Installation Requirements and Packaging

• Documentation to Provide for a Modified Resource Type

Overview of Modifying a Resource Type

Cluster administrators must be able to carry out the following tasks:

• Install and register a new version of an existing resource type

• Allow the registration of multiple versions of a given resource type

• Upgrade an existing resource to a new version of the resource type without having to delete and re-create the resource

A resource type that you intend to upgrade is called an upgrade-aware resource type. Elements of an existing resource type that you might change are as follows:

• Attributes of resource type properties

• The set of declared resource properties, including standard and extension properties

• Attributes of resource properties, such as default, min, max, arraymin, arraymax, or tunability

• The set of declared methods

• The implementation of methods or monitors

You do not necessarily have to modify a resource type when you modify application code.

You need to understand the requirements for providing the tools that will enable a cluster administrator to upgrade a resource type. This chapter tells you what you need to know to set up these tools.

Setting Up the Contents of the Resource Type Registration File

Resource Type Name

The three components of a resource type name are properties that are specified in the RTR file as vendor-id, resource-type, and rt-version. The scrgadm command inserts the period and the colon delimiters to create the name of the resource type:

vendor-id.resource-type:rt-version

The vendor-id prefix serves to distinguish between two registration files of the same name that different companies provide. To ensure that the vendor-id is unique, use the stock symbol of the company when creating the resource type. The rt-version distinguishes between multiple registered versions (upgrades) of the same base resource type.

You can obtain the fully qualified resource type name by typing the following command:

# scha_resource_get -O Type -R resource-name -G resource-group-name

Resource type names that you registered prior to Sun Cluster 3.1 continue to use this syntax:

vendor-id.resource-type

The format of resource type names is described in Format of Resource Type Names.

Specifying the #$upgrade and #$upgrade_from Directives

To ensure that the resource type that you are modifying is upgrade-aware, include the #$upgrade directive in the resource type's RTR file. After the #$upgrade directive, add zero or more #$upgrade_from directives for each earlier version of the resource type that you want to support.

The #$upgrade and #$upgrade_from directives must appear between the resource type property declarations and the resource declarations sections in the RTR file. See the rt_reg(4) man page.

Example 4–1 #$upgrade_from Directive in an RTR File

#$upgrade_from   "1.1"   WHEN_OFFLINE
#$upgrade_from   "1.2"   WHEN_OFFLINE
#$upgrade_from   "1.3"   WHEN_OFFLINE
#$upgrade_from   "2.0"   WHEN_UNMONITORED
#$upgrade_from   "2.1"   ANYTIME
#$upgrade_from   ""      WHEN_UNMANAGED

The format of the #$upgrade_from directive is as follows:

#$upgrade_from version tunability

version

The RT_version. If any resource type does not have a version, or for versions other than what you defined previously in the RTR file, specify the empty string (“”).

tunability

The conditions under which, or when, the cluster administrator can upgrade the specified RT_version.

Use the following tunability values in the #$upgrade_from directives:

ANYTIME

Use when there are no restrictions on when the cluster administrator can upgrade the resource. The resource can be completely online during the upgrade.

WHEN_UNMONITORED

Use when the new resource type version's methods are as follows:

• The Update, Stop, Monitor_check, and Postnet_stop methods are compatible with the older resource type version's starting methods (Prenet_stop and Start)

• The Fini method is compatible with the Init method of older versions

The cluster administrator must only stop the resource monitor program before upgrading.

WHEN_OFFLINE

Use when the new resource type version's Update, Stop, Monitor_check, or Postnet_stop method is as follows:

• Compatible with the Init method of an older version

• Incompatible with an older resource type version's starting methods (Prenet_stop and Start)

The cluster administrator must take the resource offline before upgrading.

WHEN_DISABLED

Similar to WHEN_OFFLINE. However, the cluster administrator must disable the resource before upgrading.

WHEN_UNMANAGED

Use when the new resource type version's Fini method is incompatible with the Init method of an older version. The cluster administrator must switch the existing resource group to the unmanaged state before upgrading.

If a version of the resource type does not appear in the list of #$upgrade_from directives, the RGM imposes the tunability of WHEN_UNMANAGED to that version by default.

AT_CREATION

Use to prevent existing resources from being upgraded to the new version of the resource type. The cluster administrator must delete and re-create a resource.

Changing the RT_version in an RTR File

You only need to change the RT_version property in an RTR file whenever the contents of the RTR file change. Choose a value for this property that clearly indicates that this version of the resource type is the latest version.

Do not include the following characters in the RT_version string in the RTR file or registration of the resource type fails:

• Space

• Tab

• Slash (/)

• Backslash (\)

• Asterisk (*)

• Question mark (?)

• Comma (,)

• Semicolon (;)

• Left square bracket ([)

• Right square bracket (])

The RT_version property, which is optional in Sun Cluster 3.0, is mandatory starting in Sun Cluster 3.1.

Resource Type Names in Earlier Versions of Sun Cluster

Resource type names in Sun Cluster 3.0 do not contain the version suffix, as shown here:

vendor-id.resource-type

A resource type that was originally registered under Sun Cluster 3.0 continues to have a name that follows this syntax even after the cluster administrator upgrades the clustering software to Sun Cluster 3.1 or later releases. Similarly, a resource type whose RTR file is missing the #$upgrade directive is given a Sun Cluster 3.0 format name (without the version suffix) if the RTR file is registered on a cluster that is running at least Sun Cluster 3.1.

The cluster administrator can register RTR files by using the #$upgrade directive or the #$upgrade_from directive in Sun Cluster 3.0. However, upgrading existing resources to new resource types in Sun Cluster 3.0 is not supported.

What Happens When a Cluster Administrator Upgrades

Here is what the cluster administrator must do or what happens when he or she upgrades a resource type:

• If the existing resource property attributes do not satisfy the validation conditions of the new version of the resource type, the cluster administrator must provide valid values. The cluster administrator must do so under the following conditions:

  • When the new version of the resource type does not have a default value and uses a property that is not declared in the earlier version.

  • When the existing resource uses a property whose value is undeclared or invalid in the new version. Declared properties that are undeclared in a new version of a resource type are deleted from the resource.

• Any attempt to upgrade from an unsupported version of a resource type fails.

• After an upgrade, resources inherit the resource property attributes for all properties from the new version of the resource type.

• If you change the default value of a resource type in the RTR file, the new default value is inherited by existing resources. The new default value is inherited even if the property is declared tunable only AT_CREATION or WHEN_DISABLED. A property of the same type that the cluster administrator creates also inherits this default value. However, if the cluster administrator specifies a new default value for the property, the new default value overrides the default value that is specified in the RTR file.

Resources that were created in Sun Cluster 3.0 do not inherit new default resource property attributes from the resource type when they are upgraded to a later version of Sun Cluster. This limitation applies only to Sun Cluster 3.1 clusters that are upgraded from Sun Cluster 3.0 clusters. The cluster administrator can overcome this limitation by specifying values for the properties and thus overriding the defaults.

Implementing Resource Type Monitor Code

The cluster administrator can register an upgrade-aware resource type in Sun Cluster 3.0. However, Sun Cluster records the resource type name without the version suffix. To run correctly in Sun Cluster 3.0 and Sun Cluster 3.1, the monitor code for this resource type must be able to handle both naming conventions:

vendor-id.resource-type:rt-version
vendor-id.resource-type

The format of resource type names is described in Format of Resource Type Names.

The cluster administrator cannot register the same version of the resource type twice under two different names. To enable the monitor code to determine the correct name, call these commands in the monitor code:

scha_resourcetype_get -O RT_VERSION -T VEND.myrt
scha_resourcetype_get -O RT_VERSION -T VEND.myrt:vers

Then, compare the output values with vers. Only one of these commands succeeds for a particular value of vers.

Determining Installation Requirements and Packaging

Keep the following two requirements in mind when determining installation requirements and packaging for resource type packages:

• When a new resource type is registered, its RTR file must be accessible on disk.

• When a resource of the new type is created, all declared method path names and the monitor program for the new type must be on disk and be executable. The old method and monitor programs must remain in place as long as the resource is in use.

To determine the correct packaging to use, consider the following questions:

• Does the RTR file change?

• Does the default value or tunability of a property change?

• Does the min or max value of a property change?

• Does the upgrade add or delete properties?

• Does the monitor code change?

• Does the method code change?

• Are the new methods, the monitor code, or both compatible with the previous versions?

The answers to these questions will help you determine the correct packaging to use for your new resource type.

Before You Change the RTR File

You do not necessarily need to create new method or monitor code when you modify a resource type. For example, you might only change the default value or tunability of a resource property. In this instance, because you do not change the method code, you only require a new valid path name to a readable RTR file.

If you do not need to reregister the old resource type, the new RTR file can overwrite the previous version. Otherwise, place the new RTR file in a new path.

If the upgrade changes the default value or tunability of a property, use the Validate method for the new version of the resource type to verify that the existing property attributes are valid for the new resource type. If they are not, the cluster administrator can change the properties of an existing resource to the correct values. If the upgrade changes the min, max, or type attributes of a property, the scrgadm command automatically validates these constraints when the cluster administrator upgrades the resource type.

If the upgrade adds a new property or deletes an old property, you probably need to change callback methods or monitor code.

Changing Monitor Code

If you change only the monitor code for a resource type, the package installation can overwrite the monitor binaries.

Changing Method Code

If you change only the method code in a resource type, you must determine whether the new method code is compatible with the old method code. The answer to this question determines whether the new method code must be stored in a new path or whether the old methods can be overwritten.

If you can apply the new Stop, Postnet_stop, and Fini methods (if declared) to resources that were initialized or started by the old versions of the Start, Prenet_stop, or Init methods, the old methods can be overwritten with the new methods.

If applying a new default value to a property causes a method such as Stop, Postnet_stop, or Fini to fail, the cluster administrator must accordingly restrict the state of the resource when the resource type is upgraded.

You enable the cluster administrator to restrict the state of the resource when it is upgraded by limiting the tunability of the Type_version property.

One approach to packaging is to include all earlier versions of a resource type that are still supported in the package. This approach permits the new version of a package to replace the old version of the package, without overwriting or deleting the old paths to the methods. You must decide the number of previous versions to support.

Determining the Packaging Scheme to Use

The following table summarizes the packaging schemes to use for your new resource types.

Documentation to Provide for a Modified Resource Type

Instructions that tell the cluster administrator how to upgrade a resource type are provided in Upgrading a Resource Type in Sun Cluster Data Services Planning and Administration Guide for Solaris OS. To enable the cluster administrator to upgrade a resource type that you modify, supplement these instructions with additional information, as described in this section.

Generally, when you create a new resource type, you need to provide documentation that does the following:

• Describes the properties that you add, change, or delete

• Describes how to make the properties conform to the new requirements

• States the tunability constraints on resources

• Calls out any new default property attributes

• Informs the cluster administrator that he or she can set existing resource properties to their correct values if necessary

Information About What to Do Before Installing an Upgrade

Explain to the cluster administrator what he or she must do before installing the upgrade package on a node, as follows:

• If the upgrade package overwrites existing methods, instruct the cluster administrator to reboot the node in noncluster mode.

• If the upgrade package updates only the monitor code and leaves the method code unchanged, tell the cluster administrator to keep the node running in cluster mode. Also tell the cluster administrator to turn off monitoring of all resource types.

• If the upgrade package updates only the RTR file, leaving the method and monitor code unchanged, tell the cluster administrator to keep the node running in cluster mode. Also tell the cluster administrator to keep monitoring turned on for all resource types.

Information About When to Upgrade Resources

Explain to the cluster administrator when he or she can upgrade resources to a new version of the resource type. The conditions under which the cluster administrator can upgrade the resource type depend on the tunability of the #$upgrade_from directive for each version of the resource in the RTR file, as follows:

• Any time (ANYTIME)

• Only when the resource is unmonitored (WHEN_UNMONITORED)

• Only when the resource is offline (WHEN_OFFLINE)

• Only when the resource is disabled (WHEN_DISABLED)

• Only when the resource group is unmanaged (WHEN_UNMANAGED)

Example 4–2 How #$upgrade_from Defines When a Cluster Administrator Can Upgrade

This example shows how the tunability of the #$upgrade_from directive affects the conditions under which the cluster administrator can upgrade a resource to a new version of a resource type.

#$upgrade_from   "1.1"   WHEN_OFFLINE
#$upgrade_from   "1.2"   WHEN_OFFLINE
#$upgrade_from   "1.3"   WHEN_OFFLINE
#$upgrade_from   "2.0"   WHEN_UNMONITORED
#$upgrade_from   "2.1"   ANYTIME
#$upgrade_from   ""      WHEN_UNMANAGED

Information About Changes to Resource Properties

Describe any changes that you have made to the resource type that require the cluster administrator to modify properties of existing resources when he or she upgrades. Possible changes that you can make include the following:

• Default settings of existing resource type properties that you have changed

• New extension properties of the resource type that you have introduced

• Existing properties of the resource type that you have withdrawn

• Changes to the set of standard properties that you have declared for the resource type

• Attributes of resource properties such as min, max, arraymin, arraymax, default, and tunability that you have changed

• Changes to the set of methods that you have declared

• Implementation of methods or the fault monitor that you have changed