FailoverClusterDsc

2.1.0-preview0001

DSCResources/DSC_Cluster/en-US/about_Cluster.help.txt

.NAME
    Cluster
 
.DESCRIPTION
    Used to configure a failover cluster. Ensures that a group of machines form a
    cluster. If the cluster does not exist, it will be created in the domain and
    the static IP address will be assigned to the cluster. When the cluster exist
    (either it was created or already existed), it will add the target node
    ($env:COMPUTERNAME) to the cluster.
 
    ## Requirements
 
    * Target machine must be running Windows Server 2008 R2 or later.
 
.PARAMETER Name
    Key - String
    Name of the failover cluster.
 
.PARAMETER StaticIPAddress
    Write - String
    The static IP address of the failover cluster. If this is not specified then the IP address will be assigned from a DHCP.
 
.PARAMETER DomainAdministratorCredential
    Write - Instance
    Credential used to create the failover cluster in Active Directory. If this is not specified then the cluster computer object must have been prestaged as per the https://docs.microsoft.com/en-us/windows-server/failover-clustering/prestage-cluster-adds. If PsDscRunAsCredential is used, then that account must have been granted Full Control over the Cluster Name Object in Active Directory. Otherwise the Computer Account must have been granted Full Control over the Cluster Name Object in Active Directory.
 
.PARAMETER IgnoreNetwork
    Write - StringArray
    One or more networks to ignore when creating the cluster. Only networks using Static IP can be ignored, networks that are assigned an IP address through DHCP cannot be ignored, and are added for cluster communication. To remove networks assigned an IP address through DHCP use the resource ClusterNetwork to change the role of the network. This parameter is only used during the creation of the cluster and is not monitored after.
 
.PARAMETER KeepDownedNodesInCluster
    Write - Boolean
    Switch controlling whether or not to evict cluster nodes in a down state from the cluster. Default value is $false.
 
.EXAMPLE 1
 
This example shows how to create the failover cluster on the first node.
 
Configuration Cluster_CreateFirstNodeOfAFailoverClusterConfig
{
    param(
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node localhost
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        Cluster CreateCluster
        {
            Name = 'Cluster01'
            StaticIPAddress = '192.168.100.20/24'
 
            <#
                This user must have the permission to create the CNO (Cluster Name Object) in Active Directory,
                unless it is prestaged.
            #>
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
 
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
    }
}
 
.EXAMPLE 2
 
This example shows how to add an additional node to the failover cluster.
 
Configuration Cluster_JoinAdditionalNodeToFailoverClusterConfig
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node localhost
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        WaitForCluster WaitForCluster
        {
            Name = 'Cluster01'
            RetryIntervalSec = 10
            RetryCount = 60
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
 
        Cluster JoinSecondNodeToCluster
        {
            Name = 'Cluster01'
            StaticIPAddress = '192.168.100.20/24'
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
            DependsOn = '[WaitForCluster]WaitForCluster'
        }
    }
}
 
.EXAMPLE 3
 
In this example, we will create a failover cluster with two servers.
 
.NOTES
Assumptions:
- We will assume that a Domain Controller already exists, and that both
servers are already domain joined.
- Both servers are using the same certificate, and that the certificate
are installed on both servers so that LCM (Local Configuration Manager)
can appropriately handle secrets such as the Active Directory
administrator credential.
- The example also assumes that the CNO (Cluster Name Object) is either
prestaged or that the Active Directory administrator credential has the
appropriate permission to create the CNO (Cluster Name Object).
 
$ConfigurationData = @{
    AllNodes = @(
        @{
            NodeName = '*'
 
            <#
                Replace with the correct path to your own public certificate part of the same certificate
                that are installed on the target nodes.
 
                NOTE! Please remove comment from this row to be able to use your certificate. This is commented
                so that AppVeyor automatic tests can pass, otherwise it will fail on missing certificate.
            #>
            #CertificateFile = 'C:\Certificates\DscDemo.cer'
 
            <#
                NOTE! THIS IS NOT RECOMMENDED IN PRODUCTION.
                This is added so that AppVeyor automatic tests can pass, otherwise the tests will fail on
                passwords being in plain text and not being encrypted. Because there is not possible to have
                a certificate in AppVeyor to encrypt the passwords we need to add parameter
                'PSDscAllowPlainTextPassword'.
                NOTE! THIS IS NOT RECOMMENDED IN PRODUCTION.
            #>
            PSDscAllowPlainTextPassword = $true
 
            <#
                Replace with the thumbprint of certificate that are installed on both the target nodes.
                This must be the private certificate of the same public certificate used in the previous
                parameter CertificateFile.
                For this example it is assumed that both machines have the same certificate installed.
            #>
            Thumbprint = "E513EEFCB763E6954C52BA66A1A81231BF3F551E"
 
            <#
                Replace with your own CNO (Cluster Name Object) and IP address.
 
                Please note that if the CNO is prestaged, then the computer object must be disabled for the
                resource Cluster to be able to create the cluster.
                If the CNO is not prestaged, then the credential used in the Cluster resource must have
                the permission in Active Directory to create the CNO (Cluster Name Object).
            #>
            ClusterName = 'Cluster01'
            ClusterIPAddress = '192.168.100.20/24'
        },
 
        # Node01 - First cluster node.
        @{
            # Replace with the name of the actual target node.
            NodeName = 'Node01'
 
            # This is used in the configuration to know which resource to compile.
            Role = 'FirstServerNode'
        },
 
        # Node02 - Second cluster node
        @{
            # Replace with the name of the actual target node.
            NodeName = 'Node02'
 
            # This is used in the configuration to know which resource to compile.
            Role = 'AdditionalServerNode'
        }
    )
}
 
