AWS Deadline Cloud Worker Agent

The AWS Deadline Cloud worker agent can be used to run a worker in an AWS Deadline Cloud fleet. This includes managing the life-cycle of a worker and its assigned work both in the service and on the worker's host.

Deadline Cloud schedules work as worker sessions which are an extension of Open Description (OpenJD) sessions specific to AWS Deadline Cloud. The worker agent initiates session actions, monitors them, and reports the status of running and completed session actions to the service including progress, logs, process exit code, and indicates if the work was canceled or interrupted.

The worker agent behavior follows the AWS Deadline Cloud worker API protocol that specifies the expectation of how the service and workers behave and collaborate through Deadline Cloud's worker APIs.

For guidance on setting up the worker agent for use in a customer-managed fleet, see the "Manage Deadline Cloud customer-managed fleets" topic in the AWS Deadline Cloud User Guide

Compatibility

The worker agent requires Python 3.9 or higher. There are additional platform-specific requirements listed below:

Linux:

Amazon Linux 2 and 2023 are recommended and tested
sudo must be installed

Windows:

Windows Server 2022 is recommended and tested
Requires CPython implementation of Python
Python must be installed for all users (e.g. in C:\Program Files)

MacOS is intended to be used for testing only and is subject to change.

Versioning

This package's version follows Semantic Versioning 2.0, but is still considered to be in its initial development, thus backwards incompatible versions are denoted by minor version bumps. To help illustrate how versions will increment during this initial development stage, they are described below:

The MAJOR version is currently 0, indicating initial development
The MINOR version is currently incremented when backwards incompatible changes are introduced to the public API.
The PATCH version is currently incremented when bug fixes or backwards compatible changes are introduced to the public API.

Installing program files

Linux

We recommend installing the agent in a Python virtual environment (e.g. using venv). For this, run:

# Create venv
python -m venv /opt/deadline/worker

# Activate the virtual environment - you can later type "deactivate" to exit the environment
source /opt/deadline/worker/bin/activate

# Install worker agent program files into the virtual environment
pip install deadline-cloud-worker-agent

Windows

The worker agent runs as a Windows Service which leads to a few installation constraints:

Python virtual environments are not supported
Python must be installed for all users

To obtain the program files, run this command in an administrator command-prompt:

pip install deadline-cloud-worker-agent

Setup worker host

The worker host can be prepared to be run using the provided install-deadline-worker command. This command performs certain functions to setup the worker host based on arguments provided. The command performs all worker host setup activities, such as:

creates an operating system user account (specified by the --user argument) on the worker host that the worker will run as. install-deadline-worker accepts a previously created user. The user defaults to deadline-worker-agent on Linux and deadline-worker on Windows.
creates a job user group (specified by --group, defaults to deadline-job-users) if required. The install-deadline-worker accepts an existing group.
creates cache, log, and config directories, and an example config file
[optionally] initializes the config file
modifies the config file using provided arguments
[optionally] install/update an operating system service
- [optionally] start the operating system service

NOTE: The install-deadline-worker command does not support MacOS at this time.

To see the available command-line arguments, run:

On Linux:

Assuming you have installed the worker agent to a Python venv in /opt/deadline/worker, run:

/opt/deadline/worker/bin/install-deadline-worker --help

On Windows:

Run the following command in an administrator command-prompt:

install-deadline-worker --help

Configuration

See configuration

State

See state

Running

Setting up the worker host using the install-deadline-worker command (see "Setup worker host" above) installs an operating system service. On Linux, this is a systemd service and on Windows this is a Windows service.

The following commands demonstrate how to manually control the operating system service.

On Linux:

# Start the worker agent
systemctl start deadline-worker

# Stop the worker agent
systemctl stop deadline-worker

# Configure the worker agent to start on boot
systemctl enable deadline-worker

# Configure the worker agent to NOT start on boot
systemctl disable deadline-worker

On Windows:

Using an admin command-prompt:

REM start the service
sc.exe start DeadlineWorker

REM stop the service
sc.exe stop DeadlineWorker

Running Outside of an Operating System Service

NOTE: It is highly recommended to run the worker agent through an OS service in production environments. The OS service automatically handles:

Restarting the worker agent process if the agent process crashes.
Starting the worker agent when the host machine starts up.
Attempting graceful shutdown when the host machine is shutting down.

The worker agent can also be started outside of a service context if required. Run deadline-worker-agent --help to see a list of supported command line arguments.

NOTE: You must have an AWS region specified in order to run the worker agent from the command line. This can be configured through:

The AWS_DEFAULT_REGION environment variable.
The AWS Configuration File
- Configured manually, or through the command line.

Logging

See logging

Contributing

See CONTRIBUTING.md for information on reporting issues, requesting features, and developer information.

Security

See security issue notifications for more information.

Telemetry

See telemetry

License

This project is licensed under the Apache-2.0 License.

ddneilson/deadline-cloud-worker-agent