Published on 5 September 2018 by

Editor's note: Andrew Ball is a guest blogger sharing his experience using Puppet’s dsc_lite module.

The systems administration team at the University of Saskatchewan has been managing SharePoint farms through a number of versions and upgrades. Typically, we would not re-deploy a farm unless absolutely necessary because the farms were manually installed, and managed by either a GUI or a series of one-time scripts to configure settings or change them as needed. This led to each upgrade requiring a great deal of planning and effort. The last one from 2010 to 2013 required months to plan and execute.

We were recently tasked with upgrading a SharePoint 2013 farm to 2016. For our previous upgrade, we would have looked at how to do this with an XML and autospinstaller. For those not familiar with SharePoint, this is a well-known and popular method to deploy a farm. In fact, this is how we installed our SharePoint 2013 farm previously.

While it accomplishes the same task (install SharePoint bits and configure them, which is a sizeable task on its own), autospinstaller is an install-time only script. This means it only configures the system once, after that you had to manually configure the system. If we had continued that method, the overhead would remain high to maintain it. In the case of our old SharePoint 2013 farm, there were many manual changes made to it over the years. Those changes are very difficult to reflect in the XML used for autospinstaller. This meant tracking these changes in documents that humans had to follow, which is prone to error. One such example of manually tracked changes would be web application permissions and settings. These are first set by autospinstaller and then manually tracked and changed over time. autospinstaller is also limited in terms of the specific settings that can be scripted, such as more than one search service application, and other more complex real-world scenarios. The process of spinning up a farm this way is still long, error-prone, and not quite repeatable.

Enter the SharePointDsc PowerShell DSC module and Puppet’s new dsc_lite module. The combination of these two is very powerful and useful in deploying a SharePoint farm. These modules enable management of each group of SharePoint settings as individual puppet resources.

For example, a new SharePoint Web Application can be described like this:

dsc{'mywebapp':
        resource_name => 'SPWebApplication',
                module      => 'SharePointDsc',
                properties  => {
                'ensure'                           => present,
                'name'                             => ‘mywebapp’
             'applicationpool'              => ‘mywebapppool’,
                'applicationpoolaccount' => ‘MYDOMAIN\apppool’,
                'allowanonymous'          => true,
                'databasename'            => ‘mywebappDB’,
                'databaseserver'          => ‘sqlserver’,
                'url'                              => ‘http://mywebapp.mydomain.com’,
                'port'                             => '80',
                'psdscrunascredential'   => $runascredentials,
                },
          }

You might know of the other Puppet module that handles DSC resources, called dsc. Why use dsc_lite and not the dsc module? First, looking at the SharePointDsc GitHub repo, there’s active development happening but the release cadence isn’t exactly predictable. With the dsc module, you are locked to a specific release version until the entire dsc module is updated.

The dsc_lite module provided us with the flexibility to keep up with releases, or even write our own bug fixes in forked dsc code without a whole lot of effort. For example, when we first began working on the profile for SharePoint, the current SharePointDsc release was 2.2 and it is now (3 months later) 2.4. The list of fixes between these releases is substantial. The changelog reflects this. With the older puppetlabs-dsc module, you cannot take advantage of the fixes in 2.4 until they are included in a new release of the module. The dsc_lite module allows to the flexibility to use the new code by simply upgrading to the newer SharePointDsc module on target nodes.

The shift from dsc to dsc_lite also comes with one more caveat. The individual PowerShell DSC resource modules need to be installed before the DSC resources can be accessed and used via dsc_lite. In our case, we package the DSC resource modules into Chocolatey packages. (For more info about Chocolatey, visit https://chocolatey.org/.) We manage them as package resources via Puppet, then ensure the dsc_lite resources have the appropriate require statements.

            package{'sharepointdsc':
            ensure   => '2.4’,
            provider => 'chocolatey',
            }
            dsc{ 'InstallPrereqs':
            resource_name => 'SPInstallPrereqs',
            module      => 'SharePointDsc',
            properties  => {
                'installerpath' => $prereqs,
                'onlinemode'    => true,
                'ensure'        => present,
            },
            require     => Package['sharepointdsc'],
            }

There is one more code-related catch that anyone attempting to install SharePoint will encounter: the farm passphrase. It does need to be a PSCredential, but SharePointDsc ignores the username supplied with the password. From my testing, it can be any string except an empty one or nil. For example:

            dsc{ 'spfarm':
            resource_name => 'SPFarm',
            module             => 'SharePointDsc',
            properties         => {
                'ensure'                                => present,
                'serverrole'                   =>  ‘myminrole’,
                'Farmconfigdatabasename' => ‘configDB’,
                'databaseserver'        => ‘mysharepointsql’,
                'farmaccount'           => $farmcredentials,
                'passphrase'            => {
                'dsc_type'      => 'MSFT_Credential',
                'dsc_properties' => {
                        'user'  => 'Placeholdercanbeanything',
                        'password' => ‘Myfarmpassphrase’,
                    }
                },
                'admincontentdatabasename' => ‘adminDB’,
                'runcentraladmin'       => true,
                'psdscrunascredential'  => $runascredentials,
            },
            }

Finally, the resulting manifest for our farms is not small. The number of resources available to be managed via SharePointDsc is extensive, and the dependencies between SharePoint resources also need to be accounted for (one cannot start provisioning site collections without a web application first, for example). So in this case, a long manifest is actually expected since there’s over 100 individual resources that can be managed by the SharePointDsc module.

Regardless of the length and dependencies, it means we are able to deploy the farms in a repeatable way. It has also meant that during our upgrade project, we have been able to re-provision a farm environment in under a day when previously it would take a week or two. In addition, we gain the benefits of any changes to the configuration being tracked in version control and being able to see who defined them and when. Finally, Puppet ensures the configuration remains as defined, and we can verify this via the reports that it was successfully applied. This led the upgrade to be very successful, and the predictable known state of the farms contributed to zero support calls post-upgrade.

Andrew Ball is a systems administrator at the University of Saskatchewan.

Learn more

Share via:

Add new comment

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.