Staged rollouts using the 1E PowerShell Toolkit
How to use the PowerShell Toolkit to manage a staged rollout of an instruction. A staged rollout is a process where a instruction is sent to a subset of the target devices available in a series of 'tranches'. Each tranche targets a percentage or count of devices. At the conclusion of the tranche the success or failure of the tranche is recorded to an output file which is then used as input to a subsequent tranche. When all candidate target devices have been selected, the rollout is complete.
Rolling out an instruction to a subset of your estate
You use the invoke-TachyonInstruction cmdlet to send instructions to devices in the normal way. You specify either a target scope (i.e a match pattern, currently against device FQDN) or a target FQDN list.
Two optional commands allow you to target a subset of the scope or FQDNs that you specify:
-TargetCount <count> specifies that a count of devices is to be targetted. The devices are randomly chosen from the candidate list.
-TargetPercent <percent> specifies that a percentage (from 1 to 99) of the devices are to be chosen. The devices are again randomly chosen from the candidate list.
Note
The -TargetCount and -TargetPercent options apply to this invocation of the instruction. Each time you repeat the invocation, a fresh set of devices are chosen until no further devices are available.
For example, if you specify a -TargetPercent value of 50 and you have 1,000 devices as the target scope or FQDN list, then 500 devices will be chosen for the first invocation and then the remaining 500 for the second.
If you specified a -TargetPercent value of 80 in the above scenario, then 800 devices will be chosen for the first invocation. Then the remaining 200 will be chosen for the second because these are all that are still available.
Tracking instruction completion and success
While it is useful to simply target a random subset of the estate - for example, to get an approximation of how many devices have a particular piece of software installed, or the OS breakdown across the estate - you may also wish to track the devices which were targetted so that if you then re-invoke the instruction, a fresh subset of devices will be targetted instead.
You specify that instruction completion should be tracked by specifying the -TargetFile <file> option.
The specified file is created automatically if it does not exist. When the invoke-instruction cmdlet is first run and the file is created, at the conclusion of instruction execution the file is updated with a list of devices and the associated information about the instruction as shown below.
[
{
"Id": 639,
"fqdn": "NLPTTIUWD18522.LGSV1911.tch13.local",
"ErrorData": "",
"CreatedTimestampUTC": "2020-08-03T14:44:22.57Z",
"Status": 0,
"CreatedBy": "TCH13\\PerfTest"
}
,
{
"Id": 639,
"fqdn": "D29YNAEKJ34032.LGSV1910.tch13.local",
"ErrorData": "",
"CreatedTimestampUTC": "2020-08-03T14:44:22.57Z",
"Status": 0,
"CreatedBy": "TCH13\\PerfTest"
}
,
{
"Id": 639,
"fqdn": "S6T6LJXSM32408.LGSV1911.tch13.local",
"ErrorData": "",
"CreatedTimestampUTC": "2020-08-03T14:44:22.57Z",
"Status": 0,
"CreatedBy": "TCH13\\PerfTest"
}
,
{
"Id": 639,
"fqdn": "GZOGTKFZY18884.LGSV1910.tch13.local",
"ErrorData": "",
"CreatedTimestampUTC": "2020-08-03T14:44:22.57Z",
"Status": 0,
"CreatedBy": "TCH13\\PerfTest"
}
,
{
"Id": 639,
"fqdn": "EMNIJNRX341947.LGSV1910.tch13.local",
"ErrorData": "",
"CreatedTimestampUTC": "2020-08-03T14:44:22.57Z",
"Status": 0,
"CreatedBy": "TCH13\\PerfTest"
}If the instruction fails on an device, the Status and ErrorData members will record the failure code and reason for failure.
Regardless of whether the instruction succeeded or failed, an device which is recorded on the the target file will not be chosen again when invoke-instruction is re-run specifying the same target file.
Rollout completion
Rollout completion occurs when all candidate devices have received the instruction and been recorded on the target file. If invoke-instruction is re-run after this point, it will report that there are no target devices left to process and return immediately,
Note
The initial implementation of this feature assumes that an instruction runs as a question rather than an action. Actions must be approved via workflow so if you invoke an action, you will need to approve it before the target file can be updated with the results.
Note
It is assumed that the user will use the same target file for the same instruction during a rollout. If you attempt to specify an existing target file which was created from a different instruction, an error will be thrown.
Note
At present the 1E API does not allow the user to determine the specific devices which received an instruction. For aggregating instructions, in particular, it is not possible to determine the devices that received the aggregated instruction without drilling down and retrieving per-device information.
To avoid significant overheads therefore, the current implementation of this feature assumes that a candidate device received an instruction if it was a selected target. If the device actively returned an error, it will be correctly recorded.
Following up rollouts
At any stage in the rollout you might want to send an instruction to the devices processed so far, possibly to verify that the device is now configured as you expect. You get use the get-Tachyontargetsfromfile cmdlet to get back an array of FQDNs from a target file. If you assign the result to a variable you can then invoke an instruction and specify this variable as the -targetfqdns argument to invoke-Tachyoninstruction.
When you do this, the instruction is then automatically sent to the devices that you retrieved from the target file.