Distributed Cache Service Identity: Turning the Playbook into real Tools

Print | posted on Sunday, April 03, 2016 12:18 PM

A couple of weeks ago I posted about the Playbook Imperative and Changing the Distributed Cache Service Identity, which generated a lot of interest and feedback regarding the “tooling approach” presented. The original intention of the post was to articulate the importance of understanding the playbook when performing operational service management of SharePoint farms. I had never intended to show “how to do it” in terms of creating tooling in Windows PowerShell. The PowerShell examples were created purely to demonstrate the playbook and were deliberately done in a way that meant the focus was on the tasks being performed rather than the plumbing that governed execution. Similarly I deliberately picked the service account example as it is simple enough to not get bogged down in (too much) detail but with enough gotchas and variance to demonstrate why the playbook is paramount. It also didn’t hurt that it’s a “pattern” that wasn’t previously documented.

At any rate, many folks have asked “why do it like that?”, “why use Invoke-Expression?”, “what’s up with all the individual scripts?”, and so on. Again the point was that these are examples. Examples to demonstrate the playbook without any extraneous considerations. I even stressed in the article that “the implementation choice is a lifestyle preference”. The idea being that the information and basic scripts can be “leveraged” in your tooling implementation of choice. No matter, tons of you asked for a tool. Who knew that Distributed Cache was such a popular thing?! Everyone I normally speak to hates it with a passion! :)

So how would one go about turning the playbook into some form of real tool? It’s all dead simple, but based on the feedback its worth walking through the “method”…

Of course the tooling choice should only be made based upon some requirements and design constraints (remember those? :)). It’s all very well to start out with something very desirable, like Desired State Configuration but by jumping on that you immediately create some pretty hefty constraints and indeed add additional pre-requisites into the picture. As I mentioned in the earlier post I have a some DSC resources built from the same playbook, they don’t take long to create. But of course such resources mean you have to use DSC and have it setup ready to go in your farm. Very few non Azure customer farms are managed by DSC. It’s not how it should be, but it is how it is.

So let’s state some requirements.

1. Firstly I want my tool to be useable in any SharePoint 2013 or SharePoint 2016 deployment. I only care about these two versions because they are the only two which include Distributed Cache.
2. I want my tool to work regardless of how many machines are running Distributed Cache. 0, 1, 2, 3 or more. It should just take care of business.
3. Also, the tool should work (i.e. be executable) from any server in the farm, regardless of whether the server is hosting Distributed Cache or not. I shouldn’t have to (as the operator) deal with Remoting onto the appropriate machine if I want to do something there. This is one of the biggest flaws of the native *-SPDistributedCache* cmdlets (because they can’t introduce a dependency on Remoting).
4. I want the tool to be quickly installable on any SharePoint Farm I may have the pleasure of operating.
5. I want the tool to follow as much as the PowerShell mantra as possible, to follow the rules as it were, unlike so many of the SharePoint cmdlets!
6. I want the tool to work with a MinRole deployment, so I don’t need an alternative version when working with farms using MinRole.

Given these requirements we can also detail some constraints:

1. PowerShell Remoting is required to be available on every server in the farm
2. The operator is expected to know the playbook!

OK, so constraint number two is pretty risky. But hey, if you want the Big Magic Button for SharePoint Farms keep dreaming. It is never going to happen.

Because of all of the above, the best choice is a PowerShell Module. They are easy to create and test, but more importantly easy for people to get and use. They have no substantial dependencies, and the ones they do have can be avoided.

Thus, I have moved things around a little bit from the previous scripts and in a nutshell instead of a bundle of scripts there is now a Function for each activity. Each of them can be used independently (if the operator is doing something else with Distributed Cache and knows what they are doing) or following a very simple operational run book. Much of the modification is in respect to the Remoting aspects. Instead of calling Invoke-Expression to run a script, I build ScriptBlocks where necessary and Invoke those. This increases the overall plumbing but provides a better tool and also reduces the number of functions required.

The main change is to the logic which actually does the change of the service account. It takes the playbook outlined a step further and caters for all my requirements above and all the potential deployment scenarios it may be run in. By no means is it bullet proof, but it’s certainly adequate if the operator knows what they are doing.

The end result are a handful of functions I can use to execute the run book for changing the service account, as follows:

$ManagedAccountName = "FABRIKAM\sppservices"
$ShellAdminAccountName = "FABRIKAM\spshelladmin"
$CacheSize = 500

$Credential = Get-Credential $ShellAdminAccountName

Get-DistributedCacheStatus -Credential $Credential -CacheHostConfiguration
Update-DistributedCacheIdentity -ManagedAccountName $ManagedAccountName -Credential $Credential
Update-DistributedCacheSize -CacheSizeInMB $CacheSize -Credential $Credential
Get-DistributedCacheStatus -Credential $Credential -CacheHostConfiguration

Note: the reality is the scripts I originally presented were modified from a PowerShell Module I had already created many moons ago for the MCSM program and have been using since. I’ve pruned it down significantly for this “version” as my original module contains a whole bunch of other Distributed Cache stuff not related to the topic at hand.

The Module is available on the PowerShell Gallery. If you have WMF 5.0 installed and an Internet connected machine, you can install it simply by running this:

Install-Module -Name SharePointDistributedCache

If the SharePoint boxes don’t have Internet you can do this on another machine or use Save-Module to bring over the files and then you can just copy them to C:\Program Files\Windows PowerShell\Modules and you are good to go. Dead simple, just like any other Module. If you want to verify the module is available run:

Get-Module -ListAvailable

Note that the module does not require WMF 5 to work, only for the PowerShell Gallery hook-up. You can import the module on earlier versions with:

Import-Module SharePointDistributedCache

That’s all there is to it. Nothing complicated, merely a question of taking the scripts and turning them into Advanced Functions and then creating a Module containing them. PowerShell tool making basics at the end of the day.  There’s certainly some improvements I know I should make and it’s clearly obvious there are other flaws but hopefully this module is helpful to those who got in touch following the previous post. I encourage everyone working with SharePoint to build tools, not scripts!

s.