Staged rollouts
This article discusses how to use the 1E PowerShell Toolkit to manage a staged rollout of a 1E Platform instruction. A staged rollout is a process where an 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-1EInstruction cmdlet to send instructions to devices in the normal way. You specify either a target scope (that is, 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 targeted. 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.
Tracking instruction completion and success
While it is useful to simply target a random subset of the device estate (for example, to get an approximation of how many devices have a particular piece of software installed, or the operating system breakdown across the estate), you may also wish to track the devices which were targeted so that if you then re-invoke the instruction, a fresh subset of devices will be targeted instead.
You can specify that instruction completion should be tracked by using the -TargetFile <file> option. The specified file is created automatically if it does not exist. When the invoke-1Einstruction cmdlet is first run and the file is created, at the conclusion of the 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 a device, the Status and ErrorData members will record the failure code and reason for failure.
Regardless of whether the instruction succeeded or failed, a device which is recorded on the target file will not be chosen again when invoke-1Einstruction is re-run specifying the same target file.
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.
Rollout completion
Rollout completion occurs when all candidate devices have received the instruction and been recorded on the target file. If invoke-1Einstruction is re-run after this point, it will report that there are no target devices left to process and return immediately.
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.
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.
At present, the 1E Platform 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. Therefore, to avoid significant overheads, 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 use the get-1Etargetsfromfile 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-1Einstruction. When you do this, the instruction is then automatically sent to the devices that you retrieved from the target file.