This chapter discusses the issues the resource type developer needs to understand in order to provide resource type upgrade and resource migration
System administrators require the ability to install and register a new version of an existing resource type, to allow the registration of multiple versions of a given resource type, and to migrate an existing resource to a new version of the resource type without having to delete and recreate the resource. Resource developers need to understand the requirements for providing resource type upgrade and resource migration.
Resource types developed with upgrade in mind are called upgrade aware.
A new version of a resource type can differ from a previous version in several ways:
Attributes of resource type properties may change
The set of declared resource properties, including standard and extension properties, may change
Attributes of resource properties, such as default, min, max, arraymin, arraymax, or tunability may change
The set of declared methods may differ
The implementation of methods or monitors may change.
The resource type developer decides when an existing resource can be migrated to a new version from among the following tunability options. The options are listed from least restrictive to most restrictive:
Throughout this chapter, the scrgadm command is used when discussing how to do an upgrade. The administrator is not restricted to using the scrgadm command but can also use the GUI or the scsetup command to do the upgrade.
The three components of the resource type name are properties 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 provided by different vendors. The RT_version distinguishes between multiple registered versions (upgrades) of the same base resource type. To ensure that the Vendor_id is unique, the recommended approach is to use the stock symbol for the company creating the resource type.
Registration of the resource type will fail if the RT_version string includes a blank, tab, slash, backslash, asterisk, question mark, comma, semicolon, left square bracket, or right square bracket character.
The RT_Version property, which was optional in Sun Cluster 3.0, is mandatory starting in Sun Cluster 3.1.
The fully qualified name is the name returned by the following command:
scha_resource_get -O Type -R <resourcename> -G <resourcegroupname> |
Resource type names registered prior to Sun Cluster 3.1 continue to use the form:
vendor_id.resource_type |
RTR files for upgrade aware resource types must include a #$upgrade directive, followed by zero or more directives of the form:
#$upgrade_from <version> <tunability> |
The upgrade_from directive consists of the string #$upgrade_from, followed by the RT_Version, followed by the tunability constraint on the resource. If the resource type from which the upgrade is being performed does not have a version, the RT_Version is specified as the empty string, as shown in the last example below:
#$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 RGM enforces these constraints on a resource when the system administrator attempts to change the resource Type_version. If the current version of the resource type does not appear in the list, the RGM imposes the tunability of When_unmanaged.
These directives must appear between the resource type property declarations section of the RTR file and the resource declarations section of the RTR file. See rt_reg(4).
Change the RT_Version string in an RTR file whenever the contents of the RTR file changes. The value of this property must make it obvious which is the newer version of the resource type and which is the older. There is no need to change the RT_Version string if there are no changes to the RTR file.
Resource type names in Sun Cluster 3.0 did not contain the version suffix:
vendor_id.resource_name |
A resource type that was originally registered under Sun Cluster 3.0 continues to have a name of this form even after you upgrade the clustering software to Sun Cluster 3.1. 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 running Sun Cluster 3.1 software.
You can register RTR files with the #$upgrade or #$upgrade_from directive in Sun Cluster 3.0, but, migrating existing resources to new resource types in Sun Cluster 3.0 is not supported.
The standard resource property Type_version stores the RT_Version property of a resource's type. This property does not appear in the RTR file. The system administrator edits it using the following command:
scrgadm -c -j <resource> -y Type_version=<new version> |
Its tunability is derived from:
The current version of the resource type
The #$upgrade_from directives in the RTR file
Use the following tunability values in the #$upgrade_from directives:
If there are no restrictions on when the resource can be upgraded; the resource can be fully online.
If the new resource type version's Update, Stop, Monitor_check, and Postnet_stop methods are known to be compatible with older resource type version's starting methods (Prenet_stop and Start), and if the new resource type version's Fini method is known to be compatible with the Init method of older versions. This scenario requires only that the resource monitor program be stopped before the upgrade
If the new resource type version's Update, Stop, Monitor_check, or Postnet_stop methods are known not to be compatible with older resource type version's starting methods (Prenet_stop and Start) but are known to be compatible with the Init method of older versions, the resource must be offline when the type upgrade is applied to it.
Similar to When_offline; however, it imposes the stronger condition that the resource be disabled.
If the new resource type version's Fini method is known not to be compatible with the Init method of older versions; this requires the existing resource group to be switched to the unmanaged state prior to upgrading the resource.
If resources are not upgradable to the new resource type version; only new resources of the new version can be created.
The tunability of At_creation means that the resource type developer can prohibit the migration of an existing resource to the new type. In this case, the system administrator must delete and recreate the resource. This is equivalent to declaring that the resource's version can only be set at creation time.
An existing resource takes on the new resource type version when the system administrator edits the Type_version property of the resource. This follows the same conventions that are used to edit other resource properties, except that some information will be derived or taken from the new resource type version instead of the current version:
Resource property attributes for all properties such as min, max, arraymin, arraymax, default, and tunability are taken from the new resource type version
The tunability applicable to the Type_version property is taken from the #$upgrade_from directives in the RTR file and the RT_version property of the resource type of the existing resource. This tunability is unlike the tunability described in property_attributes(5).
The Validate method for the new resource type version will be applied. This ensures that the property attributes are valid for the new resource type. If the existing resource property attributes do not satisfy the validation conditions of the new resource type version, the system administrator has to provide valid values for such properties on the scrgadm command line. This can occur if the newer resource type version starts to use a property that was not declared in the earlier version and which does not have a default. It might also occur if the existing resource already has a property which was assigned a value that is invalid for the newer resource type version.
Resource properties that were declared in an older version of the resource type can be undeclared in the newer version. When the resource is migrated to the newer version, the property will be deleted from the resource.
The Validate method can query the current Type_version of the resource (using scha_resource_get) as well as the new Type_version (which is passed on the Validate command line). Therefore, Validate can rule out upgrades from unsupported versions.
See “property_attributes” in Sun Cluster Data Services Guide for additional information on upgrading or migrating a resource type.
Read the upgrade documentation for the new resource type to find out the resource type changes and resource tunability constraints.
Install the resource type upgrade package on all cluster nodes.
The recommended practice for installing new resource type packages is in a rolling upgrade fashion: the pkgadd occurs while the node is booted in non-cluster mode.
There are scenarios in which it would be possible to install new resource type packages on a node in cluster mode:
If resource type package installation leaves the method code unchanged and only updates the monitor, then it is necessary to stop monitoring on all resources of that type during the installation.
If resource type package installation leaves both the method and monitor code unchanged then it is not necessary to stop monitoring on the resource during the installation, because the installation is only putting a new RTR file on the disk.
Register the new resource type version using the scrgadm (or equivalent) command, referencing the RTR file of the upgrade.
The RGM creates a new resource type whose name is of the form
vendor_id.resource_type:version |
If the resource type upgrade is installed on only a subset of the nodes, then an additional step must be taken; the Installed_nodes property of the new resource type must be set to the nodes on which it is actually installed. When a resource takes on the new type (either by being newly created or updated), the RGM requires that the resource group nodelist be a subset of the Installed_nodes list of the resource type.
scrgadm -c -t <resource_type> -h <installed_node_list> |
For each resource of the preupgraded type that is to be migrated to the upgraded type, invoke scswitch to change the state of the resource or its resource group to the appropriate state as dictated by the upgrade documentation.
For each resource of the preupgraded type that is to be migrated to the upgraded type, edit the resource, changing its Type_version property to the new version.
scrgadm -c -j <resource> -y Type_version=<new version> |
If necessary, edit other properties of the same resource to appropriate values in the same command.
Restore the previous state of the resource or resource group by reversing the command invoked in Step 5.
The RGM stores all resources such that any property that was not explicitly set by the system administrator (and which was defaulted) is not stored in the resource CCR entry. The RGM obtains the default value of a missing resource property from the resource type (or if not defined there, using a system-defined default) when a resource is read in from the CCR. It is this method of storing properties that permits an upgraded resource type to define new properties or new default values for existing properties.
When resource properties are edited, the RGM stores in the CCR the properties that were specified in the edit command.
If an upgraded version of the resource type declares a new default value for a defaulted property, the new default value is inherited by existing resources, even if the property is declared tunable only At_creation or When_disabled. If the application of the new default would cause a method such as Stop or Postnet_stop or Fini to fail, the resource type implementor must accordingly restrict the state of the resource at the time that it is upgraded. This is done by limiting the tunability of the Type_version property.
The new resource type version Validate method can check to make sure that existing property attributes are appropriate. If they are not, the system administrator can edit the properties of an existing resource to appropriate values in the same command that edits the Type_version property to upgrade the resource to the new resource type version.
Resources that were created in Sun Cluster 3.0 do not inherit new default property attributes from the resource type when they are migrated to a later version because their default properties are stored in the CCR.
The resource type developer must provide documentation with the new resource that provides the following information:
Describe any property additions, changes, or deletions
Describe how to make the properties conform to the new requirements
Call out any new default property attributes
Inform the system administrator that existing resource properties are editable to appropriate values using the same command used to edit the Type_version property to upgrade the resource to the new resource type version
You can register an upgrade aware resource type in Sun Cluster 3.0, but its name is recorded in the CCR without the version suffix. To run correctly in both Sun Cluster 3.0 and Sun Cluster 3.1, the monitor for this resource type must be able to handle both naming conventions:
vendor_id.resource_name:version vendor_id.resource_name |
The monitor code can determine the proper name to use by running the equivalent of:
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 will succeed for a particular value of vers, because it is not possible to register the same version of the resource type twice under two different names.
The upgrade of application code is orthogonal to the upgrading of agent code, although some of the issues are similar. An application upgrade might or might not be accompanied by a resource type upgrade.
These examples illustrate several different resource type installation and upgrade scenarios. Tunability and packaging information have been chosen based on the types of changes made to the resource type implementation. Tunability applies to the migration of the resource to the new resource type.
All of the examples use the following assumptions:
The resource type is delivered in a Solaris-style package. See pkgadd(1M) and pkgrm(1M).
There is only one previous version of the resource type and, therefore, only one #$upgrade_from directive in the new RTR file
The installation procedure will not remove or overwrite the methods if it is possible that the RGM could call the methods while they are removed from the disk
New methods are compatible with old methods unless otherwise stated
Resources and resource groups are moved to the required state before installation or migration using the appropriate scswitch(1M) command or equivalent. The following example shows moving the resource group to an unmanaged state:
scswitch -M -n -j <resource> scswitch -n -j <resource> scswitch -F -g <resource group> scswitch -u -g <resource group> |
Registration is performed using the equivalent of:
scrgadm -a -t <resource type> -f <path to RTR file> |
Migration is performed using the equivalent of:
scrgadm -c -j <resource> -y Type_version=<version> \ -y <property=value> \ -x <property=value> ... |
Resources and resource groups are restored to their previous state after migration using the appropriate scswitch(1M) command or equivalent:
scswitch -M -e -j <resource> scswitch -e -j <resource> scswitch -o -g <resource group> scswitch -Z -g <resource group> |
The resource type developer might need to specify more restrictive tunability values than the ones used in these examples. The tunability values depend on the exact changes made to the resource type implementation. Also, the resource type developer might choose to use a different packaging scheme in place of the Solaris-style packaging used in these examples.
Table 3–1 Resource Type Upgrade Examples
Type of change |
Tunability |
Packaging |
Procedure |
---|---|---|---|
Property changes are only made in the RTR file. |
Anytime |
Only deliver new RTR file. |
Do a pkgadd of the new RTR file on all nodes. Register the new resource type. Migrate the resource. |
Methods are updated. |
Anytime |
Place the updated methods in a distinct path from the old methods. |
Do a pkgadd of the updated methods on all nodes. Register the new resource type. Migrate the resource. |
New monitor program. |
When_unmonitored |
Only overwrite the previous version of the monitor. |
Disable monitoring. Do a pkgadd of the new monitor program on all nodes. Register the new resource type. Migrate the resource. Enable monitoring. |
Methods are updated; the new Update/Stop methods are incompatible with the old Start methods. |
When_offline |
Place the updated methods in a distinct path from the old methods. |
Do a pkgadd of the updated methods on all nodes. Register the new resource type. Take the resource offline. Migrate the resource. Bring the resource online. |
Methods are updated and new properties are added to the RTR file; the new methods require new properties. (The goal is to allow the containing resource group to remain online but to prevent the resource from coming online should the resource group move from the offline state to the online state on a node.) |
When_disabled |
Overwrite the previous versions of the methods. |
Disable the resource.
Register the new resource type. Migrate the resource. Enable the resource. |
Methods are updated and new properties are added to the RTR file; new methods do not require new properties. |
Anytime |
Overwrite the previous versions of the methods. |
During this procedure, the RGM will call the new methods even though migration (which would configure the new properties) has not yet been performed. It is important that the new methods be able to work without the new properties. Register the new resource type. Migrate the resource. |
Methods are updated; the new Fini method is incompatible with the old Init method. |
When_unmanaged |
Place the updated methods in a distinct path from the old methods. |
Make the containing resource group unmanaged. Do a pkgadd of the updated methods on all nodes. Register the resource type. Migrate the resource. Make the containing resource group managed. |
Methods are updated; no changes made to the RTR file. |
N/A; no changes to RTR file |
Overwrite the previous versions of the methods. |
Because there were no changes to the RTR file, the resource does not need to be registered or migrated. |
There are two requirements related to the installation of the new 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 of the declared method pathnames and the monitor program for the new type must be on disk and executable. The old method and monitor programs must remain in place as long as the resource is in use.
To decide on the most appropriate packaging, the resource type implementor must consider the following:
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 method code change?
Does the monitor code change?
Are the new methods or monitor code compatible with the previous version?
Some resource type upgrades do not involve new method or monitor code. For example, a resource type upgrade might only change the default value or tunability of a resource property. Since the method code is not changing, the only requirement for installing the upgrade is to have a valid pathname to a readable RTR file.
If there is no need to reregister the old resource type, the new RTR file can overwrite the previous version. Otherwise the new RTR file can be placed in a new pathname.
If the upgrade changes the default value or tunability of a property, the Validate method for the new version can verify at migration time that the existing property attributes are valid for the new resource type. If the upgrade changes the min, max, or type attributes of a property, the scrgadm command automatically validates these constraints at migration time.
The upgrade documentation must call out any new default property attributes. The documentation must inform the system administrator that existing resource properties are editable to appropriate values using the same command that edits the Type_version property to upgrade the resource to the new resource type version.
If the upgrade adds or deletes properties, it is likely that some callback methods or monitor code also must be changed.
If the monitor code is the only change in the updated resource type, then the package installation can overwrite the monitor binaries. The documentation must instruct the system administrator to suspend monitoring before installing the new package.
If the method code is the only change in the updated resource type, it is important to determine whether the new method code is compatible with the previous version. This determines whether the new method code must be stored in a new pathname or whether the old methods can be overwritten.
If the new Stop, Postnet_stop and Fini methods (if declared) can be applied to resources that were initialized or started by the old versions of the Start, Prenet_stop, or Init methods, then it is possible to overwrite the old methods with the new methods.
If the new method code is not compatible with the previous version, then it is necessary to stop or unconfigure a resource using the old versions of the methods before it can be migrated to the upgraded resource type. If the new methods overwrite the old ones, it can require shutting down (and possibly unmanaging) all resources of the type before doing the resource type upgrade. If the new methods are stored separately from the old (and both are accessible at once), then even without backward compatibility it is possible to install the new resource type version and upgrade the resources one by one.
Even if the new methods are backward compatible, it might be a requirement to upgrade one resource at a time to use the new methods, while other resources continue to use the old methods. It still is necessary to store the new methods in a separate directory rather than overwriting the old ones.
An advantage to storing each resource type version's methods in a separate directory is that it makes it easy to switch resources back to the older resource type version if a problem arises with the newer version.
One packaging approach is to include all of the earlier versions that are still supported in the package. This permits the new package version to replace the older version, without overwriting or deleting the old method paths. It is up to the resource type developer to decide how many previous versions to support.
It is not recommended to overwrite methods or pkgrm/pkgadd methods on a node that is currently in the cluster. If the RGM were to call a method when the method is not accessible on disk, unexpected results can occur. Removing or replacing the binary of a running method might also cause unexpected results.