feat: add macOS (darwin) support to the worker agent installer

[andychoquette]

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

install-deadline-worker rejected every platform except Linux and Windows, so
macOS hosts could not be configured as workers in a customer-managed fleet —
even though the CMF fleet OS enum already accepts MACOS and the worker-agent
runtime otherwise runs on macOS. Customers want to bring Mac render hosts into their fleets.

What was the solution? (How)

Add darwin as a first-class platform in the installer, mirroring the existing
Linux structure:

• installer/__init__.py

  • Allow darwin through the platform gate.
  • Add a darwin entry to INSTALLER_PATH so install() dispatches through
    the existing sudo <script> ... path to a new install_darwin.sh.
  • Reject --vfs-install-path on macOS (the Deadline VFS is Linux-only),
    surfacing the error before shelling out.

• installer/install_darwin.sh (new) — the macOS port of install.sh:

  • Creates the agent user and job group via Directory Services
    (dscl / dseditgroup) instead of useradd/groupadd, preserving the
    same jobRunAsUser isolation model (agent user's primary group is never the
    job group; job group is a secondary membership only).
  • Provisions the same directories with the same ownership/permissions
    (credentials 700, worker.toml 640, etc.), writes worker.toml via the
    same deadline_worker_agent.config module, and installs a launchd
    LaunchDaemon instead of a systemd unit.
  • Does not write a jobRunAsUser sudoers rule. An earlier revision of this
    PR did; it was removed on review feedback so that macOS matches the Linux
    installer, where granting the agent passwordless sudo to the queue's job user
    is the operator's documented manual step. See
    jobRunAsUser sudo below.
  • Two macOS-specific deviations from a naive port:
    1. Argument parsing uses a portable while/case loop rather than
       getopt --longoptions, because macOS ships BSD getopt (which silently
       drops long options rather than erroring).
    2. The default session root is /var/lib/deadline/sessions, not
       /sessions, because the macOS root volume is sealed read-only
       (macOS 10.15+) and a top-level directory cannot be created there.

• config/settings.py — add DEFAULT_MACOS_SESSION_ROOT_DIR
  (/var/lib/deadline/sessions) and select it on darwin in the settings model
  and the installer arg-parser default, so a stock install-deadline-worker
  (no --session-root-dir) works out of the box on macOS.

jobRunAsUser sudo: left to the operator, matching Linux

openjd-sessions runs a Session's actions as the queue's jobRunAsUser via
sudo -u <job-user> -i ..., which needs the agent user to become a job user
without a password. This installer does not configure that, and neither does
install.sh — on Linux it is a documented manual step in the
developer guide,
where the operator writes:

deadline-worker-agent ALL=(jobRunAsUser) NOPASSWD:ALL

macOS now behaves the same way. An earlier revision of this PR wrote a
group-scoped rule (deadline-worker ALL=(%deadline-job-users) NOPASSWD: ALL)
automatically, on the reasoning that the failure is silent on macOS — a
LaunchDaemon has no TTY, so every impersonated action dies with sudo: a terminal is required to read the password and the task loops READY ↔ ASSIGNED with
nothing on the host explaining why. That rule has been removed following
review feedback: the right move is to match the Linux install process first, and
treat automating this (with or without an installer flag) as a separate
quality-of-life change that lands for both platforms together rather than
diverging them here.

Consequences worth stating plainly:

• A stock macOS install cannot run jobs on a queue using
  runAs = QUEUE_CONFIGURED_USER until the operator adds the sudoers rule by
  hand. Same as Linux, but the macOS failure mode is quieter, so this needs to be
  called out in the macOS worker-host documentation (tracked as the docs
  follow-up below).
• Queues using runAs = WORKER_AGENT_USER are unaffected and work out of the
  box: the agent passes no user to openjd-sessions,
  PosixSessionUser.is_process_user() short-circuits the sudo branch, and
  actions run as the agent user directly.
• Removing the rule also removes the privilege question it raised. There is no
  longer a stock install that grants the agent user authority over every current
  and future member of the job group, so the WORKER_AGENT_USER concern raised
  earlier in this review no longer applies to this PR.

