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:
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.
This section describes how to set up a resource type registration file.
This section covers the following topics:
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 clresourcetype(1CL) 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.
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.
#$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
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 (“”).
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:
Use when there are no restrictions on when the cluster administrator can upgrade the resource. The resource can be completely online during the upgrade.
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.
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.
Similar to WHEN_OFFLINE. However, the cluster administrator must disable the resource before upgrading.
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.
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.
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 with the Sun Cluster 3.1 release.
Resource type names in Sun Cluster 3.0 do not contain the version suffix, as shown here:
vendor-id.resource-type
The name of a resource type that you registered in Sun Cluster 3.0 retains this syntax in Sun Cluster 3.1 and Sun Cluster 3.2. If you register an RTR file in Sun Cluster 3.1 or Sun Cluster 3.2 that omits the #$upgrade directive, the resource type name also follows this syntax.
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.
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 provide valid values 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.
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.
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.
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 clresourcetype(1CL) 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.
If you change only the monitor code for a resource type, the package installation can overwrite the monitor binaries.
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.
The following table summarizes the packaging schemes to use for your new resource types.
Table 4–1 Determining the Packaging Scheme to Use
Type of Change |
Tunability Value |
Packaging Scheme |
---|---|---|
Make property changes in only the RTR file. |
ANYTIME |
Deliver only new RTR file. |
Update the methods. |
ANYTIME |
Place the updated methods in a different path than the old methods. |
Install the new monitor program. |
WHEN_UNMONITORED |
Overwrite only the previous version of the monitor. |
Update the methods. The new Update and Stop methods are incompatible with the old Start methods. |
WHEN_OFFLINE |
Place the updated methods in a different path than the old methods. |
Update the methods and add new properties to the RTR file. The new methods require new properties. The goal is to allow the containing resource group to remain online but prevent the resource from coming online if the resource group moves from the offline state to the online state on a node. |
WHEN_DISABLED |
Overwrite the previous versions of the methods. |
Update the methods and add new properties to the RTR file. New methods do not require new properties. |
ANYTIME |
Overwrite the previous versions of the methods. |
Update the methods. The new Fini method is incompatible with the old Init method. |
WHEN_UNMANAGED |
Place the updated methods in a different path than the old methods. |
Update the methods. No changes are made to the RTR file. |
Not applicable. No changes are made to the RTR file. |
Overwrite the previous versions of the methods. Because you made no changes to the RTR file, the resource does not need to be registered or upgraded. |
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
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
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.
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)
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
Version |
When the Cluster Administrator Can Upgrade a Resource |
---|---|
1.1, 1.2, or 1.3 |
Only when the resource is offline |
2.0 |
Only when the resource is unmonitored |
2.1 |
Any time |
All other versions |
Only when the resource group is unmanaged |
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