SqlServerDsc: Documentation updates (#1576)

- SqlServerDsc - Remove the file `.github/CONTRIBUTION.md` as it no longer filled any purpose as GitHub will find the CONTRIBUTION.md in the root folder directly now (issue #1227). - The documentation in CONTRIBUTING.md has been somewhat updated. - Update documentation around design pattern for accounts that does not use passwords (issue #378) and (issue #1230). - Updating the Integration Test README.md to better explain what the integration tests for SqlSetup, SqlRSSetup, and SqlRS does (issue #1315). - SqlAGReplica - Update documentation with a requirement for SqlServer in certain circumstances (issue #1033). - SqlRSSetup - There was a typo in the error message that was thrown when not passing either the `Edition` or `ProductKey` that could be misleading (issue #1386). - Updated the parameter descriptions for the parameters `Edition` and `ProductKey` that they are mutually exclusive (issue #1386).
dsccommunity · Jul 1, 2020 · 1833285 · 1833285
1 parent 83a8e4a
commit 1833285
Show file tree

Hide file tree

Showing 8 changed files with 152 additions and 55 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,12 +5,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- SqlServerDsc
+ - Remove the file `.github/CONTRIBUTION.md` as it no longer filled any
+ purpose as GitHub will find the CONTRIBUTION.md in the root folder
+ directly now ([issue #1227](https://github.com/dsccommunity/SqlServerDsc/issues/1227)).
+
 ### Fixed
 
 - SqlServerDsc
  - Update resource parameter documentation ([issue #1568](https://github.com/dsccommunity/SqlServerDsc/issues/1568)).
  - Documentation is now published to the GitHub Wiki.
  - Deploy task was updated with the correct name.
+ - The documentation in CONTRIBUTING.md has been somewhat updated.
+ - Update documentation around design pattern for accounts that does not
+ use passwords ([issue #378](https://github.com/dsccommunity/SqlServerDsc/issues/378))
+ and ([issue #1230](https://github.com/dsccommunity/SqlServerDsc/issues/1230)).
+ - Updating the Integration Test README.md to better explain what the
+ integration tests for SqlSetup, SqlRSSetup, and SqlRS does ([issue #1315](https://github.com/dsccommunity/SqlServerDsc/issues/1315)).
 - SqlServerDsc.Common
  - Connect-UncPath
  - Now support to authenticate using both NetBIOS domain and Fully Qualified
@@ -21,6 +34,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  - Connect-SQLAnalysis
  - Now support to authenticate using both NetBIOS domain and Fully Qualified
  Domain Name (FQDN) ([issue #1223](https://github.com/dsccommunity/SqlServerDsc/issues/1223)).
+- SqlAGReplica
+ - Update documentation with a requirement for SqlServer in certain circumstances
+ ([issue #1033](https://github.com/dsccommunity/SqlServerDsc/issues/1033)).
+- SqlRSSetup
+ - There was a typo in the error message that was thrown when not passing
+ either the `Edition` or `ProductKey` that could be misleading ([issue #1386](https://github.com/dsccommunity/SqlServerDsc/issues/1386)).
+ - Updated the parameter descriptions for the parameters `Edition` and
+ `ProductKey` that they are mutually exclusive ([issue #1386](https://github.com/dsccommunity/SqlServerDsc/issues/1386)).
 - SqlWindowsFirewall
  - Now support to authenticate using both NetBIOS domain and Fully Qualified
  Domain Name (FQDN) ([issue #1223](https://github.com/dsccommunity/SqlServerDsc/issues/1223)).

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,13 +8,14 @@ to use, and we would love to have contributions from the community.
 
 Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).
 
-## Running the Tests
+## Documentation with Markdown
 
-If want to know how to run this module's tests you can look at the [Testing Guidelines](https://dsccommunity.org/guidelines/testing-guidelines/#running-tests)
-
-## Specific guidelines for SqlServerDsc
+If using Visual Studio Code to edit Markdown files it can be a good idea
+to install the markdownlint extension. It will help to do style checking.
+The file [.markdownlint.json](/.markdownlint.json) is prepared with a default
+set of rules which will automatically be used by the extension.
 
-### Automatic formatting with VS Code
+## Automatic formatting with VS Code
 
 There is a VS Code workspace settings file within this project with formatting
 settings matching the style guideline. That will make it possible inside VS Code
@@ -34,6 +35,22 @@ supported versions.
 Those SQL Server products that are still supported can be listed at the
 [Microsoft life cycle site](https://support.microsoft.com/en-us/lifecycle/search?alpha=SQL%20Server).
 
+## Design patterns
+
+### Credentials that does not have password
+
+Credential that needs to be passed to a DSC resource might include Manged
+Service Account (MSA), Group Managed Service Account (gMSA), and built-in
+accounts (e.g. 'NT AUTHORITY\NetworkService').
+
+For a resource to support these types of accounts (credentials) the DSC
+resource need to ignore the password part of the credential object when
+it is passed to the DSC resource. We should not add separate parameters
+for passing such account names.
+
+_This was discussed in [issue #738](https://github.com/dsccommunity/SqlServerDsc/issues/738)_
+_and [issue #1230](https://github.com/dsccommunity/SqlServerDsc/issues/1230)_.
+
 ### Naming convention
 
 The DSC resources contained in SqlServerDsc use the following naming convention:
@@ -99,33 +116,37 @@ naming structure using the following components.
 - **Feature**: Endpoint
 - **Property**: Permission
 
-#### mof-based resource
+### mof-based resource
 
-All mof-based resource (with Get/Set/Test-TargetResource) should be prefixed with
-'DSC\_Sql'. I.e. DSC\_SqlDatabase
+A mof-based resource is a resource tha has the functions Get-, Set-, and
+Test-TargetResource in a PowerShell module script file (.psm1) and a
+schema.mof that describes the properties of the resource.
 
-Please note that not all places should contain the prefix 'DSC\_'.
-
-##### Folder and file structure
+#### Folder and file structure
 
 Please note that for the examples folder we don't use the 'DSC\_' prefix on the
 resource folders.
 This is to make those folders more user friendly, to resemble the name the user
 would use in the configuration file.
 
 ```Text
-DSCResources/DSC_SqlConfiguration/DSC_SqlConfiguration.psm1
-DSCResources/DSC_SqlConfiguration/DSC_SqlConfiguration.schema.mof
-DSCResources/DSC_SqlConfiguration/en-US/DSC_SqlConfiguration.strings.psd1
+source/DSCResources/DSC_SqlConfiguration/DSC_SqlConfiguration.psm1
+source/DSCResources/DSC_SqlConfiguration/DSC_SqlConfiguration.schema.mof
+source/DSCResources/DSC_SqlConfiguration/en-US/DSC_SqlConfiguration.strings.psd1
+source/DSCResources/DSC_SqlConfiguration/README.md
+
+source/Examples/Resources/SqlConfiguration/1-AddConfigurationOption.ps1
+source/Examples/Resources/SqlConfiguration/2-RemoveConfigurationOption.ps1
 
-Tests/Unit/DSC_SqlConfiguration.Tests.ps1
+tests/Unit/DSC_SqlConfiguration.Tests.ps1
 
-Examples/Resources/SqlConfiguration/1-AddConfigurationOption.ps1
-Examples/Resources/SqlConfiguration/2-RemoveConfigurationOption.ps1
+tests/Integration/DSC_SqlConfiguration.config.ps1
+tests/Integration/DSC_SqlConfiguration.Integration.Tests.ps1
 ```
 
 ##### Schema mof file
 
+The class name should be prefixed with 'DSC\_Sql', e.g. _DSC_SqlConfiguration_.
 Please note that the `FriendlyName` in the schema mof file should not contain the
 prefix `DSC\_`.
 
@@ -137,7 +158,7 @@ class DSC_SqlConfiguration : OMI_BaseResource
 };
 ```
 
-#### Composite or class-based resource
+### Composite or class-based resource
 
 Any composite (with a Configuration) or class-based resources should be prefixed
 with just 'Sql'
@@ -146,42 +167,36 @@ with just 'Sql'
 
 In each resource folder there should be, at least, a localization folder for
 english language 'en-US'.
-In the 'en-US' (and any other language folder) there should be a file named
-'DSC_ResourceName.strings.psd1', i.e.
-'DSC_SqlSetup.strings.psd1'.
-At the top of each resource the localized strings should be loaded, see the helper
-function `Get-LocalizedData` for more information on how this is done.
-
-The localized string file should contain the following (beside the localization
-strings)
 
-```powershell
-# Localized resources for SqlSetup
-
-ConvertFrom-StringData @'
- InstallingUsingPathMessage = Installing using path '{0}'.
-'@
-```
+Read more about this in the [localization style guideline](https://dsccommunity.org/styleguidelines/localization/).
 
 ### Helper functions
 
-Helper functions or wrapper functions that are used only by the resource can preferably
-be placed in the resource module file. If the functions are of a type that could
-be used by more than
-one resource, then the functions can also be placed in the common module
-[SqlServerDsc.Common](https://github.com/dsccommunity/SqlServerDsc/blob/master/source/Modules/SqlServerDsc.Common)
+Helper functions or wrapper functions that are used only by the resource can
+preferably be placed in the resource module file. If the functions are of a
+type that could be used by more than one resource, then the functions can also
+be placed in the common module [SqlServerDsc.Common](https://github.com/dsccommunity/SqlServerDsc/blob/master/source/Modules/SqlServerDsc.Common)
 module file.
 
+If a helper function can be used by more than one DSC module it is preferably
+that the helper function is added to the PowerShell module [DscResource.Common](https://github.com/dsccommunity/DscResource.Common).
+Once the helper function is in a full release (not preview) then it can be
+automatically be used by DSC resources in this module. This is because the
+_DscResource.Common_ module is incorporating during the build phase.
+
 ### Unit tests
 
 For a review of a Pull Request (PR) to start, all tests must pass without error.
 If you need help to figure why some test don't pass, just write a comment in the
 Pull Request (PR), or submit an issue, and somebody will come along and assist.
 
-#### Unit tests for examples files
+If want to know how to run this module's tests you can look at the [Testing Guidelines](https://dsccommunity.org/guidelines/testing-guidelines/#running-tests)
 
-When sending in a Pull Request (PR) all example files will be tested so they can
-be compiled to a .mof file. If the tests find any errors the build will fail.
+#### Using SMO stub classes
+
+There are [stub classes](https://github.com/PowerShell/SqlServerDsc/blob/master/Tests/Unit/Stubs/SMO.cs)
+for the SMO classes which can be used and improved on when creating tests where
+SMO classes are used in the code being tested.
 
 ### Integration tests
 
@@ -190,17 +205,19 @@ the CI.
 
 There are also configuration made by existing integration tests that can be reused
 to write integration tests for other resources. This is documented in
-[Integration tests for SqlServerDsc](https://github.com/PowerShell/SqlServerDsc/blob/dev/Tests/Integration/README.md).
+[Integration tests for SqlServerDsc](https://github.com/PowerShell/SqlServerDsc/blob/master/Tests/Integration/README.md).
 
-#### Using SMO stub classes
+Since integration tests must run in order because they are dependent on each
+other to some degree. Most resource are dependent on that integration tests
+for the DSC resource _SqlSetup_ have installed the instance to connect to.
+To make sure a integration tests is run in the correct order the integration
+tests are grouped in the file `azure-pipelines.yml` in the integration tests
+jobs.
 
-There are [stub classes](https://github.com/PowerShell/SqlServerDsc/blob/dev/Tests/Unit/Stubs/SMO.cs)
-for the SMO classes which can be used and improved on when creating tests where
-SMO classes are used in the code being tested.
+There are two integration tests jobs that each test SQL Server 2016 and
+SQL Server 2017.
 
-### Documentation with Markdown
+### Testing of examples files
 
-If using Visual Studio Code to edit Markdown files it can be a good idea to install
-the markdownlint extension. It will help to do style checking.
-The file [.markdownlint.json](/.markdownlint.json) is prepared with a default set
-of rules which will automatically be used by the extension.
+When sending in a Pull Request (PR) all example files will be tested so they can
+be compiled to a .mof file. If the tests find any errors the build will fail.
diff --git a/source/DSCResources/DSC_SqlAGReplica/README.md b/source/DSCResources/DSC_SqlAGReplica/README.md
@@ -9,6 +9,13 @@ Always On Availability Group Replica.
 * Target machine must be running SQL Server Database Engine 2012 or later.
 * 'NT SERVICE\ClusSvc' or 'NT AUTHORITY\SYSTEM' must have the 'Connect SQL',
  'Alter Any Availability Group', and 'View Server State' permissions.
+* There are circumstances where the PowerShell module _SQLPS_ that is install
+ together with SQL Server does not work with all features of this resource.
+ The solution is to install the PowerShell module [_SqlServer_](https://www.powershellgallery.com/packages/SqlServer)
+ from the PowerShell Gallery. The module must be installed in a machine-wide
+ path of `env:PSModulePath` so it is found when LCM runs the DSC resource.
+ This will also make all SqlServerDsc DSC resources use the PowerShell
+ module _SqlServer_ instead of the PowerShell module _SQLPS_.
 
 ## Known issues
 

diff --git a/source/DSCResources/DSC_SqlRSSetup/DSC_SqlRSSetup.schema.mof b/source/DSCResources/DSC_SqlRSSetup/DSC_SqlRSSetup.schema.mof
@@ -7,11 +7,11 @@ class DSC_SqlRSSetup : OMI_BaseResource
  [Write, Description("The action to be performed. Default value is 'Install' which performs either install or upgrade."), ValueMap{"Install","Uninstall"}, Values{"Install","Uninstall"}] String Action;
  [Write, EmbeddedInstance("MSFT_Credential"), Description("Credentials used to access the path set in the parameter 'SourcePath'.")] String SourceCredential;
  [Write, Description("Suppresses any attempts to restart.")] Boolean SuppressRestart;
- [Write, Description("Sets the custom license key, e.g. '12345-12345-12345-12345-12345'.")] String ProductKey;
+ [Write, Description("Sets the custom license key, e.g. '12345-12345-12345-12345-12345'. This parameter is mutually exclusive with the parameter Edition.")] String ProductKey;
  [Write, Description("Forces a restart after installation is finished. If set to $true then it will override the parameter SuppressRestart.")] Boolean ForceRestart;
  [Write, Description("Upgrades the edition of the installed product. Requires that either the ProductKey or the Edition parameter is also assigned. By default no edition upgrade is performed.")] Boolean EditionUpgrade;
  [Write, Description("Upgrades installed product version if the major product version of the source executable is higher than the currently installed major version. Requires that either the ProductKey or the Edition parameter is also assigned. Default is $false.")] Boolean VersionUpgrade;
- [Write, Description("Sets the custom free edition."), ValueMap{"Development","Evaluation","ExpressAdvanced"}, Values{"Development","Evaluation","ExpressAdvanced"}] String Edition;
+ [Write, Description("Sets the custom free edition. This parameter is mutually exclusive with the parameter ProductKey."), ValueMap{"Development","Evaluation","ExpressAdvanced"}, Values{"Development","Evaluation","ExpressAdvanced"}] String Edition;
  [Write, Description("Specifies the setup log file location, e.g. 'log.txt'. By default log files are created under %TEMP%.")] String LogPath;
  [Write, Description("Sets the install folder, e.g. 'C:\\Program Files\\SSRS'. Default value is 'C:\\Program Files\\Microsoft SQL Server Reporting Services'.")] String InstallFolder;
  [Write, Description("The timeout, in seconds, to wait for the setup process to finish. Default value is 7200 seconds (2 hours). If the setup process does not finish before this time an error will be thrown.")] UInt32 SetupProcessTimeout;

diff --git a/source/DSCResources/DSC_SqlRSSetup/en-US/DSC_SqlRSSetup.strings.psd1 b/source/DSCResources/DSC_SqlRSSetup/en-US/DSC_SqlRSSetup.strings.psd1
@@ -14,7 +14,7 @@ ConvertFrom-StringData @'
  Restart = Restarting the target node.
  SuppressRestart = Suppressing restart of target node.
  EditionInvalidParameter = Both the parameters Edition and ProductKey was specified. Only either parameter Edition or ProductKey is allowed.
- EditionMissingParameter = Neither the parameters Edition and ProductKey was specified.
+ EditionMissingParameter = Neither the parameters Edition or ProductKey was specified.
  SourcePathNotFound = The source path '{0}' does not exist, or the path does not specify an executable file.
  VersionFound = The Microsoft SQL Server Reporting Service instance is version '{0}'.
  PackageNotFound = Could not determine the version of the Microsoft SQL Server Reporting Service instance.

diff --git a/source/WikiSource/CredentialOverview.md b/source/WikiSource/CredentialOverview.md
@@ -0,0 +1,40 @@
+# Credential Overview
+
+## Group Managed Service Account
+
+To support [Group Managed Service Accounts](https://docs.microsoft.com/en-us/windows-server/security/group-managed-service-accounts/group-managed-service-accounts-overview)
+(gMSAs) the DSC resource must support it. This also applies to Managed Service
+Accounts (MSAs).
+
+There are more information about using (g)MSAs with SQL Server
+in the article [Configure Windows Service Accounts and Permissions](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/configure-windows-service-accounts-and-permissions) in section [Managed Service Accounts, Group Managed Service Accounts, and Virtual Accounts](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/configure-windows-service-accounts-and-permissions#New_Accounts)
+
+To use a (g)MSA with a DSC resource you should pass the (g)MSA account name
+in the credential object and use any text string as password.
+
+>It is not possible to pass `$null` as password, it is a limitation by
+>how the MOF is generated when encrypting passwords.
+
+If there is a resource that you find that will not work with a (g)MSAs then
+please submit a [new issue](https://github.com/dsccommunity/SqlServerDsc/issues/new?template=Problem_with_resource.md).
+Then the community can work together to support (g)MSAs for that DSC resource
+too.
+
+For designing a resource for (g)MSAs see the section [Group Managed Service Account](https://github.com/dsccommunity/SqlServerDsc/blob/master/CONTRIBUTING.md#group-managed-service-account)
+in the contribution guidelines.
+
+<sup>_This was discussed in [issue #738](https://github.com/dsccommunity/SqlServerDsc/issues/738)_.</sup>
+
+## Built-In Account
+
+To use a built-in account with a DSC resource you should pass the built-in
+account name, e.g. 'NT AUTHORITY\NetworkService' in the credential object
+and use any text string as password.
+
+>It is not possible to pass `$null` as password, it is a limitation by
+>how the MOF is generated when encrypting passwords.
+
+If there is a resource that you find that will not work with a built-in account
+then please submit a [new issue](https://github.com/dsccommunity/SqlServerDsc/issues/new?template=Problem_with_resource.md).
+Then the community can work together to support built-in accounts for that
+DSC resource too.
diff --git a/tests/Integration/README.md b/tests/Integration/README.md
@@ -16,6 +16,12 @@ to each other. Dependencies are made to speed up the testing.**
 
 ## SqlSetup
 
+Installs the Database Engine, Analysis Service for both SQL Server 2016
+and SQL Server 2017 in two different Azure Pipelines jobs with the configuration
+names `'Integration_SQL2016'` and `'Integration_SQL2017'`. It will also
+install the Reporting Services 2016 in the Azure Pipelines job with the configuration
+name `'Integration_SQL2016'`.
+
 **Run order:** 1
 
 **Depends on:** None
@@ -68,6 +74,9 @@ properties `IsClustered` and `IsHadrEnable`.*
 
 ## SqlRSSetup
 
+Installs SQL Server 2017 Reporting Services in Azure Pipelines job with the
+configuration name `'Integration_SQL2017'`.
+
 **Run order:** 2
 
 **Depends on:** SqlSetup (for the local installation account)
@@ -243,6 +252,10 @@ worker.*
 
 ## SqlRS
 
+Configures _SQL Server Reporting Services 2016_ and _SQL Server Reporting_
+_Services 2017_ in two different Azure Pipelines jobs with the configuration
+names `'Integration_SQL2016'` and `'Integration_SQL2017'`.
+
 **Run order:** 3
 
 **Depends on:** SqlSetup, SqlRSSetup