Cluster Policy APIs

The information provided here includes:

• Cluster Policy APIs--Introduction
• Defined Cluster Policies
• Cluster Policy API List

Cluster Policy APIs--Introduction

Cluster policies manage specific behaviors related to a cluster. Cluster policy information is distributed to all nodes in a cluster.

All cluster policies share some common information:

Policy Name

Each policy has a defined policy name. The supported cluster policy names are:

• QCST_AD_CREATE - Automatically add monitored resource entries (MREs) to a cluster administrative domain when the specified resource types are created.
• QCST_AD_DELETE - Change existing behavior to automatically delete resources on all nodes in the administrative domain and remove the MREs when the specified resource types have been deleted on all the nodes.
• QCST_AD_RESTORE - Change existing behavior to use the attribute values of the restored resource rather than modifying the attribute values of the restored resource to match the attribute values stored in the cluster administrative domain for the specified resource types.
• QCST_CRG_CANCEL_FAILOVER - Change the failover behavior for the specified failover scenario, specifying whether the failover should continue or be automatically cancelled.

Domain Type

The type of domain for which the policy is supported. The supported domain types are:

Policy Qualifier and Policy Value

The possible values in these fields will be defined separately for each policy, but most policies share a common format for these fields. The format is very similar to the control language (CL) command parameter format, with one or more pairs consisting of a keyword and a value for that keyword. Each keyword/value pair must be specified using the CL rules for parameters in keyword form. The values must be defined as specified in the CL rules for parameter values. Each policy will define a list of permissible keywords and permissible values for each keyword.

Examples:

LIB(NAME1 NAME2)
     One keyword, LIB, with the corresponding value 'NAME1 NAME2'.
LIB(*ALL) OBJ(NAME)
     Two keywords, LIB and OBJ, with the values *ALL and NAME respectively.

Defined Cluster Policies

Defined cluster policies:

• QCST_AD_CREATE
• QCST_AD_DELETE
• QCST_AD_RESTORE
• QCST_CRG_CANCEL_FAILOVER

QCST_AD_CREATE

The QCST_AD_CREATE policy will specify which resources will be automatically added to the specified cluster administrative domain when the resource is created. Normally resources must be manually added to the cluster administrative domain after they are created. If a QCST_AD_CREATE policy is specified for a resource type and a resource of that type is created, a monitored resource entry (MRE) will be automatically created for the resource. This MRE will monitor all of the attributes for the resource.

Each QCST_AD_CREATE policy is uniquely defined by the cluster administrative domain name specified in the domain name field and the resource type specified in the RSCTYPE keyword in the policy qualifier field. The name of any defined cluster administrative domain resource type may be specified. In addition the special value *ALL can be specified for the resource type, indicating all resource types supported by the QCST_AD_CREATE policy.

Each resource type will be covered by at most one QCST_AD_CREATE policy. When a resource is created the cluster administrative domain will look for a matching policy in the following order:

1. Check for a QCST_AD_CREATE policy with a matching resource type.
2. Check for a QCST_AD_CREATE policy with RSCTYPE(*ALL).

For example, if a QCST_AD_CREATE policy is defined for RSCTYPE(*ALL) and another QCST_AD_CREATE policy is defined for RSCTYPE(*JOBD) in the same cluster administrative domain, when a *JOBD resource is created it will use the QCST_AD_CREATE policy for RSCTYPE(*JOBD), and when a resource of any other resource type is created it will use the policy for RSCTYPE(*ALL).

Resource types supported by the QCST_AD_CREATE policy:

• *ASPDEV
• *AUTL¹
• *CLS²
• *ETHLIN
• *JOBD²
• *OPTDEV
• *PRTDEV¹
• *SBSD²
• *TAPDEV
• *USRPRF

¹ This resource type requires the IBM PowerHA SystemMirror for i product.
² This resource type requires a LIB value in the policy value field.