The installer still writes the --allow-shutdown rule
(/etc/sudoers.d/deadline-worker-shutdown, 440 root:wheel, granting exactly
/sbin/shutdown -h now as root) — that one has a direct Linux counterpart and is
flag-gated. It is installed through a install_sudoers_file helper that writes to
a temp path, runs visudo -cf, and only then moves the file into place, so a file
sudo cannot parse never appears in /etc/sudoers.d (where it would break sudo
host-wide). The Linux installer validates nothing here, so this is a small
improvement on the baseline.

What is the impact of this change?

macOS hosts can be installed as customer-managed-fleet workers. Linux and
Windows behavior is unchanged (the Linux install.sh and Windows installer
paths are untouched; only a new darwin branch and a new script are added).

Dependency note: running a job as a jobRunAsUser on macOS also requires the
companion openjd-sessions changes (macOS lacks setsid(1), which that PR replaces
with a pure-Python session-leader shim); see
OpenJobDescription/openjd-sessions-for-python#335, now merged.
This PR covers host installation; that PR covers cross-user job execution, and neither
is useful without the other — without the shim the macOS cross-user spawn fails at
setsid regardless of how sudo is configured on the host.

That shim ships in openjd-sessions 0.10.14 (published), so this PR bumps the
pin from == 0.10.13 — which predates the merge and resolves to a build without the
shim — to == 0.10.14. Verified against the published sdist that it contains
_MACOS_SETSID_SHIM, is_macos(), and the pgrep retry fix.

Prerequisite: macOS worker hosts require the Xcode Command Line Tools (for
the OS-provided /usr/bin/python3 used by the openjd-sessions cross-user path).

Not covered here: neither this installer nor the Linux one creates the
jobRunAsUser accounts, enforces their job-group membership, or grants the agent
sudo to them. All three are operator steps. On macOS each one fails quietly if
missed (no TTY for sudo to prompt on), which is why the user-guide follow-up below
matters — there is currently no macOS worker-host setup page in the public docs at
all.

Pre-existing issues surfaced while reviewing this (not introduced here, not
fixed here) — filing separately unless reviewers want them in scope:

• --scripts-path is only checked for existence, never ownership, yet the
  LaunchDaemon execs ${scripts_path}/deadline-worker-agent at every boot. A
  group-writable venv (common on macOS, e.g. /opt/homebrew/bin is
  drwxrwxr-x root:admin) means a local admin user can replace the binary and
  run code as the agent user on next boot. Same gap in install.sh.
• worker.toml.example is copied from $SCRIPT_DIR, so the same writable-path
  precondition allows config poisoning on a fresh install. Same in install.sh.
• queue_boto3_session.py:367-372 chmods each queue's cached credentials 0640
  and chowns them to the queue user's group. If two queues resolve to the same
  posix group, one queue's job user can read the other's AWS credentials. Purely
  inherited (identical code path and directory modes on Linux), but it is the
  highest-impact credential exposure in this area and the installer's default
  group naming makes the misconfiguration easy to reach.

How was this change tested?

• Added unit tests (test/unit/install/test_install.py): INSTALLER_PATH has a
  darwin entry, install() builds the expected sudo command on darwin, and
  --vfs-install-path is rejected before dispatch. Removed darwin from
  test_unsupported_platform_raises (it is now supported). Updated the
  session_root_dir settings-field test to expect the platform-correct default.
• Full test/unit install + config suites pass (hatch run test): 726 passed.
• Added macOS installer integration tests (test/integ/macos/test_installer.py)
  that run the installer for real as root and assert the invariants it must
  establish: hidden service account, the primary-group/job-group isolation
  invariant, file modes, LaunchDaemon plist contents, and the sudoers rules.
  They mutate host state, so they are gated behind RUN_INSTALLER_TESTS=true
  and run on throwaway macOS runners via the new macos_installer_test.yml
  workflow. No AWS access needed — the farm/fleet ids are fakes.
  • Sudoers coverage specifically: the jobRunAsUser rule exists with mode 440 root, parses under visudo -cf, and contains exactly the one
    group-scoped rule (so an added rule or a widened runas list fails the
    test); the shutdown rule is asserted separately and is revoked on a re-run
    without --allow-shutdown.