Configuration Cluster_CreateFailoverClusterWithTwoNodesConfig
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node $AllNodes.Where{$_.Role -eq 'FirstServerNode' }.NodeName
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        Cluster CreateCluster
        {
            Name = $Node.ClusterName
            StaticIPAddress = $Node.ClusterIPAddress
            # This user must have the permission to create the CNO (Cluster Name Object) in Active Directory, unless it is prestaged.
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
    }
 
    Node $AllNodes.Where{ $_.Role -eq 'AdditionalServerNode' }.NodeName
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        WaitForCluster WaitForCluster
        {
            Name = $Node.ClusterName
            RetryIntervalSec = 10
            RetryCount = 60
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
 
        Cluster JoinSecondNodeToCluster
        {
            Name = $Node.ClusterName
            StaticIPAddress = $Node.ClusterIPAddress
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
            DependsOn = '[WaitForCluster]WaitForCluster'
        }
    }
}
 
.EXAMPLE 4
 
This example shows how to create the a failover cluster on the first node
and ignoring a network.
 
Configuration Cluster_CreateFailoverClusterAndIgnoreANetworkConfig
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node localhost
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        Cluster CreateCluster
        {
            Name = 'Cluster01'
            StaticIPAddress = '192.168.100.20/24'
            IgnoreNetwork = @('10.0.2.0/24')
 
            <#
                This user must have the permission to create the CNO (Cluster Name Object) in Active Directory,
                unless it is prestaged.
            #>
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
 
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
    }
}
 
.EXAMPLE 5
 
This example shows how to create the failover cluster on the first node
using DHCP to assign the IP address to the cluster.
 
Configuration Cluster_CreateFirstNodeOfAFailoverClusterWithDHCPConfig
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node localhost
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        Cluster CreateCluster
        {
            Name = 'Cluster01'
 
            <#
                This user must have the permission to create the CNO (Cluster Name Object) in Active Directory,
                unless it is prestaged.
            #>
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
 
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
    }
}
 
.EXAMPLE 6
 
This example shows how to add an additional node to the failover cluster
when the cluster was assigned an IP address from a DHCP.
 
Configuration Cluster_JoinAdditionalNodeToFailoverClusterWithDHCPConfig
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node localhost
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        WaitForCluster WaitForCluster
        {
            Name = 'Cluster01'
            RetryIntervalSec = 10
            RetryCount = 60
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
 
        Cluster JoinSecondNodeToCluster
        {
            Name = 'Cluster01'
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
            DependsOn = '[WaitForCluster]WaitForCluster'
        }
    }
}
 
.EXAMPLE 7
 
This example shows how to add an additional node to the failover cluster without evicting cluster nodes in a down state.
 
Configuration Cluster_JoinAdditionalNodeToFailoverClusterConfigAndDontEvictDownedNodes
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ActiveDirectoryAdministratorCredential
    )
 
    Import-DscResource -ModuleName FailoverClusterDsc
 
    Node localhost
    {
        WindowsFeature AddFailoverFeature
        {
            Ensure = 'Present'
            Name = 'Failover-clustering'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringPowerShellFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-PowerShell'
            DependsOn = '[WindowsFeature]AddFailoverFeature'
        }
 
        WindowsFeature AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature
        {
            Ensure = 'Present'
            Name = 'RSAT-Clustering-CmdInterface'
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringPowerShellFeature'
        }
 
        WaitForCluster WaitForCluster
        {
            Name = 'Cluster01'
            RetryIntervalSec = 10
            RetryCount = 60
            DependsOn = '[WindowsFeature]AddRemoteServerAdministrationToolsClusteringCmdInterfaceFeature'
        }
 
        Cluster JoinSecondNodeToCluster
        {
            Name = 'Cluster01'
            StaticIPAddress = '192.168.100.20/24'
            DomainAdministratorCredential = $ActiveDirectoryAdministratorCredential
            KeepDownedNodesInCluster = $True
            DependsOn = '[WaitForCluster]WaitForCluster'
        }
    }
}