MoveClusterGroupEx 関数 (clusapi.h)

[アーティクル]
08/22/2023

フラグとバッファーを追加して、既存の MoveClusterGroup メソッドを拡張します。フラグはクラスターフェールオーバーポリシーの動作を制御し、入力バッファーを使用すると、クライアントはグループ内のリソースに特別な指示を送信できます。

構文

DWORD MoveClusterGroupEx(
  [in]           HGROUP hGroup,
  [in, optional] HNODE  hDestinationNode,
  [in]           DWORD  dwMoveFlags,
  [in, optional] PBYTE  lpInBuffer,
  [in]           DWORD  cbInBufferSize
);

パラメーター

[in] hGroup

クラスターグループへのハンドル。

[in, optional] hDestinationNode

クラスターノードへのハンドル。グループを移動するノードを示します。このパラメーターは省略可能です。 NULL のままにすると、クラスターとこの特定のグループに対して構成されたフェールオーバーポリシーに従って、クラスターによってグループが最適なノードに移動されます。

[in] dwMoveFlags

この移動操作に関してフェールオーバーポリシーに影響を与えるフラグのビットごとの組み合わせ。

CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS (0x00000001)

リソースが現在のノードの現在の状態で "ロック" する必要があることを示している場合でも、グループを強制的に移動し、必要に応じてリソースを終了します。

CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR (0x00000002)

グループが宛先ノードの永続的な状態に到達できない場合 ( hDestinationNode で指定されているか、クラスターによって選択されているかに関係なく)、グループをソースノードに返し、その永続的な状態に戻します。

CLUSAPI_GROUP_MOVE_QUEUE_ENABLED (0x00000004)

グループ内のリソース DLL が、現時点では移動できないことを示しているが、近い将来に可能になる可能性がある場合は、クラスターサービスでこの移動をキューに入れ、移動操作が完了するか、クライアントによって取り消されるまで、適切と見なされた場合に再試行を続行します。

CLUSAPI_GROUP_MOVE_HIGH_PRIORITY_START (0x00000008)

グループを永続的な状態に移行する順序や優先順位付けを管理する実装固有のポリシーに関係なく、このグループをできるだけ早く宛先ノードの永続的な状態にします。

CLUSAPI_GROUP_MOVE_FAILBACK (0x00000010)

予約済み。

[in, optional] lpInBuffer

グループ内の特定のリソースに対する移動操作命令を含むプロパティリスト。命令はプロパティ値に含まれています。グループ内のリソースは、移動操作でサポートされているプロパティ名をプロパティリストで検索し、関連付けられているプロパティ値の指示を解釈します。 MoveClusterGroupEx 操作でリソースによってサポートされるプロパティは、リソースに関連付けられているプライベートプロパティとは関係ありません。

[in] cbInBufferSize

lpInBuffer のサイズ (バイト単位)。

戻り値

MoveClusterGroupEx は、move コマンドが受け入れられ、進行中 の場合に ERROR_IO_PENDINGを返します。 MoveClusterGroupEx は、グループの状態を変更せず、move コマンドがすぐに拒否された場合、0 以外のエラーコードを返します。たとえば、これは、移動要求時に hDestinationNode が Up でない場合に発生します。

注釈

moveClusterGroupExは、CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS フラグが設定されておらず、グループ内のリソースがオンラインで、現在の状態で "ロック" されていることを示している場合、エラー ERROR_CLUSTER_RESOURCE_LOCKED_STATUSですぐに失敗します。

MoveClusterGroupEx がERROR_IO_PENDINGを返した後、次のようにいくつかの結果が得られます。

移動操作が成功し、グループがターゲットノードの永続的な状態に達する可能性があります。
グループがターゲットノードの永続的な状態に到達できないという点で、移動操作が失敗する可能性があります。 dwMoveFlags にCLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERRORが含まれていない場合、クラスターは (構成されたポリシーに従って) 適切なアクションを実行して、クラスター内の他のノードでグループを永続的な状態にします。 dwMoveFlags にCLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERRORが含まれている場合、クラスターはグループをソースノードの永続的な状態に戻そうとします。これが失敗した場合、クラスターは (構成されたポリシーに従って) 適切なアクションを実行して、クラスター内の他のノードでグループを永続的な状態にします。
リソースがすぐに移動できないことを示し、CLUSAPI_GROUP_MOVE_QUEUE_ENABLED フラグが設定されている場合は、移動操作をキューに入れる可能性があります。
移動操作は、グループ内のリソースによって拒否される可能性があるため、障害数を増やしたり、障害ポリシーをトリガーしたりすることなく、グループをソースノードの永続的な状態に戻すことができます。 これは、CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS フラグが設定されている場合は発生できません。

仮想マシンのライブマイグレーションの場合は、次の手順を実行します。

dwMoveFlags パラメーターで、CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR、CLUSAPI_GROUP_MOVE_QUEUE_ENABLED、およびCLUSAPI_GROUP_MOVE_HIGH_PRIORITY_STARTフラグを設定します。
lpInBuffer パラメーターで、プロパティリストに、CLUSPROP_FORMAT_DWORD のCLUSTER_PROPERTY_FORMAT列挙値 (プロパティのデータ形式を表す) と VmResdllContextLiveMigration のプロパティ値を指定する "Virtual Machine" または "Virtual Machine Configuration" という名前のリソースの種類を追加します (仮想マシンアクションのVM_RESDLL_CONTEXT列挙体から)。

MoveClusterGroupEx では、クライアントにクラスターセキュリティ記述子のフルアクセスが付与されている必要があります。

例

#include "stdafx.h"
#include <windows.h>
#include <stdio.h>
#include <ClusAPI.h>


#define DemoResDllTypeName L"dummy"
#define DemoGroupName L"DemoGroup"


int __cdecl main( void )
{
    HCLUSTER hCluster= NULL;
    HGROUP hGroup = NULL;
    DWORD error = 0;

    hCluster = OpenCluster( NULL );
    if ( hCluster == NULL )
    {
        error = GetLastError();
        wprintf( L"Failed to open cluster: 0x%x\n", error );
        goto Cleanup;
    }

    hGroup = OpenClusterGroup( hCluster, DemoGroupName );
    if ( hGroup == NULL )
    {
        error = GetLastError();
        wprintf( L"Failed to open cluster group " DemoGroupName L": 0x%x\n", error );
        goto Cleanup;
    }


    // Move Group example
    error = MoveClusterGroupEx( hGroup,
                                NULL,
                                CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR | CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS,
                                NULL,
                                0);

    if ( error == ERROR_IO_PENDING  )
    {
        wprintf( L"Group move pending" DemoGroupName L": 0x%x\n", error );
        error = ERROR_SUCCESS;
    }
    else if ( error != ERROR_SUCCESS)
    {
        wprintf( L"Failed to move group" DemoGroupName L": 0x%x\n", error );
    }
    else 
    {
        wprintf( L"Group move completed" DemoGroupName L": 0x%x\n");
    }

Cleanup:

    if ( hGroup != NULL )
    {
        CloseClusterGroup( hGroup );
        hGroup = NULL;
    }
    if ( hCluster != NULL )
    {
        CloseCluster( hCluster );
        hCluster = NULL;
    }

    return (int)error;
}

要件

要件	値
サポートされている最小のクライアント	サポートなし
サポートされている最小のサーバー	Windows Server 2012
対象プラットフォーム	Windows
ヘッダー	clusapi.h
Library	ClusAPI.lib
[DLL]	ClusAPI.dll

次の方法で共有