The policy value field can be used to specify a list of libraries for a QCST_AD_CREATE policy in the LIB keyword. The following values are supported on the LIB keyword:

At the time a QCST_AD_CREATE policy is created or changed the libraries specified on the LIB keyword in the policy value field are not required to exist. A diagnostic message will be sent indicating that the specified library does not exist, but the command or API will complete successfully. If the library is later created it will be properly handled by the QCST_AD_CREATE policy.

Starting with cluster modification level 5 the QCST_AD_CREATE policy affects resources created on inactive nodes or when the cluster is partitioned. See the documentation for the Add Monitored Resource Entry API for information on how conflicts arising from adding the same resource to the cluster administrative domain on different nodes at the same time is resolved. Prior to cluster modification level 5 the QCST_AD_CREATE policy only affected resources created on active cluster nodes in a cluster that was not partitioned. If a resource that would be covered by a QCST_AD_CREATE policy was created on an inactive cluster node, or on an active cluster node in a partitioned cluster, a message was sent to the QSYSOPR joblog indicating that the resource was not added to the cluster administrative domain.

Example:

Two QCST_AD_CREATE policies defined for cluster administrative domain AD1:
RSCTYPE(*ALL) LIB(*ALL)
RSCTYPE(*JOBD) LIB(PROD1 PROD2)

With this configuration any *JOBD resource created in library PROD1 or PROD2 will automatically be added to the cluster administrative domain. Any resource with a resource type other than *JOBD will automatically be added to the cluster administrative domain regardless of what library it is created in.

QCST_AD_DELETE

When a resource is deleted on a node in a cluster administrative domain the cluster administrative domain will check to see if the resource is covered by a QCST_AD_DELETE policy. If the resource is covered by a QCST_AD_DELETE policy the resource will be deleted on all other active cluster nodes and the monitored resource entry (MRE) for the resource will be removed from the cluster administrative domain. If the resource is not covered by a QCST_AD_DELETE policy the MRE for the resource will be marked as failed, indicating that the resource is no longer tracked by the cluster administrative domain. The resource must be manually deleted on other nodes in the cluster administrative domain, and the MRE must be manually removed.

Each QCST_AD_DELETE policy is uniquely defined by the cluster administrative domain name specified in the domain name field and the resource type specified in the RSCTYPE keyword in the policy qualifier field. The name of any defined cluster administrative domain resource type may be specified. In addition the special value *ALL can be specified for the resource type, indicating all resource types supported by the QCST_AD_DELETE policy. Each resource type will be covered by at most one QCST_AD_DELETE policy. When a resource is deleted the cluster administrative domain will look for a matching policy in the following order:

1. Check for a QCST_AD_DELETE policy with a matching resource type.
2. Check for a QCST_AD_DELETE policy with RSCTYPE(*ALL).

For example, if a QCST_AD_DELETE policy is defined for RSCTYPE(*ALL) and another QCST_AD_DELETE policy is defined for RSCTYPE(*JOBD) in the same cluster administrative domain, when a *JOBD resource is deleted it will use the QCST_AD_DELETE policy for RSCTYPE(*JOBD), and when a resource of any other resource type is deleted it will use the policy for RSCTYPE(*ALL).

• *ASPDEV
• *AUTL¹
• *CLS²
• *ENVVAR
• *ETHLIN
• *JOBD²
• *OPTDEV
• *PRTDEV¹
• *SBSD²
• *TAPDEV
• *USRPRF

¹ This resource type requires the IBM PowerHA SystemMirror for i product.
² This resource type requires a LIB value in the policy value field.

The policy value field can be used to specify a list of libraries for a QCST_AD_DELETE policy in the LIB keyword. The following values are supported on the LIB keyword:

Note that at the time a QCST_AD_DELETE policy is created or changed the libraries specified on the LIB keyword in the policy value field are not required to exist. A diagnostic message will be sent indicating that the specified library does not exist, but the command or API will complete successfully. If the library is later created it will be properly handled by the QCST_AD_DELETE policy.