• Validated end-to-end on macOS 26.5 (arm64) against a live customer-managed
  fleet: install-deadline-worker → the worker registers and reaches IDLE → a
  job runs as the queue's jobRunAsUser (uid 498, gid 501) → the job user
  cannot read the agent's cached credentials → the job is cancelled and its
  process group is reaped with no orphaned processes. Installer re-runs are
  idempotent.

Was this change documented?

Code comments in install_darwin.sh explain the macOS-specific choices (BSD
getopt, read-only root volume, Directory Services user/group creation,
launchd mappings) and flag items that warrant host-level verification (TCC /
Full Disk Access, code-signing / notarization for a headless daemon, the exact
shutdown argv for --allow-shutdown). The sudoers block documents which queue
configurations the rule affects, why Linux needs an equivalent rule as a manual
step, and that job group membership is the security boundary.

Public user-guide documentation (AWSBeaLineDocs) is a separate follow-up. It is
load-bearing here: the fleet-types table already lists macOS for CMF, but there
is no macOS worker-host setup page, and the worker agent README still states
that install-deadline-worker "does not support MacOS at this time" — that line
needs updating alongside this change.

Is this a breaking change?

No. It adds a new supported platform; Linux and Windows install behavior is
unchanged and no public interface is modified.

---

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

[crowecawcaw]

LGTM. I think we should open an issue to convert the linux and mac install scripts to Python so code is cleaner, we're not building structures strings in bash, and so we can test them better.

Also do we have an E2E test we'll run? Is it possible to run one in GitHub actions?

[andychoquette]

I'll get that issue added and add an e2e test before we merge this.

[andychoquette]

added e2e test in 3853d23

[crowecawcaw]

New test looks good! For testing, I think we want an additional test that spins on a Mac instance, runs this install script, and verifies the worker registers to the real Deadline service and picks up a task. Even better if it also triggers the instance to restart and verifies it re-attaches successfully.

[github-actions]

The plist sets no ExitTimeOut, so launchd applies its default of 20 seconds: on launchctl bootout / launchctl kickstart -k / system shutdown, launchd sends SIGTERM and then SIGKILLs the agent 20s later.

The Linux unit sets no TimeoutStopSec, so it gets systemd’s default of 90s. That is a ~4.5x reduction in drain time that exists only on macOS.

This matters because SIGTERM is exactly what starts the agent’s graceful drain (worker.py:139 registers _signal_handler, which drives Scheduler.shutdown), and that drain is deliberately unbounded — scheduler.py:1471 passes gracetime = None with the comment "Let the cancels happen as defined in the Job Template". So the scheduler waits for each session’s cancelation as the Job Template defines it, which routinely exceeds 20s. Consequences on macOS:

• SIGKILL at t=20s skips _agent_shutdown, so the worker never reports STOPPED and sits in STOPPING until the service-side timeout.
• Session subprocesses (sudo -u <jobRunAsUser> ...) are orphaned rather than cancelled, leaving job processes and session directories behind.
• --allow-shutdown autoscaling drains are truncated the same way, since _repeatedly_attempt_host_shutdown runs inside that same window.

Note also that test/e2e/test_job_submissions.py::test_worker_enters_stopping_state_while_draining uses launchctl bootout against a sleep 600 task and allows 120s. The 20s SIGKILL would land well inside that window, and because the test accepts STOPPING it would still pass while the process was being hard-killed.

Suggest setting ExitTimeOut explicitly so the macOS grace period matches Linux — an ExitTimeOut integer key of 90 alongside KeepAlive/RunAtLoad. (0 means "wait forever", also an option if a fully unbounded drain is intended, but a finite value matching systemd’s default is the closer port.)