Chapter 3 Upgrading a Resource Type

This chapter discusses the issues that you need to understand to upgrade a resource type and migrate a resource.

• Overview

• Resource Type Registration File

• Resource Type_version Property

• Migrating a Resource to a Different Version

• Upgrading and Downgrading a Resource Type

• Default Property Values

• Resource Type Developer Documentation

• Resource Type Name and Resource Type Monitor Implementations

• Application Upgrades

• Resource Type Upgrade Examples

• Installation Requirements for Resource Type Packages

Overview

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:

• Any time (Anytime)

• When the resource is unmonitored (When_unmonitored)

• When the resource is offline (When_offline)

• When the resource is disabled (When_disabled)

• When the resource group is unmanaged (When_unmanaged)

• At creation (At_creation)

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.

Resource Type Registration File

Resource Type Name

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 resource_name -G resource_group_name

Resource type names registered prior to Sun Cluster 3.1 continue to use the form:

vendor_id.resource_type

Directives

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

Changing the RT_Version in an RTR file

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 Earlier Versions of Sun Cluster

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.

Resource Type_version Property

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 this property value by using the following command:

scrgadm -c -j resource -y Type_version=new_version

This property's 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:

Anytime

If there are no restrictions on when the resource can be upgraded. The resource can be fully online.

When_unmonitored

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

When_offline

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.

When_disabled

Similar to When_offline. However, this tunability value imposes the stronger condition that the resource be disabled.

When_unmanaged

If the new resource type version's Fini method is not compatible with the Init method of older versions. This tunability value requires the existing resource group to be switched to the unmanaged state before you can upgrade the resource.

At_creation

If resources cannot be upgraded 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.

Migrating a Resource to a Different Version

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.

Upgrading and Downgrading a Resource Type

The section “Upgrading a Resource Type” in Sun Cluster 3.1 Data Service Planning and Administration Guide contains additional information about upgrading or migrating a resource type.

How to Upgrade a Resource Type

1. Read the upgrade documentation for the new resource type to find out the resource type changes and resource tunability constraints.

2. 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.

3. 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

4. If the resource type upgrade is installed on only a subset of the nodes, you must set the Installed_nodes property of the new resource type 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

5. 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.

6. 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.

7. Restore the previous state of the resource or resource group by reversing the command invoked in Step 5.

How to Downgrade a Resource to an Older Version of Its Resource Type

You can downgrade a resource to an older version of its resource type. The conditions under which you can downgrade a resource to an older version of the resource type are more restrictive than when you upgrade to a newer version of the resource type. You must first unmanage the resource group. In addition, you can only downgrade a resource to an upgrade-enabled version of the resource type. You can identify upgrade-enabled versions by using the scrgadm -p command. In the output, upgrade-enabled versions contain the suffix :version.

1. Switch the resource group that contains the resource you want to downgrade offline.

   scswitch -F -g resource_group

2. Disable the resource that you want to downgrade and all resources in the resource group.

   scswitch -n -j resource_to_downgrade scswitch -n -j resource1 scswitch -n -j resource2 scswitch -n -j resource3 ...

   ---

   Note –

   Disable resources in order of dependency, starting with the most dependent (application resources) and ending with the least dependent (network address resources).

   ---

3. Unmanage the resource group.

   scswitch -u -g resource_group

4. Is the old version of the resource type to which you want to downgrade still registered in the cluster?

   • If yes, go to the next step.

   • If no, re-register the old version that you want.

     scrgadm -a -t resource_type_name

5. Downgrade the resource by specifying the old version that you want for Type_version.

   scrgadm -c -j resource_to_downgrade -y Type_version=old_version

   If necessary, edit other properties of the same resource to appropriate values in the same command.

6. Bring the resource group that contains the resource that you downgraded to a managed state, enable all the resources, and switch the group online.

   scswitch -Z -g resource_group

Default Property Values

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 entry in the CCR (cluster configuration repository). 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.

Resource Type Developer Documentation

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

• State the tunability constraints on resources

• 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

Resource Type Name and Resource Type Monitor Implementations

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.

Application Upgrades

The upgrading of application code is unlike 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.

Resource Type Upgrade Examples

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 examples assume that:

• 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 correct scswitch(1M) command or equivalent. The following example shows how to move 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

• You register a resource type by using this command:

  scrgadm -a -t resource_type -f path_to_RTR_file

• You migrate a resource by using this command:

  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.

Installation Requirements for Resource Type Packages

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?

Information That You Need to Know Before Changing the RTR File

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.

Changing Monitor Code

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.

Changing Method Code

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.