If a resource covered by a QCST_AD_DELETE policy is deleted on a node in a cluster administrative domain and the node is not active in the cluster, or the cluster administrative domain is inactive, the MRE will be marked as delete pending. If the resource is deleted on a node in a partitioned cluster, the resource will be deleted on all accessible nodes and the MRE will be marked as delete pending. When the node joins an active administrative domain or when the partition is merged the resource will be deleted on the remaining nodes and, if all nodes in the cluster administrative domain are active, the MRE will be removed from the cluster administrative domain.

Example:

Two QCST_AD_DELETE policies defined for cluster administrative domain AD1:
RSCTYPE(*ALL) LIB(*ALL)
RSCTYPE(*JOBD) LIB(PROD1 PROD2)

With this configuration any *JOBD resource deleted in library PROD1 or PROD2 will automatically be removed from the cluster administrative domain. Any resource with a resource type other than *JOBD will automatically be removed from the cluster administrative domain regardless of what library it is deleted in.

QCST_AD_RESTORE

The QCST_AD_RESTORE policy will specify which resources will be properly restored in the specified cluster administrative domain. Normally resources with a monitored resource entry (MRE) in the cluster administrative domain which are restored are immediately updated to match the attribute values in the cluster administrative domain (essentially undoing the restore operation). When the QCST_AD_RESTORE policy is specified the restored version of the attribute values will be propagated to other nodes in the cluster administrative domain.

Each QCST_AD_RESTORE policy is uniquely defined by the cluster administrative domain name specified in the domain name field and the resource type specified in the RSCTYPE keyword in the policy qualifier field. The name of any supported cluster administrative domain resource type may be specified. In addition the special value *ALL can be specified for the resource type, indicating all resource types supported by the QCST_AD_RESTORE policy.

Each resource type will be covered by at most one QCST_AD_RESTORE policy. When a resource is restored the cluster administrative domain will look for a matching policy in the following order:

1. Check for a QCST_AD_RESTORE policy with a matching resource type.
2. Check for a QCST_AD_RESTORE policy with RSCTYPE(*ALL).

For example, if a QCST_AD_RESTORE policy is defined for RSCTYPE(*ALL) and another QCST_AD_RESTORE policy is defined for RSCTYPE(*JOBD) in the same cluster administrative domain, when a *JOBD resource is restored it will use the QCST_AD_RESTORE policy for RSCTYPE(*JOBD), and when a resource of any other resource type is restored it will use the policy for RSCTYPE(*ALL).

Resource types supported by the QCST_AD_RESTORE policy:

• *ASPDEV
• *AUTL¹
• *CLS²
• *ETHLIN
• *JOBD²
• *OPTDEV
• *PRTDEV¹
• *SBSD²
• *TAPDEV
• *USRPRF

¹ This resource type requires the IBM PowerHA SystemMirror for i product.
² is resource type requires a LIB value in the policy value field.

The policy value field can be used to specify a list of libraries for a QCST_AD_RESTORE policy in the LIB keyword. The following values are supported on the LIB keyword:

Note that at the time a QCST_AD_RESTORE policy is created or changed the libraries specified on the LIB keyword in the policy value field are not required to exist. A diagnostic message will be sent indicating that the specified library does not exist, but the command or API will complete successfully. If the library is later created it will be properly handled by the QCST_AD_RESTORE policy.

If a resource covered by a QCST_AD_RESTORE policy is restored on a node that is not active in the cluster, or in an inactive cluster administrative domain, the monitored resource entry (MRE) for the resource will be marked as 'update pending'. If the resource is restored on a node in a partitioned cluster, the restored attribute values for the resource will be replicated on all accessible nodes. When the node joins an active administrative domain or when the partition is merged the restored attributes for the resource will be replicated on the remaining nodes.

Example:

Two QCST_AD_RESTORE policies defined for cluster administrative domain AD1:
RSCTYPE(*ALL) LIB(*ALL)
RSCTYPE(*JOBD) LIB(PROD1 PROD2)

