SqlAGListener: Add parameter ProcessOnlyOnActiveNode to make it cluster aware

CHANGELOG.md

@@ -66,6 +66,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
       no SQL module is found. The script-terminating error is caught and made into
       a statement-terminating error.
   - Bump GitHub Action Checkout to v4.
+- SqlAGListener
+  - Made the resource cluster aware. When ProcessOnlyOnActiveNode is specified,
+    the resource will only determine if a change is needed if the target node
+    is the active host of the SQL Server instance ([issue #871](https://github.com/dsccommunity/SqlServerDsc/issues/871)).
 
 ### Remove
 

source/DSCResources/DSC_SqlAGListener/DSC_SqlAGListener.psm1

@@ -24,7 +24,6 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
 #>
 function Get-TargetResource
 {
-    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('SqlServerDsc.AnalyzerRules\Measure-CommandsNeededToLoadSMO', '', Justification='The command Connect-Sql is called when Get-SQLAlwaysOnAvailabilityGroupListener is called')]
     [CmdletBinding()]
     [OutputType([System.Collections.Hashtable])]
     param
@@ -44,7 +43,11 @@ function Get-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.String]
-        $AvailabilityGroup
+        $AvailabilityGroup,
+
+        [Parameter()]
+        [System.Boolean]
+        $ProcessOnlyOnActiveNode
     )
 
     Write-Verbose -Message (
@@ -53,6 +56,11 @@ function Get-TargetResource
 
     try
     {
+        $serverObject = Connect-SQL -ServerName $ServerName -InstanceName $InstanceName
+
+        # Is this node actively hosting the SQL instance?
+        $isActiveNode = Test-ActiveNode -ServerObject $serverObject
+
         $availabilityGroupListener = Get-SQLAlwaysOnAvailabilityGroupListener -Name $Name -AvailabilityGroup $AvailabilityGroup -ServerName $ServerName -InstanceName $InstanceName
 
         if ($null -ne $availabilityGroupListener)
@@ -99,14 +107,16 @@ function Get-TargetResource
     }
 
     return @{
-        InstanceName      = [System.String] $InstanceName
-        ServerName        = [System.String] $ServerName
-        Name              = [System.String] $Name
-        Ensure            = [System.String] $ensure
-        AvailabilityGroup = [System.String] $AvailabilityGroup
-        IpAddress         = [System.String[]] $ipAddress
-        Port              = [System.UInt16] $port
-        DHCP              = [System.Boolean] $dhcp
+        InstanceName            = [System.String] $InstanceName
+        ServerName              = [System.String] $ServerName
+        Name                    = [System.String] $Name
+        Ensure                  = [System.String] $ensure
+        AvailabilityGroup       = [System.String] $AvailabilityGroup
+        IpAddress               = [System.String[]] $ipAddress
+        Port                    = [System.UInt16] $port
+        DHCP                    = [System.Boolean] $dhcp
+        ProcessOnlyOnActiveNode = [System.Boolean] $ProcessOnlyOnActiveNode
+        IsActiveNode            = [System.Boolean] $isActiveNode
     }
 }
 
@@ -137,6 +147,10 @@ function Get-TargetResource
 
     .PARAMETER DHCP
         If DHCP should be used for the availability group listener instead of static IP address.
