diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 79a46819d..000000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -If you'd like to contribute to this project, please review the [Contribution Guidelines](https://github.com/PowerShell/DscResources/blob/master/CONTRIBUTING.md). diff --git a/CHANGELOG.md b/CHANGELOG.md index e8774bba9..e2b8a2011 100644 --- 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 index 294a5233d..47acdeca8 100644 --- 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,14 +116,13 @@ 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. @@ -114,18 +130,23 @@ 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 index dfb2230d5..387c1d19f 100644 --- 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 index c775685f8..44a235e10 100644 --- 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 index 74a389e48..cb8af1465 100644 --- 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 new file mode 100644 index 000000000..6f119227c --- /dev/null +++ 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. + +_This was discussed in [issue #738](https://github.com/dsccommunity/SqlServerDsc/issues/738)_. + +## 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 index 517e93842..348b4fe5c 100644 --- 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