With this configuration the attribute values for any *JOBD resource restored in library PROD1 or PROD2 will automatically be replicated to all active nodes in the cluster administrative domain. The attribute values for any resource with a resource type other than *JOBD will automatically be replicated to all active nodes in the cluster administrative domain regardless of the library the resource was restored in.

QCST_CRG_CANCEL_FAILOVER

EVENT(*ALL | (*CLUFAIL | *CRGFAIL | *ENDCLUNOD | *ENDSYS
| *ENDTCP | *PWRDWNSYS [*CLUFAIL | *CRGFAIL
| *ENDCLUNOD | *ENDSYS | *ENDTCP | *PWRDWNSYS ...]))

If the QCST_CRG_CANCEL_FAILOVER policy is defined for a given failover event, the failover should be automatically cancelled and the IASP will not be varied off by the CRG on the current primary node. Normally the IASPs will be varied off and a failover will continue unless the cluster message queue or CRG failover queue is used to cancel the failover.

Each QCST_CRG_CANCEL_FAILOVER policy is uniquely defined by the cluster resource group name specified in the domain name field and the failover scope specified in the SCOPE keyword in the policy qualifier field.

The SCOPE keyword has potential values of *SITE, *CRSSITE, and *CRG.

• *SITE indicates that the policy will only apply to failovers where the new primary node is in the same site as the original primary node.
• *CRSSITE indicates that the policy will only apply to failovers where the new primary node is in a different site than the original primary node.
• *CRG indicates that the policy applies to all failovers, regardless of which site the original and new primary nodes are in.

The policy value field contains the EVENT keyword. This keyword contains a space separated list of event types. At least one event type (or the special value *ALL) must be specified. The following failover events are supported by the QCST_CRG_CANCEL_FAILOVER policy:

• *CLUFAIL - The failover was caused by one of the following:
  • CHGCLURCY(*END) ending the QCSTCRGM or QCSTCCTL job
  • Critical job end
  • Node crashed (could also be *CRGFAIL depending on the type of node crash)
• *CRGFAIL - The failover was caused by one of the following:
  • CHGCLURCY(*END) ending a CRG job
  • Critical job end
  • CRG job end
  • Node crashed (could also be *CRGFAIL depending on the type of node crash)
• *ENDCLUNOD - The failover was caused by the ENDCLUNOD command or the QcstEndClusterNode API.
• *ENDSYS - The failover was caused by an ENDSYS or ENDSBS(*ALL) action on the primary node.
• *ENDTCP - The failover was caused by the ENDTCP command being invoked on the primary node.
• *PWRDWNSYS - The failover was caused by the PWRDWNSYS command.
• *CONTINUE - When determining whether to cancel a failover the QCST_CRG_CANCEL_FAILOVER policy will be checked first. If the policy is not defined then the cluster message queue and CRG failover queue will be used.

When determining whether to cancel a failover the QCST_CRG_CANCEL_FAILOVER policy will be checked first. If the policy is not defined then the cluster message queue and CRG failover queue will be used.

Example:

QCST_CRG_CANCEL_FAILOVER policy defined for cluster resource group CRG1:
SCOPE(*SITE)  EVENT(ENDTCP)

Indicates that if a failover is being attempted due to an ENDTCP on the primary node and the first backup node is in the same site that the failover should be cancelled.

Cluster policy API list

The cluster policy APIs are:

• Add Cluster Policy (QcstAddClusterPolicy) adds a cluster policy to the cluster.
• Change Cluster Policy (QcstChangeClusterPolicy) changes an existing defined cluster policy.
• Remove Cluster Policy (QcstRemoveClusterPolicy) removes an existing defined cluster policy.
• Retrieve Cluster Policy (QcstRetrieveClusterPolicy) retrieves information on an existing cluster policy.

[ Back to top | Cluster APIs | APIs by category ]