Sun Cluster 3.1 Data Services Developer's Guide

Chapter 3 Resource Type Upgrade

This chapter discusses the issues the resource type developer needs to understand in order to provide resource type upgrade and resource migration

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:

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:

See Resource Type_version Property for an explanation of each option.


Note –

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 <resourcename> -G <resourcegroupname>

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 it using the following command:


scrgadm -c -j <resource> -y Type_version=<new version>

Its tunability is derived from:

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, it imposes the stronger condition that the resource be disabled.

When_unmanaged

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.

At_creation

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.

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:


Note –

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.


Resource Type Upgrade

See “property_attributes” in Sun Cluster Data Services Guide for additional information on upgrading or migrating a resource type.

Resource Type Upgrade
  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, 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>
  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.

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


Note –

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:

Resource Type Names 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 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.

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 of the examples use the following assumptions:

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. 

For each node:

  • Take the node out of the cluster

  • Do a

    pkgrm/pkgadd of the methods being updated

  • Restore the node to the cluster

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. 

For each node:

  • Take the node out of the cluster

  • Do a pkgrm/pkgadd of the methods being updated

  • Restore the node to the cluster

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. 

For each node:

  • Take the node out of the cluster

  • Do a pkgadd of the updated methods

  • Restore the node to the cluster.

Because there were no changes to the RTR file, the resource does not need to be registered or migrated. 

Packaging Issues

There are two requirements related to the installation of the new resource type packages:

RTR File Change

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.

Monitor Code Change

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.

Method Code Change

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.


Note –

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.