NOTE: This page is no longer being updated. To install the latest version of DSC Resource Kit, please use the PowerShell Gallery. If you need to report issues or would like to contribute to development, check out our GitHub Repositories.

Introduction

The xFailOverCluster module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains the xCluster and xWaitForCluster resources. These DSC Resource allows you to create and configure a fail over cluster.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The "x" in xFailOverCluster stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xFailOverCluster module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point). There are also great community resources, such as PowerShell.org, or PowerShell Magazine. For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xFailOverCluster module

  • Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:

  • Run Get-DSCResource to see that xCluster and xWaitForCluster is among the DSC Resources listed

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xFailOverCluster module contains the xCluster and xWaitForCluster DSC Resource. This DSC Resource allows you to configure a computer by changing its name and modifying its domain or workgroup.  The xCluster resource is responsible for ensuring that a group of machines form a cluster.  The xWaitForCluster resource is responsible for ensuring that the node waits for a cluster to be created.

Details

xCluster resource has following properties:

  • Name:                                                 Name of the cluster
  • StaticIPAddress:                                Static IP Address of the cluster
  • DomainAdministratorCredential: Credential used to create the cluster

xWaitForCluster resource has following properties:

  • Name:                                                 Name of the cluster to wait for
  • RetryIntervalSec:                              Interval to check for cluster existence
  • RetryCount:                                       Maximum number of retries to check for cluster existance
  • Credential:                                        Credential to be used to join or leave domain

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xFailOverCluster becomes cFailOverCluster)
    • Resource folder (ex: MSFT_xCluster becomes Contoso_cCluster)
    • Resource Name (ex: MSFT_xCluster becomes Contoso_cCluster)
    • Resource Friendly Name (ex: xCluster becomes cCluster)
    • MOF class name (ex: MSFT_xCluster becomes Contoso_cCluster)
    • Filename for the <resource>.schema.mof (ex: MSFT_xCluster.schema.mof becomes Contoso_cCluster.schema.mof)
  2. Update module and metadata information in the module manifest
  3. Update any configuration that use these resources

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_Cluster" or "Cluster"). If the next version of Windows Server ships with a "Cluster" resource, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

1.0.0.0

  • Initial release with the following resources
    • xCluster, and xWaitForCluster
1.1.0.0

Example: Cluster Example

In this example, we will create a failover cluster from two VMs.  For this example, we assume that a Domain Controller already exists, that both VMs are already domain joined .  Furthermore, it assumes that you certificates installed such that DSC can appropriately handle secrets such as the Domain Administrator Credential.  Finally, the xCluster module must also be installed on the VMs, as specified above.  For an example of an end to end scenario, check out the SQL HA Group blog post on the PowerShell Team Blog.
PowerShell
Edit|Remove
Configuration ClusterDemo 
{ 
    param([Parameter(Mandatory=$true)]  
          [ValidateNotNullorEmpty()]  
          [PsCredential] $domainAdminCred) 
 
    Node $AllNodes.Where{$_.Role -eq "PrimaryClusterNode" }.NodeName 
    { 
        WindowsFeature FailoverFeature 
        { 
            Ensure = "Present" 
            Name      = "Failover-clustering" 
        } 
 
        WindowsFeature RSATClusteringPowerShell 
        { 
            Ensure = "Present" 
            Name   = "RSAT-Clustering-PowerShell"    
 
            DependsOn = "[WindowsFeature]FailoverFeature" 
        } 
 
        WindowsFeature RSATClusteringCmdInterface 
        { 
            Ensure = "Present" 
            Name   = "RSAT-Clustering-CmdInterface" 
 
            DependsOn = "[WindowsFeature]RSATClusteringPowerShell" 
        } 
         
        xCluster ensureCreated 
        { 
            Name = $Node.ClusterName 
            StaticIPAddress = $Node.ClusterIPAddress 
            DomainAdministratorCredential = $domainAdminCred 
 
           DependsOn = “[WindowsFeature]RSATClusteringCmdInterface” 
       }  
         
    } 
 
    Node $AllNodes.Where{ $_.Role -eq "ReplicaServerNode" }.NodeName 
    {          
        WindowsFeature FailoverFeature 
        { 
            Ensure = "Present" 
            Name      = "Failover-clustering" 
        } 
 
        WindowsFeature RSATClusteringPowerShell 
        { 
            Ensure = "Present" 
            Name   = "RSAT-Clustering-PowerShell"    
 
            DependsOn = "[WindowsFeature]FailoverFeature" 
        } 
 
        WindowsFeature RSATClusteringCmdInterface 
        { 
            Ensure = "Present" 
            Name   = "RSAT-Clustering-CmdInterface" 
 
            DependsOn = "[WindowsFeature]RSATClusteringPowerShell" 
        } 
 
        xWaitForCluster waitForCluster 
        { 
            Name = $Node.ClusterName 
            RetryIntervalSec = 10 
            RetryCount = 60 
 
            DependsOn = “[WindowsFeature]RSATClusteringCmdInterface”  
        } 
 
        xCluster joinCluster 
        { 
            Name = $Node.ClusterName 
            StaticIPAddress = $Node.ClusterIPAddress 
            DomainAdministratorCredential = $domainAdminCred 
 
            DependsOn = "[xWaitForCluster]waitForCluster" 
        }   
         
    } 
} 
 
 
$ConfigData = @{ 
    AllNodes = @( 
 
        @{ 
            NodeName= "*" 
 
            CertificateFile = "C:\keys\Dscdemo.cer"                 # use your own certificate 
            Thumbprint = "E513EEFCB763E6954C52BA66A1A81231BF3F551E" # assume both machines have the same certificate to hold private key 
                                                                    # replace the value of thumbprint with your own. 
            
            ClusterName = "Cluster" 
            ClusterIPAddress = "192.168.100.20/24"    # replace the ipaddress of your own. 
        }, 
 
         # Node01 
        @{ 
            NodeName= "Node01"   # rename to actual machine name of VM 
            Role = "PrimaryClusterNode" 
         }, 
 
         # Node02 
         @{ 
            NodeName= "Node02"   # rename to actual machine name of VM 
            Role = "ReplicaServerNode" 
         } 
    ); 
} 
 
$domainAdminCred = Get-Credential -UserName "ClusterDemo\Administrator" -Message "Enter password for private domain Administrator" 
 
ClusterDemo -ConfigurationData $ConfigData -domainAdminCred $domainAdminCred