+
+    .PARAMETER ProcessOnlyOnActiveNode
+        Specifies that the resource will only determine if a change is needed if the target node is the active host of the SQL Server instance.
+        Not used in Set-TargetResource.
 #>
 function Set-TargetResource
 {
@@ -175,7 +189,11 @@ function Set-TargetResource
 
         [Parameter()]
         [System.Boolean]
-        $DHCP
+        $DHCP,
+
+        [Parameter()]
+        [System.Boolean]
+        $ProcessOnlyOnActiveNode
     )
 
     $parameters = @{
@@ -413,10 +431,13 @@ function Set-TargetResource
 
     .PARAMETER DHCP
         If DHCP should be used for the availability group listener instead of static IP address.
+
+    .PARAMETER ProcessOnlyOnActiveNode
+        Specifies that the resource will only determine if a change is needed if the target node is the active host of the SQL Server instance.
 #>
 function Test-TargetResource
 {
-    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('SqlServerDsc.AnalyzerRules\Measure-CommandsNeededToLoadSMO', '', Justification='The command Connect-Sql is called when Get-TargetResource is called')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('SqlServerDsc.AnalyzerRules\Measure-CommandsNeededToLoadSMO', '', Justification = 'The command Connect-Sql is called when Get-TargetResource is called')]
     [CmdletBinding()]
     [OutputType([System.Boolean])]
     param
@@ -453,7 +474,11 @@ function Test-TargetResource
 
         [Parameter()]
         [System.Boolean]
-        $DHCP
+        $DHCP,
+
+        [Parameter()]
+        [System.Boolean]
+        $ProcessOnlyOnActiveNode
     )
 
     $parameters = @{
@@ -471,6 +496,20 @@ function Test-TargetResource
 
     [System.Boolean] $result = $false
 
+    <#
+        If this is supposed to process only the active node, and this is not the
+        active node, don't bother evaluating the test.
+    #>
+    if ($ProcessOnlyOnActiveNode -and -not $availabilityGroupListenerState.IsActiveNode)
+    {
+        # Use localization if the resource has been converted
+        Write-Verbose -Message ('The node ''{0}'' is not actively hosting the instance ''{1}''. Exiting the test.' -f (Get-ComputerName), $InstanceName)
+
+        $result = $true
+
+        return $result
+    }
+
     if ($availabilityGroupListenerState.Ensure -eq $Ensure)
     {
         $result = $true

source/DSCResources/DSC_SqlAGListener/DSC_SqlAGListener.schema.mof

@@ -10,5 +10,6 @@ class DSC_SqlAGListener : OMI_BaseResource
     [Write, Description("The IP address used for the availability group listener, in the format `'192.168.10.45/255.255.252.0'`. If using DHCP, set to the first IP-address of the DHCP subnet, in the format `'192.168.8.1/255.255.252.0'`. Must be valid in the cluster-allowed IP range.")] String IpAddress[];
     [Write, Description("The port used for the availability group listener.")] UInt16 Port;
     [Write, Description("If DHCP should be used for the availability group listener instead of static IP address.")] Boolean DHCP;
+    [Write, Description("Specifies that the resource will only determine if a change is needed if the target node is the active host of the SQL Server instance.")] Boolean ProcessOnlyOnActiveNode;
+    [Read, Description("Determines if the current node is actively hosting the SQL Server instance.")] Boolean IsActiveNode;
 };
-

source/Examples/Resources/SqlAGListener/1-AddAvailabilityGroupListenerWithSameNameAsVCO.ps1

@@ -2,6 +2,11 @@
     .DESCRIPTION
         This example will add an Availability Group listener with the same name
         as the cluster role VCO.
+
+        In the event this is applied to a Failover Cluster Instance (FCI), the
+        ProcessOnlyOnActiveNode property will tell the Test-TargetResource function
+        to evaluate if any changes are needed if the node is actively hosting the
+        SQL Server instance.
 #>
 Configuration Example
 {
@@ -18,15 +23,16 @@ Configuration Example
     {
         SqlAGListener 'AvailabilityGroupListenerWithSameNameAsVCO'
         {
-            Ensure               = 'Present'
-            ServerName           = 'SQLNODE01.company.local'
-            InstanceName         = 'MSSQLSERVER'
-            AvailabilityGroup    = 'AG-01'
-            Name                 = 'AG-01'
-            IpAddress            = '192.168.0.73/255.255.255.0'
-            Port                 = 5301
+            Ensure                  = 'Present'
+            ServerName              = 'SQLNODE01.company.local'
+            InstanceName            = 'MSSQLSERVER'
+            AvailabilityGroup       = 'AG-01'
+            Name                    = 'AG-01'
+            IpAddress               = '192.168.0.73/255.255.255.0'
+            Port                    = 5301
+            ProcessOnlyOnActiveNode = $true
 
-            PsDscRunAsCredential = $SqlAdministratorCredential
+            PsDscRunAsCredential    = $SqlAdministratorCredential
         }
     }
 }

source/Examples/Resources/SqlAGListener/2-AddAvailabilityGroupListenerWithDifferentNameAsVCO.ps1

@@ -2,6 +2,11 @@
     .DESCRIPTION
         This example will add an Availability Group listener with a different
         than the cluster role VCO.
+
+        In the event this is applied to a Failover Cluster Instance (FCI), the
+        ProcessOnlyOnActiveNode property will tell the Test-TargetResource function
+        to evaluate if any changes are needed if the node is actively hosting the
+        SQL Server instance.
 #>
 Configuration Example
 {
@@ -18,15 +23,16 @@ Configuration Example
     {
         SqlAGListener 'AvailabilityGroupListenerWithDifferentNameAsVCO'
         {
-            Ensure               = 'Present'
-            ServerName           = 'SQLNODE01.company.local'
-            InstanceName         = 'MSSQLSERVER'
-            AvailabilityGroup    = 'AvailabilityGroup-01'
-            Name                 = 'AG-01'
-            IpAddress            = '192.168.0.74/255.255.255.0'
-            Port                 = 5302
+            Ensure                  = 'Present'
+            ServerName              = 'SQLNODE01.company.local'
+            InstanceName            = 'MSSQLSERVER'
+            AvailabilityGroup       = 'AvailabilityGroup-01'
+            Name                    = 'AG-01'
+            IpAddress               = '192.168.0.74/255.255.255.0'
+            Port                    = 5302
+            ProcessOnlyOnActiveNode = $true
 
-            PsDscRunAsCredential = $SqlAdministratorCredential
+            PsDscRunAsCredential    = $SqlAdministratorCredential
         }
     }
 }

source/Examples/Resources/SqlAGListener/5-AddAvailabilityGroupListenerUsingDHCPWithDefaultServerSubnet.ps1

@@ -2,6 +2,11 @@
     .DESCRIPTION
         This example will add an Availability Group listener using DHCP on the
         default server subnet.
+
+        In the event this is applied to a Failover Cluster Instance (FCI), the
+        ProcessOnlyOnActiveNode property will tell the Test-TargetResource function
+        to evaluate if any changes are needed if the node is actively hosting the
+        SQL Server instance.
 #>
 Configuration Example
 {
@@ -18,19 +23,20 @@ Configuration Example
     {
         SqlAGListener 'AvailabilityGroupListenerWithSameNameAsVCO'
         {
-            Ensure               = 'Present'
-            ServerName           = 'SQLNODE01.company.local'
-            InstanceName         = 'MSSQLSERVER'
-            AvailabilityGroup    = 'AG-01'
-            Name                 = 'AG-01'
+            Ensure                  = 'Present'
+            ServerName              = 'SQLNODE01.company.local'
+            InstanceName            = 'MSSQLSERVER'
+            AvailabilityGroup       = 'AG-01'
+            Name                    = 'AG-01'
             <#
                 If not specifying parameter DHCP, then the default will be
                 DHCP with the default server subnet.
             #>
-            DHCP                 = $true
-            Port                 = 5301
+            DHCP                    = $true
+            Port                    = 5301
+            ProcessOnlyOnActiveNode = $true
 
-            PsDscRunAsCredential = $SqlAdministratorCredential
+            PsDscRunAsCredential    = $SqlAdministratorCredential
         }
     }
 }

source/Examples/Resources/SqlAGListener/6-AddAvailabilityGroupListenerUsingDHCPWithSpecificSubnet.ps1

@@ -1,6 +1,11 @@
 <#
     .DESCRIPTION
         This example will add an Availability Group listener using DHCP with a specific subnet.
+
+        In the event this is applied to a Failover Cluster Instance (FCI), the
+        ProcessOnlyOnActiveNode property will tell the Test-TargetResource function
+        to evaluate if any changes are needed if the node is actively hosting the
+        SQL Server instance.
 #>
 Configuration Example
 {
@@ -17,16 +22,17 @@ Configuration Example
     {
         SqlAGListener 'AvailabilityGroupListenerWithSameNameAsVCO'
         {
-            Ensure               = 'Present'
-            ServerName           = 'SQLNODE01.company.local'
-            InstanceName         = 'MSSQLSERVER'
-            AvailabilityGroup    = 'AG-01'
-            Name                 = 'AG-01'
-            DHCP                 = $true
-            IpAddress            = '192.168.0.1/255.255.252.0'
-            Port                 = 5301
+            Ensure                  = 'Present'
+            ServerName              = 'SQLNODE01.company.local'
+            InstanceName            = 'MSSQLSERVER'
+            AvailabilityGroup       = 'AG-01'
+            Name                    = 'AG-01'
+            DHCP                    = $true
+            IpAddress               = '192.168.0.1/255.255.252.0'
+            Port                    = 5301
+            ProcessOnlyOnActiveNode = $true
 
-            PsDscRunAsCredential = $SqlAdministratorCredential
+            PsDscRunAsCredential    = $SqlAdministratorCredential
         }
     }
 }