First published on MSDN on Dec 19, 2008

Hi Cluster Fans,

In Windows Server 2008 R2 (“R2”) we are introducing PowerShell as the new scripting language for clustering technologies.  PowerShell with Failover Clustering will replace Cluster.exe and the Windows Server 2008 R2 release will be the deprecation release for Cluster.exe.  This means it will still be available for use so it doesn’t break legacy scripts, but no improvements have been made and Cluster.exe will be completely removed in the next release of Windows Server.  This allows ample time for you to learn (and love) PowerShell.

PowerShell provides numerous benefits over standard command line interfaces, including easily customizable scripts and the dynamic use of variables.  In Windows Server 2008 R2, PowerShell can also be run on Server Core machines.  Using PowerShell on a Core cluster, you can directly run cluster Validation and generate dependency reports, without needing to manage the Core node through a UI-based remote machine.

This blog post will provide an overview of PowerShell with Failover Clustering.  In the next few weeks, a post about PowerShell with Network Load Balancing (NLB) will be added to the site.

How do I get R2 Beta?

There are numerous ways to get the Windows Server 2008 R2 Beta build which includes Failover Clustering (on Enterprise and Datacenter editions).  If you work for an organization which partners with Microsoft, try contacting your Technology Account Manager (TAM) to see if they can provide you with access.  If your organization is enrolled in the Technology Adoption Program (TAP) you may also have access through this channel.  Others may enroll in the Microsoft Connect program ( http://connect.microsoft.com/ ) to receive access to major builds.  The Beta build will be available very shortly for deployment and testing.

We want your feedback!

PowerShell is going to be the cluster scripting language for the future – and you have the opportunity to influence its design and use for the next decade during the Beta feedback period.  Some high-level areas of feedback for the PowerShell commands (cmdlets) which we are looking for include the following:

·         Was it easy to find the cmdlet you wanted?

·         Are the parameters consistent between cmdlets?

·         Is the in-box help and example useful?

·         Has the PowerShell utility met your scripting needs?

·         Was there a cmdlet which did something different than you expected from its name or description?

·         Anything else?

We encourage you to provide feedback through the appropriate channels on the Microsoft Connect site, through your TAM, or TAP Program Manager.  You may also email your feedback to us via the “Email” link in the upper left corner of this page.

Running Failover Clustering with PowerShell

The name of the Failover Clustering module is FailoverClusters .

[Update: 10/5/2009] For the Windows Server 2008 R2 RTM release of the product you may access PowerShell management, launch as an Administrator and load ALL of your PowerShell modules automatically by selecting: Start à Administrator Tools à Windows PowerShell Modules.

Loading PowerShell with Failover Clustering can be done in two ways:

1.       Open Failover Cluster PowerShell Management from the shortcut in Administrative Tools

§  This option will appear after the Failover Clustering feature is installed

2.       Open PowerShell on your machine through right-clicking and selecting Run as administrator

§  Load the module with the command: Import-Module FailoverClusters

Failover Clustering PowerShell Cmdlets

Cmdlets (“command-lets”) form the basis of the PowerShell instruction set.  The design goal was for feature parity between the Failover Cluster Manager GUI and PowerShell, so any operation can be performed on both (with cluster migration being the exception, unavailable with PowerShell).  Other new R2 Failover Clustering features are also supported by PowerShell, including Cluster Shared Volumes (CSV) and Live Migration.  Integration with and manageability of Hyper-V Virtual Machines (VMs) is also important and PowerShell give you the ability to create and manage highly-available VMs, configure CSV volumes, and perform a Quick Migration (Move-ClusterGroup)  or a Live Migration (Move-ClusterVirtualMachineRole).

To get a complete list of the cmdlets, run the following command: Get-Command -Module FailoverClusters

The following is a list of Failover Clustering cmdlets for the Beta release.  Note that these are subject to change.

Name

----

Add-ClusterDisk

Add-ClusterFileServerRole

Add-ClusterGenericApplicationRole

Add-ClusterGenericScriptRole

Add-ClusterGenericServiceRole

Add-ClusterGroup

Add-ClusterNode

Add-ClusterPrintServerRole

Add-ClusterResource

Add-ClusterResourceDependency

Add-ClusterResourceType

Add-ClusterServerRole

Add-ClusterSharedVolume

Add-ClusterVirtualMachineRole

Block-ClusterAccess

Clear-ClusterDiskReservation

Clear-ClusterNode

Fail-ClusterResource

Get-Cluster

Get-ClusterAccess

Get-ClusterAvailableDisk

Get-ClusterGroup

Get-ClusterLog

Get-ClusterNetwork

Get-ClusterNetworkInterface

Get-ClusterNode

Get-ClusterOwnerNode

Get-ClusterParameter

Get-ClusterQuorum

Get-ClusterResource

Get-ClusterResourceDependency

Get-ClusterResourceDependencyReport

Get-ClusterResourceType

Get-ClusterSharedVolume

Grant-ClusterAccess

Move-ClusterGroup

Move-ClusterResource

Move-ClusterSharedVolume

Move-ClusterVirtualMachineRole

New-Cluster

Remove-Cluster

Remove-ClusterAccess

Remove-ClusterGroup

Remove-ClusterNode

Remove-ClusterResource

Remove-ClusterResourceDependency

Remove-ClusterResourceType

Remove-ClusterSharedVolume

Resume-ClusterNode

Resume-ClusterResource

Set-ClusterLog

Set-ClusterOwnerNode

Set-ClusterParameter

Set-ClusterQuorum

Set-ClusterResourceDependency

Start-Cluster

Start-ClusterGroup

Start-ClusterNode

Start-ClusterResource

Stop-Cluster

Stop-ClusterGroup

Stop-ClusterNode

Stop-ClusterResource

Suspend-ClusterNode

Suspend-ClusterResource

Test-Cluster

Update-ClusterIPResource

Update-ClusterVirtualMachineConfiguration

Help Documentation

This all sounds pretty good, right?  But what happens when you cannot figure out what command syntax is needed?  Well PowerShell has all the help documentation built into the PowerShell utility itself and even includes examples.  Please refer to this in-box help when you use PowerShell.  This is also an area where we would like your feedback – please let us know if there is anything which you cannot find or you believe was misleading.

To get full help for a cmdlet: Get-Help <cmdlet_name> -Full

Let’s take a look at the Add-ClusterDisk cmdlet:

PS C:\Users\symonp> Get-Help Add-ClusterDisk -Full

NAME

Add-ClusterDisk

SYNOPSIS

Make a new disk available for use in a failover cluster. The disk (LUN) must be exposed to all nodes in the failover cluster, and should not be exposed to any other servers.

SYNTAX

Add-ClusterDisk [-InputObject] <ClusterDiskInfo[]> [-confirm] [-whatif] [<CommonParameters>]

DETAILED DESCRIPTION

When adding a disk, make sure that the configuration of the storage allows the operating system to recognize and mount the disk as needed. The disk must be a basic disk (not a dynamic disk) and should not be exposed to servers outside the cluster. The cmdlet Get-ClusterAvailableDisk gets information about disks that you can add to the cluster.

PARAMETERS

-InputObject <ClusterDiskInfo[]>

Required?                    true

Position?                    1

Default value

Accept pipeline input?       true (ByValue)

Accept wildcard characters?  false

-Confirm [<SwitchParameter>]

Prompts you for confirmation before executing the command.

Required?                    false

Position?                    named

Default value

Accept pipeline input?       false

Accept wildcard characters?  false

-WhatIf [<SwitchParameter>]

Describes what would happen if you executed the command without actually executing the command.

Required?                    false

Position?                    named

Default value

Accept pipeline input?       false

Accept wildcard characters?  false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug,

-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,

-OutBuffer and -OutVariable. For more information, type,

"get-help about_commonparameters".

INPUT TYPE

Microsoft.FailoverClusters.PowerShell.ClusterDiskInfo

RETURN TYPE

Microsoft.FailoverClusters.PowerShell.ClusterResource

NOTES

-------------------------- EXAMPLE 1 --------------------------

C:\PS>Get-ClusterAvailableDisk | Add-ClusterDisk

Name                State               Group               ResourceType

----                -----               -----               ------------

Cluster Disk 7      OnlinePending       Available Storage   Physical Disk

Cluster Disk 8      OnlinePending       Available Storage   Physical Disk

Description

-----------

This command adds to the cluster all disks that are ready for cluster use but have not been added to the cluster yet.

-------------------------- EXAMPLE 2 --------------------------

C:\PS>Get-ClusterAvailableDisk | ?{ $_.ScsiAddress -eq 50331651 } | Add-ClusterDisk

Name                State               Group               ResourceType

----                -----               -----               ------------

Cluster Disk 4      OnlinePending       Available Storage   Physical Disk

Description

-----------

This command adds to the cluster a disk (with the given SCSI Address) that is ready for cluster use but has not been added to the cluster yet.

RELATED LINKS

Test-Cluster

Get-ClusterAvailableDisk

To get full help for all Failover Clustering cmdlets: Get-Command -Module FailoverClusters | %{ Get-Help $_.Name -Full }

Example

Here’s a sample PowerShell script where I set some variables, create a highly-available File Server, get some information about the cluster and resources, move the File Server, then delete it.

# Set some variables

$Node1 = "symonp-n1" ; $Node2 = "symonp-n2"

$FileServerGroupName = "symonp-fsBlog"

$FileServerDiskResourceName = "Cluster Disk 1"

# Create a highly available file server

Add-ClusterFileServerRole -Storage $FileServerDiskResourceName –Name $FileServerGroupName

# See which resources are in my group

Get-ClusterGroup $FileServerGroupName | Get-ClusterResource

# Get resources on a specific node

Get-ClusterNode $Node1 | Get-ClusterResource

Get-ClusterNode $Node2 | Get-ClusterResource

# Move file server cluster group to this node if it is on another node

Move-ClusterGroup -Group $FileServerGroupName -NodeName $env:computername

# Delete the highly available file server

Remove-ClusterGroup $FileServerGroupName -RemoveResources

Good luck with your PowerShell deployments and please send us your feedback!

Thanks,

Symon Perriman

Program Manager

Clustering & HA