ADDomainController: Added InstallDns to promote without installing DNS

CHANGELOG.md

@@ -62,6 +62,9 @@
     the domain was found, or `$false` if it was not.
 - Changes to ADUser
   - Remove unused non-mandatory parameters from the Get-TargetResource ([issue #293](https://github.com/PowerShell/ActiveDirectoryDsc/issues/293)).
+- Changes to ADDomainController
+  - Add InstallDns parameter to enable promotion without installing local
+    DNS Server Service ([issue #87](https://github.com/PowerShell/xActiveDirectory/issues/87)).
 
 ## 4.0.0.0
 

DSCResources/MSFT_ADDomainController/MSFT_ADDomainController.psm1

@@ -32,6 +32,14 @@ $script:localizedData = Get-LocalizedData -ResourceName 'MSFT_ADDomainController
 
     .PARAMETER SiteName
         Provide the name of the site you want the Domain Controller to be added to.
+
+    .PARAMETER InstallDns
+        Specifies if the DNS Server service should be installed and configured on
+        the domain controller. If this is not set the default value of the parameter
+        InstallDns of the cmdlet Install-ADDSDomainController is used.
+        The parameter `InstallDns` is only used during the provisioning of a domain
+        controller. The parameter cannot be used to install or uninstall the DNS
+        server on an already provisioned domain controller.
 #>
 function Get-TargetResource
 {
@@ -65,7 +73,11 @@ function Get-TargetResource
 
         [Parameter()]
         [System.String]
-        $SiteName
+        $SiteName,
+
+        [Parameter()]
+        [System.Boolean]
+        $InstallDns
     )
 
     Assert-Module -ModuleName 'ActiveDirectory'
@@ -80,6 +92,7 @@ function Get-TargetResource
         AllowPasswordReplicationAccountName = $null
         DenyPasswordReplicationAccountName  = $null
         FlexibleSingleMasterOperationRole   = $null
+        InstallDns                          = $InstallDNs
     }
 
     Write-Verbose -Message (
@@ -187,6 +200,14 @@ function Get-TargetResource
         Specifies one or more Flexible Single Master Operation (FSMO) roles to
         move to this domain controller. The current owner must be online and
         responding for the move to be allowed.
+
+    .PARAMETER InstallDns
+        Specifies if the DNS Server service should be installed and configured on
+        the domain controller. If this is not set the default value of the parameter
+        InstallDns of the cmdlet Install-ADDSDomainController is used.
+        The parameter `InstallDns` is only used during the provisioning of a domain
+        controller. The parameter cannot be used to install or uninstall the DNS
+        server on an already provisioned domain controller.
 #>
 function Set-TargetResource
 {
@@ -257,7 +278,11 @@ function Set-TargetResource
         [Parameter()]
         [ValidateSet('DomainNamingMaster', 'SchemaMaster', 'InfrastructureMaster', 'PDCEmulator', 'RIDMaster')]
         [System.String[]]
-        $FlexibleSingleMasterOperationRole
+        $FlexibleSingleMasterOperationRole,
+
+        [Parameter()]
+        [System.Boolean]
+        $InstallDns
     )
 
     $getTargetResourceParameters = @{} + $PSBoundParameters
@@ -329,6 +354,11 @@ function Set-TargetResource
             $installADDSDomainControllerParameters.Add('NoGlobalCatalog', $true)
         }
 
+        if ($PSBoundParameters.ContainsKey('InstallDns'))
+        {
+            $installADDSDomainControllerParameters.Add('InstallDns', $InstallDns)
+        }
+
         if (-not [System.String]::IsNullOrWhiteSpace($InstallationMediaPath))
         {
             $installADDSDomainControllerParameters.Add('InstallationMediaPath', $InstallationMediaPath)
@@ -577,6 +607,16 @@ function Set-TargetResource
         Specifies one or more Flexible Single Master Operation (FSMO) roles to
         move to this domain controller. The current owner must be online and
         responding for the move to be allowed.
+
+    .PARAMETER InstallDns
+        Specifies if the DNS Server service should be installed and configured on
+        the domain controller. If this is not set the default value of the parameter
+        InstallDns of the cmdlet Install-ADDSDomainController is used.
+        The parameter `InstallDns` is only used during the provisioning of a domain
+        controller. The parameter cannot be used to install or uninstall the DNS
+        server on an already provisioned domain controller.
+
+        Not used in Test-TargetResource.
 #>
 function Test-TargetResource
 {
@@ -637,7 +677,11 @@ function Test-TargetResource
         [Parameter()]
         [ValidateSet('DomainNamingMaster', 'SchemaMaster', 'InfrastructureMaster', 'PDCEmulator', 'RIDMaster')]
         [System.String[]]
-        $FlexibleSingleMasterOperationRole
+        $FlexibleSingleMasterOperationRole,
+
+        [Parameter()]
+        [System.Boolean]
+        $InstallDns
     )
 
     Write-Verbose -Message (

DSCResources/MSFT_ADDomainController/MSFT_ADDomainController.schema.mof

@@ -15,4 +15,5 @@ class MSFT_ADDomainController : OMI_BaseResource
     [Write, Description("Specifies an array of names of user accounts, group accounts, and computer accounts whose passwords can be replicated to this Read-Only Domain Controller (RODC).")] String AllowPasswordReplicationAccountName[];
     [Write, Description("Specifies the names of user accounts, group accounts, and computer accounts whose passwords are not to be replicated to this Read-Only Domain Controller (RODC).")] String DenyPasswordReplicationAccountName[];
     [Write, Description("Specifies one or more Flexible Single Master Operation (FSMO) roles to move to this domain controller. The current owner must be online and responding for the move to be allowed."), ValueMap{"DomainNamingMaster", "SchemaMaster", "InfrastructureMaster", "PDCEmulator", "RIDMaster"}, Values{"DomainNamingMaster", "SchemaMaster", "InfrastructureMaster", "PDCEmulator", "RIDMaster"}] String FlexibleSingleMasterOperationRole[];
+    [Write, Description("Specifies if the DNS Server service should be installed and configured on the Domain Controller. If this is not set the default value of the parameter `InstallDns` of the cmdlet Install-ADDSDomainController is used. This parameter is only used during the provisioning of a domain controller. The parameter cannot be used to install or uninstall the DNS server on an already provisioned domain controller.")] Boolean InstallDns;
 };

DSCResources/MSFT_ADDomainController/README.md

@@ -4,6 +4,15 @@ The ADDomainController DSC resource will install and configure domain
 controllers in Active Directory. Installation of Read-Only Domain Controllers
 (RODC) is also supported.
 
+Promotion of a Domain Controller using an existing DNS is available using
+the `InstallDns` parameter. The parameter specifies if the DNS Server service
+should be installed and configured on the domain controller. If this is
+not set the default value of the parameter `InstallDns` of the cmdlet
+[`Install-ADDSDomainController`](https://docs.microsoft.com/en-us/powershell/module/addsdeployment/install-addsdomaincontroller)
+is used. The parameter `InstallDns` is only used during the provisioning
+of a domain controller. The parameter cannot be used to install or uninstall
+the DNS server on an already provisioned domain controller.
+
 >**Note:** If the account used for the parameter `Credential`
 >cannot connect to another domain controller, for example using a credential
 >without the domain name, then the cmdlet `Install-ADDSDomainController` will

DSCResources/MSFT_ADDomainController/en-US/about_ADDomainController.help.txt

@@ -6,6 +6,15 @@
     controllers in Active Directory. Installation of Read-Only Domain Controllers
     (RODC) is also supported.
 
+    Promotion of a Domain Controller using an existing DNS is available using
+    the `InstallDns` parameter. The parameter specifies if the DNS Server service
+    should be installed and configured on the domain controller. If this is
+    not set the default value of the parameter `InstallDns` of the cmdlet
+    [`Install-ADDSDomainController`](https://docs.microsoft.com/en-us/powershell/module/addsdeployment/install-addsdomaincontroller)
+    is used. The parameter `InstallDns` is only used during the provisioning
+    of a domain controller. The parameter cannot be used to install or uninstall
+    the DNS server on an already provisioned domain controller.
+
     >**Note:** If the account used for the parameter `Credential`
     >cannot connect to another domain controller, for example using a credential
     >without the domain name, then the cmdlet `Install-ADDSDomainController` will
@@ -84,6 +93,10 @@
     Allowed values: DomainNamingMaster,  SchemaMaster,  InfrastructureMaster,  PDCEmulator,  RIDMaster
     Specifies one or more Flexible Single Master Operation (FSMO) roles to move to this domain controller. The current owner must be online and responding for the move to be allowed.
 
+.PARAMETER InstallDns
+    Write - Boolean
+    Specifies if the DNS Server service should be installed and configured on the Domain Controller. If this is not set the default value of the parameter `InstallDns` of the cmdlet Install-ADDSDomainController is used. This parameter is only used during the provisioning of a domain controller. The parameter cannot be used to install or uninstall the DNS server on an already provisioned domain controller.
+
 .EXAMPLE 1
 
 This configuration will add a domain controller to the domain
@@ -387,4 +400,58 @@ Configuration ADDomainController_AddDomainControllerAndMoveRole_Config
     }
 }
 
+.EXAMPLE 6
+
+This configuration will add a domain controller to the domain contoso.com
+without installing the local DNS server service and using the one in the existing domain.
+
+Configuration ADDomainController_AddDomainControllerUsingInstallDns_Config
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $Credential
+    )
+
+    Import-DscResource -ModuleName PSDscResources
+    Import-DscResource -ModuleName ActiveDirectoryDsc
+
+    node localhost
+    {
+        WindowsFeature 'InstallADDomainServicesFeature'
+        {
+            Ensure = 'Present'
+            Name   = 'AD-Domain-Services'
+        }
+
+        WindowsFeature 'RSATADPowerShell'
+        {
+            Ensure    = 'Present'
+            Name      = 'RSAT-AD-PowerShell'
+
+            DependsOn = '[WindowsFeature]InstallADDomainServicesFeature'
+        }
+
+        WaitForADDomain 'WaitForestAvailability'
+        {
+            DomainName       = 'contoso.com'
+            Credential       = $Credential
+
+            DependsOn        = '[WindowsFeature]RSATADPowerShell'
+        }
+
+        ADDomainController 'DomainControllerUsingExistingDNSServer'
+        {
+            DomainName                    = 'contoso.com'
+            Credential                    = $Credential
+            SafeModeAdministratorPassword = $Credential
+            InstallDns                    = $false
+
+            DependsOn                     = '[xWaitForADDomain]WaitForestAvailability'
+        }
+    }
+}
+
 

DSCResources/MSFT_WaitForADDomain/en-US/about_WaitForADDomain.help.txt

@@ -262,10 +262,10 @@ Configuration WaitForADDomain_WaitForDomainControllerIgnoringAuthenticationError
     {
         WaitForADDomain 'contoso.com'
         {
-            DomainName                 = 'contoso.com'
+            DomainName              = 'contoso.com'
             WaitForValidCredentials = $true
 
-            PsDscRunAsCredential       = $Credential
+            PsDscRunAsCredential    = $Credential
         }
     }
 }

Examples/Resources/ADDomainController/6-ADDomainController_AddDomainControllerUsingInstallDns_Config.ps1

@@ -0,0 +1,72 @@
+<#PSScriptInfo
+.VERSION 1.0.0
+.GUID d817a83d-6450-4dff-9b39-9b184572c100
+.AUTHOR Microsoft Corporation
+.COMPANYNAME Microsoft Corporation
+.COPYRIGHT (c) Microsoft Corporation. All rights reserved.
+.TAGS DSCConfiguration
+.LICENSEURI https://github.com/PowerShell/xActiveDirectory/blob/master/LICENSE
+.PROJECTURI https://github.com/PowerShell/xActiveDirectory
+.ICONURI
+.EXTERNALMODULEDEPENDENCIES
+.REQUIREDSCRIPTS
+.EXTERNALSCRIPTDEPENDENCIES
+.RELEASENOTES First version.
+.PRIVATEDATA 2016-Datacenter,2016-Datacenter-Server-Core
+#>
+
+#Requires -module ActiveDirectoryDsc
+
+<#
+    .DESCRIPTION
+    This configuration will add a domain controller to the domain contoso.com
+    without installing the local DNS server service and using the one in the existing domain.
+#>
+Configuration ADDomainController_AddDomainControllerUsingInstallDns_Config
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $Credential
+    )
+
+    Import-DscResource -ModuleName PSDscResources
+    Import-DscResource -ModuleName ActiveDirectoryDsc
+
+    node localhost
+    {
+        WindowsFeature 'InstallADDomainServicesFeature'
+        {
+            Ensure = 'Present'
+            Name   = 'AD-Domain-Services'
+        }
+
+        WindowsFeature 'RSATADPowerShell'
+        {
+            Ensure    = 'Present'
+            Name      = 'RSAT-AD-PowerShell'
+
+            DependsOn = '[WindowsFeature]InstallADDomainServicesFeature'
+        }
+
+        WaitForADDomain 'WaitForestAvailability'
+        {
+            DomainName       = 'contoso.com'
+            Credential       = $Credential
+
+            DependsOn        = '[WindowsFeature]RSATADPowerShell'
+        }
+
+        ADDomainController 'DomainControllerUsingExistingDNSServer'
+        {
+            DomainName                    = 'contoso.com'
+            Credential                    = $Credential
+            SafeModeAdministratorPassword = $Credential
+            InstallDns                    = $false
+
+            DependsOn                     = '[WaitForADDomain]WaitForestAvailability'
+        }
+    }
+}

Examples/Resources/WaitForADDomain/7-WaitForADDomain_WaitForDomainControllerIgnoringAuthenticationErrors_Config.ps1

@@ -39,10 +39,10 @@ Configuration WaitForADDomain_WaitForDomainControllerIgnoringAuthenticationError
     {
         WaitForADDomain 'contoso.com'
         {
-            DomainName             = 'contoso.com'
+            DomainName              = 'contoso.com'
             WaitForValidCredentials = $true
 
-            PsDscRunAsCredential   = $Credential
+            PsDscRunAsCredential    = $Credential
         }
     }
 }