Select Language:

When creating machine images in AWS, it’s important to follow a clear process to prevent errors during deployment, especially with Windows systems. If you try to modify local accounts—like renaming or disabling the Administrator account—while the EC2 Image Builder pipeline is running, you may encounter issues with Sysprep and AWS orchestration tools. These problems happen because some parts of the process rely heavily on default account names and configurations.

The best way to avoid these problems is to leave account modifications out of the image-building process altogether. Instead, create a standard, general-purpose image and then make your account changes after the image is finished and the OS has been generalized. This approach ensures that Sysprep runs smoothly and AWS tools work without interruption.

Here’s why your current approach can cause failures during image creation:

AWS Task Orchestrator and Executor (AWSTOE), which manages the setup steps, depends on the default Administrator account to run scripts, track progress, and verify success. Renaming or disabling this account beforehand can cause the pipeline to hang or fail because AWSTOE can’t operate properly.

ADVERTISEMENT
Sysprep, the tool that prepares Windows images for deployment, expects a standard account setup. Changes to the local accounts before running Sysprep can be overridden or cause the process to break because Sysprep relies on specific account settings in the unattend.xml file.

To fix this, you should keep the Administrator account unchanged during the image build. Instead, perform your account modifications when the final instance is being provisioned. Here are three reliable methods to do this:

Method 1: Use EC2 User Data Scripts
If you are deploying Windows 11 instances with EC2Launch v2, you can pass a PowerShell script via the User Data field in your launch templates. This script runs automatically during the first boot after Sysprep, allowing you to change account names, create new user accounts, or remove unnecessary accounts.

For example, a script might look like this:

powershell

Rename default Administrator account

Rename-LocalUser -Name “Administrator” -NewName “MainAdmin”

Rename Guest account

Rename-LocalUser -Name “Guest” -NewName “GuestUser”

Remove a specific account if it exists

if (Get-LocalUser -Name “Workspaces_BYOL” -ErrorAction SilentlyContinue) {
Remove-LocalUser -Name “Workspaces_BYOL”
}

Create a new local user and add to administrators

$Password = Read-Host -AsSecureString “Create a secure password”
New-LocalUser “NewAdmin” -Password $Password -FullName “Admin User”
Add-LocalGroupMember -Group “Administrators” -Member “NewAdmin”

Method 2: Use Group Policy Settings
If your images are for Amazon WorkSpaces or will join AWS Managed Microsoft AD, configuring account names via Group Policy is a secure, scalable solution. You can set policies to rename the administrator and guest accounts immediately after the machine joins the domain, eliminating the need for scripting.

Navigate to:
Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Security Options
Then enable and configure the options for renaming accounts.

Method 3: Modify EC2Launch Configuration
Advanced users can customize other parts of the EC2Launch system, like editing agent-config.yml or unattend.xml, to run scripts during the first startup. However, this approach adds complexity to your image-building process and is generally more difficult to maintain. Using User Data scripts or Group Policy is simpler and more straightforward.

In summary, the key is to create a clean, generic image without account changes and then make those changes during or after deployment. This prevents errors, ensures compatibility with Windows Sysprep, and keeps your deployment process smooth and reliable.