Deploying ControlUp Edge DX Agent with custom bundles for Amazon WorkSpaces Personal and Amazon WorkSpaces Pools
Using the configuration options in this walkthrough, you can automatically install the ControlUp Edge DX Agent in your custom bundle. This method can be used for any agent that requires a registration process in custom bundles.
Published Feb 14, 2025
A WorkSpace bundle is package deal including an operating system, storage, compute, and software resources. When you start up a WorkSpace, you pick the bundle that works for you. The basic bundles available for WorkSpaces are called public bundles.For more information about the various public bundles available for WorkSpaces, see Amazon WorkSpaces Bundles.
A custom image contains the OS, software, and settings for a WorkSpace. A custom bundle combines a custom image with hardware configurations. After you create a custom image, you can build a custom bundle to launch new WorkSpaces with consistent configurations. Do review the latest Best Practices for deploying Amazon Workspaces document for more information.
Using custom bundles reduces the time to value when deploying WorkSpaces. With a custom bundle, a new WorkSpace is available with all the components the user needs already installed and configured ready to go. This can include software agents, such as the Controlup Edge agent, to help monitor the WorkSpace and provide tools for remediation and remote support.
When deploying as part of a custom bundle, the Edge DX Agent needs to securely register each new WorkSpace. This process must happen as the WorkSpace starts in order to to uniquely identify each new WorkSpace. Note that WorkSpace creation (either Personal, or Pooled) from a custom bundle goes through multiple reboots before being available. You want registration to happen only as the new WorkSpaces is made available for use.
You can use this method for any agent that requires a registration process. For this example, you preconfigure a ControlUp Edge DX Agent installation as part of a custom bundle for Amazon WorkSpaces. With this configuration, the Agent automatically connects to your environment as part of deployment on startup when the instance is ready for use. Once deployed, the ControlUp Agent Manager automatically keeps the Agent updated according to your Agent version control settings. Other agents’ update mechanisms may vary, but if they need registration to happen.. make the appropriate tweaks for your agent installation.
- Download the Windows agent from your Edge tenant.
- Make a note of the Tenant Name and the Device Registration Code.
- (optional) Get a beverage of your choice.
If your WorkSpaces are part of an Active Directory domain, using Group Policy is the best way to manage startup scripts. Create a Group Policy Object (GPO) that links to your target computers and configures the script to run at startup. This is highly manageable and scalable for domain environments. This method provides centralized control and simplifies deployment.
You typically place your deployment script and resources on a network share accessible by all computers, and then configure the GPO to run the script and host agent install file deployment from that location using a UNC path (e.g., \\server\share\yourdeploymentscript.ps1).
However, you might not have access to the resources needed to configure a Group Policy with a script accessible by all computers. If you’re in this particular painted corner, review the section on using the Task Scheduler within your custom WorkSpaces image.
If you need more insight into creating a custom bundle for your WorkSpaces - review the documentation for creating a custom bundle and do check out the best practices guidance.
- (optional) Create a launch script
[optional] If you need to run the script as part of the custom image (i.e. you don’t have access to launch a GPO from a shared resource) you need a .bat file. Here is an example. Save the following code in a directory (for example) c:\controlup, and name the .bat appropriately for example edgeconf.bat
powershell -executionpolicy Bypass c:\controlup\edgeconf.ps1
- Save the agent configuration script in the custom image
This script is an example of how to install the an agent that needs to register on startup. This script can be used from a scheduled task, or as part of a default GPO for running on a WorkSpaces startup where the WorkSpace is part of a domain. The script monitors the WorkSpace configuration and starts the installation and registration process when the WorkSpace is configured and ready for use. Save the following code in a directory (for example) c:\controlup, and name the powershell script appropriately for example edgeconf.ps1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
#Requires -RunAsAdministrator
# Configuration
$SourceDirectory ="C:\ControlUp"
$LogFile = "$SourceDirectory\WorkspacesCheck.log"
try {
if ([bool]((Get-itemproperty -Path "HKLM:\SOFTWARE\Avacee\SIP").DeviceRegistrationCode)) {
if (Test-Path $LogFile) {
Remove-Item $LogFile -force
}
Add-Content -Path "$LogFile" -Value "$(Get-Date) - Edge agent installed, my work here is done"
exit
}
} catch {
try {
if ((Get-itemproperty -Path "HKLM:\SOFTWARE\Amazon\WorkSpacesConfig").ProvisioningCompletedEventLogged -eq 1) {
Add-Content -Path "$LogFile" -Value "$(Get-Date) - WorkSpace provisioned"
}
} catch {
# not provisioned yet, go about your day, nothing to see here
exit
}
}
# Edge Agent installation settings
# Get these values from your edge tenant Windows Agent install view
$MSIFileName = "agentmanagersetup.msi"
$MSIPATH = "$SourceDirectory\$MSIFileName"
$DEVREGCODE = "[YOUR-DEVREGCODE]"
$TENANT = "[YOUR-TENANT]"
# This is optional, you do you for grouping. This is an example of taking a WorkSpaces' internal region name as the device’s default group
$GROUP = (Get-itemproperty -Path "HKLM:\SOFTWARE\Amazon\WorkSpacesConfig").InternalRegion
# Run the install script -
$Arguments = "/i", "`"$MSIPath`"", "/qn", ("DEVREGCODE="+$DEVREGCODE), ("TENANT="+$TENANT), ("GROUP="+$GROUP), "ALLUSERS=1","/L*V+", $LogFile
Add-Content -Path "$LogFile" -Value "$Arguments - Action performed"
Start-Process -FilePath "msiexec.exe" -ArgumentList $Arguments -PassThru
Add-Content -Path "$LogFile" -Value "$(Get-Date) - Action performed, have a nice day"
- (optional ) Create a schedule task to run on startup
Create a system schedule task on startup to launch the installation script (edgeconf.bat).
Use SYSTEM as the account. Not a service user you say? No, not a service user. Use SYSTEM as the user; the imaging process for custom images doesn’t allow multiple profiles to be used.
Do use the checker script to confirm you’re good to go before committing an environment to be imaged, because you checked out the custom image best practices guidance right.. right?
3.1 Create a scheduled task. Give it a title, set the user account to be SYSTEM.
Image not found
3.2 Set the trigger to begin the task At Startup
Image not found
3.3 Configure the task to launch the .bat file you created in Step 1.
- Complete other configuration tasks, and save the custom image
- Create a custom bundle using the custom image
- Deploy a WorkSpace with the custom bundle and validate the configuration.
The process for creating and deploying a custom image for WorkSpaces Pools is different to WorkSpaces Personal. Do review the process for creating a WorkSpaces Pool custom image. The WorkSpace pool image will use a startup session script to configure the agent.
a. In the WorkSpace used to create the custom image, create a directory e.g. c:\controlup
b. Copy Windows Edge agent to the directory created in Step a.
c. Create an installation file e.g. setup.bat. Insert your configuration information for your controlup tenant.
1
msiexec /i c:\controlup\agentmanagersetup.msi /qn DEVREGCODE=your-device-registration-code TENANT=your-tenant-name ALLUSERS=1 GROUP=your-pool-named. [Optional] include GROUP. You can use device groups to organize devices which can be useful when filtering data, performing actions, configuring Agent version control, and more. Learn more about device groups.
e. [Optional] Add PROXY and PROXY_TEST_IP to the msiexec . Read Proxy server configuration for details.
f. Create a session script config.json file in c:\AWSEUC\SessionScripts
g. Set the sessionstart executables filename appropriately. Don’t forget the double “\”
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"SessionStart": {
"executables": [
{
"context": "system",
"filename": "c:\\controlup\\setup.bat",
"arguments": "",
"s3LogEnabled": true
},
{
"context": "user",
"filename": "",
"arguments": "",
"s3LogEnabled": true
}
],
"waitingTime": 30
},
"SessionTermination": {
"executables": [
{
"context": "system",
"filename": "",
"arguments": "",
"s3LogEnabled": true
},
{
"context": "user",
"filename": "",
"arguments": "",
"s3LogEnabled": true
}
],
"waitingTime": 30
}
}h. Check your work.
i. Do other configuration items as you need
j. Create a custom image, and bundle
k. Use the custom bundle to deploy a WorkSpaces Pool
Custom bundles can reduce the time to value when deploying WorkSpaces Personal instances or WorkSpaces Pools. When deploying agents that need to securely register on startup consider when that agent starts and registeres in the deployment process. WorkSpaces creation (either Personal, or Pooled) from a custom bundle will go through multiple reboots before being available for users.
Using the configuration options in this walkthrough, you can automatically install the ControlUp Edge DX Agent in your custom bundle. This method can be used for any agent that requires a registration process. With this configuration, the Agent automatically connects to your environment as part of deployment on startup when the instance is ready for use. Once deployed, the ControlUp Agent Manager automatically keeps the Agent updated according to your Agent version control settings. Other agents’ update mechanisms may vary.
Why does the header show minifigures in a forest you ask? Clones deployed in the field.. get it? Get it?
You have fun now :)
4 Comments
Log in to comment