fix: non-user-friendly error when trying to install the worker agent as domain user

What was the problem/requirement? (What/Why)

When trying to run the worker agent installer and configure the worker agent to run as a domain user, the installer fails a non-user-friendly message.

For example, on a domain-joined worker host, running:

C:\> install-deadline-worker ... --user someuser

produces the error:

ERROR: The Worker Agent user needs to run as an administrator, but the supplied user (workeragent) exists and was not found to be in the Administrators group. Please provide an administrator user, specify a new username to have one created, or provide the --grant-required-access option to allow the installer to make the existing user an administrator.

If you then try adding the --grant-required-access, you then see:

Traceback (most recent call last):
  File "C:\Program Files\Python-3.10.8\lib\runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Program Files\Python-3.10.8\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Program Files\Thinkbox\DeadlineCloud\install-deadline-worker.exe\__main__.py", line 7, in <module>
  File "C:\Program Files\Python-3.10.8\lib\site-packages\deadline_worker_agent\installer\__init__.py", line 101, in install
    start_windows_installer(**installer_args)
  File "C:\Program Files\Python-3.10.8\lib\site-packages\deadline_worker_agent\installer\win_installer.py", line 925, in start_windows_installer
    agent_user_rights = get_effective_user_rights(user_name)
  File "C:\Program Files\Python-3.10.8\lib\site-packages\deadline_worker_agent\installer\win_installer.py", line 716, in get_effective_user_rights
    group_names = win32net.NetUserGetLocalGroups(None, user)
pywintypes.error: (2221, 'NetUserGetLocalGroups', 'The user name could not be found.')

This is because the install-deadline-worker command was not designed for use with domain users (see #458). The installer calls win32 APIs that do not support specifying domain users in one format or another (User Principal Name (UPN) or Down-Level Logon Name).

While working on this, I discovered that InstallerFailedException exceptions being raised by validation checks in the Windows installer code were not being caught. This resulted in the validation errors showing up as non-friendly Python stack traces instead of clean looking error messages.

What was the solution? (How)

The Windows installer code was modified to validate the user name supplied in the --user argument. If the username contains a \ or @ character, which is a signal that the username is UPN or down-level logon name, then the installer fails fast with a clear and actionable error:

C:\> install-deadline-worker --farm-id %FARM_ID% --fleet-id %FLEET_ID% --user DOMAIN\foo
ERROR: running worker agent as a domain user is not currently supported. You can have jobs run as a domain user by configuring the queue job run user to specify a domain user account.

C:\> echo %ERRORLEVEL%
1

C:\> install-deadline-worker --farm-id %FARM_ID% --fleet-id %FLEET_ID% --user foo@DOMAIN
ERROR: running worker agent as a domain user is not currently supported. You can have jobs run as a domain user by configuring the queue job run user to specify a domain user account.

C:\> echo %ERRORLEVEL%
1

I also modified the installer entrypoint to handle InstallerFailedException exceptions and format them into human-readable output.

What is the impact of this change?

People trying to run the worker agent installer command (install-deadline-worker) and supplying a domain user for the agent to run as with the --user argument get a user-friendly and actionable error message indicating this is not supported but that they can run jobs as a domain user by configuring their Deadline queue.
Failed validation checks in the Windows install code that raise InstallerFailedException exceptions will no longer output stack traces, but instead nicely formatted error messages.

How was this change tested?

Added a unit test which is passing
Ran the installer on a Windows machine (see the produced error message above)

Was this change documented?

Code comments were added and behavior was changed to improve an error message.

Is this a breaking change?

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

aws-deadline / deadline-cloud-worker-agent