Job API Reference
These docs are for the new Anyscale design. If you started using Anyscale before April 2024, use Version 1.0.0 of the docs. If you're transitioning to Anyscale Preview, see the guide for how to migrate.
Customer-hosted cloud features
Some features are only available on customer-hosted clouds. Reach out to preview-help@anyscale.com for info.
Job Models
JobConfig
Configuration options for a job.
Fields
name
(str | None): Name of the job. Multiple jobs can be submitted with the same name.image_uri
(str | None): URI of an existing image. Exclusive withcontainerfile
.containerfile
(str | None): The file path to a containerfile that will be built into an image before running the workload. Exclusive withimage_uri
.compute_config
(ComputeConfig | Dict | str | None): The name of an existing registered compute config or an inlined ComputeConfig object.working_dir
(str | None): Directory that will be used as the working directory for the application. If a local directory is provided, it will be uploaded to cloud storage automatically. When running inside a workspace, this defaults to the current working directory ('.').excludes
(List[str] | None): A list of file path globs that will be excluded when uploading local files forworking_dir
.requirements
(str | List[str] | None): A list of pip requirements or a path to arequirements.txt
file for the workload. When running inside a workspace, this defaults to the workspace-tracked requirements.env_vars
(Dict[str, str] | None): A dictionary of environment variables that will be set for the workload.py_modules
(List[str] | None): A list of local directories or remote URIs that will be uploaded and added to the Python path.cloud
(str | None): The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).project
(str | None): The project for the workload. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).registry_login_secret
(str | None): A name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. This can only be used when 'image_uri' is specified and the image is not hosted on Anyscale.ray_version
(str | None): The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If not provided, the latest Ray version will be used.entrypoint
(str): Command that will be run to execute the job, e.g.,python main.py
.max_retries
(int): Maximum number of times the job will be retried before being marked failed. Defaults to1
.
Python Methods
def __init__(self, **fields) -> JobConfig
"""Construct a model with the provided field values set."""
def options(self, **fields) -> JobConfig
"""Return a copy of the model with the provided field values overwritten."""
def to_dict(self) -> Dict[str, Any]
"""Return a dictionary representation of the model."""
Examples
- YAML
- Python
name: my-job
entrypoint: python main.py
# An inline dictionary can also be provided.
compute_config: my-compute-config:1
# A containerfile path can also be provided.
image_uri: anyscale/image/my-image:1
from anyscale.job.models import JobConfig
config = JobConfig(
name="my-job",
entrypoint="python main.py",
max_retries=1,
# An inline `ComputeConfig` can also be provided.
compute_config="my-compute-config:1",
# A containerfile path can also be provided.
image_uri="anyscale/image/my-image:1",
)
JobState
Current state of a job.
Values
STARTING
: The job is being started and is not yet running.RUNNING
: The job is running. A job will have state RUNNING if a job run fails and there are remaining retries.FAILED
: The job did not finish running or the entrypoint returned an exit code other than 0 after retrying up to max_retries times.SUCCEEDED
: The job finished running and its entrypoint returned exit code 0.UNKNOWN
: The CLI/SDK received an unexpected state from the API server. In most cases, this means you need to update the CLI.
JobStatus
Current status of a job.
Fields
id
(str): Unique ID of the job (generated when the job is first submitted).name
(str): Name of the job. Multiple jobs can be submitted with the same name.state
(str | JobState): Current state of the job.config
(JobConfig): Configuration of the job.runs
(List[JobRunStatus]): List of job run states.
Python Methods
def to_dict(self) -> Dict[str, Any]
"""Return a dictionary representation of the model."""
Examples
- Python
- CLI
import anyscale
from anyscale.job.models import JobStatus
status: JobStatus = anyscale.job.status(name="my-job")
$ anyscale job status -n my-job
id: prodjob_3suiybn8r7dhz92yv63jqzm473
name: my-job
state: STARTING
JobRunStatus
Current status of an individual job run.
Fields
name
(str): Name of the job run.state
(str | JobRunState): Current state of the job run.
Python Methods
def to_dict(self) -> Dict[str, Any]
"""Return a dictionary representation of the model."""
Examples
- Python
- CLI
import anyscale
from anyscale.job.models import JobRunStatus
run_statuses: List[JobRunStatus] = anyscale.job.status(name="my-job").runs
$ anyscale job status -n my-job
id: prodjob_jurfnb5tebn76rtm1jiev1des7
name: my-job
state: SUCCEEDED
runs:
- name: raysubmit_igxeSmbQAtUY8qNf
state: FAILED
- name: raysubmit_bKuhY2s2SrS9TYSz
state: SUCCEEDED
JobRunState
Current state of an individual job run.
Values
STARTING
: The job run is being started and is not yet running.RUNNING
: The job run is running.FAILED
: The job run did not finish running or the entrypoint returned an exit code other than 0.SUCCEEDED
: The job run finished running and its entrypoint returned exit code 0.UNKNOWN
: The CLI/SDK received an unexpected state from the API server. In most cases, this means you need to update the CLI.
JobLogMode
Mode to use for getting job logs.
Values
HEAD
: Fetch logs from the start of the job's log.TAIL
: Fetch logs from the end of the job's log.
Job CLI
anyscale job submit
Usage
anyscale job submit [OPTIONS] [ENTRYPOINT]...
Submit a job.
The job config can be specified in one of the following ways:
-
Job config file can be specified as a single positional argument. E.g.
anyscale job submit config.yaml
. -
Job config can also be specified with command-line arguments. In this case, the entrypoint should be specified as the positional arguments starting with
--
. Other arguments can be specified with command-line flags. E.g.-
anyscale job submit -- python main.py
: submit a job with the entrypointpython main.py
. -
anyscale job submit --name my-job -- python main.py
: submit a job with the namemy-job
and the entrypointpython main.py
.
-
-
[Experimental] If you want to specify a config file and override some arguments with the commmand-line flags, use the
--config-file
flag. E.g.-
anyscale job submit --config-file config.yaml
: submit a job with the config inconfig.yaml
. -
anyscale job submit --config-file config.yaml -- python main.py
: submit a job with the config inconfig.yaml
and override the entrypoint withpython main.py
.
-
Either containerfile or image-uri should be used, specifying both will result in an error.
By default, this command submits the job asynchronously and exits. To wait for the job to complete, use the --wait
flag.
Options
-n/--name
: Name of the job.-w/--wait
: Block this CLI command and print logs until the job finishes.--config-file/-f
: Path to a YAML config file to use for this job. Command-line flags will overwrite values read from the file.--compute-config
: Named compute configuration to use for the job. This defaults to the compute configuration of the workspace.--image-uri
: Container image to use for this job. When running in a workspace, this defaults to the image of the workspace.--registry-login-secret
: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. This can only be used when 'image_uri' is specified and the image is not hosted on Anyscale.--containerfile
: Path to a containerfile to build the image to use for the job.--env
: Environment variables to set for the job. The format is 'key=value'. This argument can be specified multiple times. When the same key is also specified in the config file, the value from the command-line flag will overwrite the value from the config file.--working-dir
: Path to a local directory that will be the working directory for the job. The files in the directory will be automatically uploaded to cloud storage. When running in a workspace, this defaults to the current working directory.-e/--exclude
: File pattern to exclude when uploading local directories. This argument can be specified multiple times and the patterns will be appended to the 'excludes' list in the config file (if any).-r/--requirements
: Path to a requirements.txt file containing dependencies for the job. These will be installed on top of the image. When running in a workspace, this defaults to the workspace dependencies.--py-module
: Python modules to be available for import in the Ray workers. Each entry must be a path to a local directory.--cloud
: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).--project
: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).--ray-version
: The Ray version (X.Y.Z) to the image specified by --image-uri. This is only used when --image-uri is provided. If not provided, the latest Ray version will be used.--max-retries
: Maximum number of retries to attempt before failing the entire job.
anyscale job status
Usage
anyscale job status [OPTIONS]
Query the status of a job.
To specify the job by name, use the --name flag. To specify the job by id, use the --id flag. Either name or id should be used, specifying both will result in an error.
If job is specified by name and there are multiple jobs with the specified name, the most recently created job status will be returned.
Options
--id/--job-id
: Unique ID of the job.--name/-n
: Name of the job.--cloud
: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).--project
: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).--json/-j
: Output the status in a structured JSON format.--verbose/-v
: Include verbose details in the status.
anyscale job terminate
Usage
anyscale job terminate [OPTIONS]
Terminate a job.
To specify the job by name, use the --name flag. To specify the job by id, use the --id flag. Either name or id should be used, specifying both will result in an error.
If job is specified by name and there are multiple jobs with the specified name, the most recently created job status will be terminated.
Options
--id/--job-id
: Unique ID of the job.--name/-n
: Name of the job.--cloud
: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).--project
: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
anyscale job archive
Usage
anyscale job archive [OPTIONS]
Archive a job.
To specify the job by name, use the --name flag. To specify the job by id, use the --id flag. Either name or id should be used, specifying both will result in an error.
If job is specified by name and there are multiple jobs with the specified name, the most recently created job status will be archived.
Options
--id/--job-id
: Unique ID of the job.--name/-n
: Name of the job.--cloud
: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).--project
: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
anyscale job logs
Usage
anyscale job logs [OPTIONS]
Print the logs of a job.
By default from the latest job attempt.
Example usage:
anyscale job logs --id prodjob_123
anyscale job logs --id prodjob_123 -f
anyscale job logs -n my-job --all-attempts
Options
--id/--job-id
: Unique ID of the job.--name/-n
: Name of the job.--run
: Name of the job run.--cloud
: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).--project
: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).--head
: Used with --max-lines to getmax-lines
lines from the head of the log.--tail
: Used with --max-lines to getmax-lines
lines from the tail of the log.--max-lines
: Used with --head or --tail to limit the number of lines output.--follow/-f
: Whether to follow the log.--all-attempts
: DEPRECATED: Listing logs from all attempts no longer supported, instead list jobs by run name.
anyscale job wait
Usage
anyscale job wait [OPTIONS]
Wait for a job to enter a specific state (default: SUCCEEDED).
To specify the job by name, use the --name flag. To specify the job by id, use the --id flag.
If the job reaches the target state, the command will exit successfully.
If the job reaches a terminal state other than the target state, the command will exit with an error.
If the command reaches the timeout, the command will exit with an error but job execution will continue.
Options
--id/--job-id
: Unique ID of the job.--name/-n
: Name of the job.--cloud
: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).--project
: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).--state/-s
: The state to wait for this job to enter--timeout-s/--timeout/-t
: The timeout in seconds after which this command will exit.
anyscale job list
Usage
anyscale job list [OPTIONS]
Display information about existing jobs.
Options
--name/-n
: Filter by job name.--id/--job-id
: Filter by job id.--include-all-users
: Include jobs not created by current user.--include-archived
: List archived jobs as well as unarchived jobs.If not provided, defaults to listing only unarchived jobs.--max-items
: Max items to show in list.
Job SDK
anyscale.job.submit
Submit a job.
Returns the id of the submitted job.
Arguments
config
(JobConfig): The config options defining the job.
Returns: str
Examples
- Python
import anyscale
from anyscale.job.models import JobConfig
anyscale.job.submit(
JobConfig(
name="my-job",
entrypoint="python main.py",
working_dir=".",
),
)
anyscale.job.status
Get the status of a job.
Arguments
name
(str | None) = None: Name of the job.id
(str | None) = None: Unique ID of the jobcloud
(str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).project
(str | None) = None: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
Returns: JobStatus
Examples
- Python
import anyscale
from anyscale.job.models import JobStatus
status: JobStatus = anyscale.job.status(name="my-job")
anyscale.job.terminate
Terminate a job.
This command is asynchronous, so it always returns immediately.
Returns the id of the terminated job.
Arguments
name
(str | None) = None: Name of the job.id
(str | None) = None: Unique ID of the jobcloud
(str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).project
(str | None) = None: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
Returns: str
Examples
- Python
import anyscale
anyscale.job.terminate(name="my-job")
anyscale.job.archive
Archive a job.
This command is asynchronous, so it always returns immediately.
Returns the id of the archived job.
Arguments
name
(str | None) = None: Name of the job.id
(str | None) = None: Unique ID of the jobcloud
(str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).project
(str | None) = None: Named project to use for the job . If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
Returns: str
Examples
- Python
import anyscale
anyscale.job.archive(name="my-job")
anyscale.job.get_logs
Query the jobs for a job run.
Arguments
id
(str | None) = None: Unique ID of the jobname
(str | None) = None: Name of the jobcloud
(str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).project
(str | None) = None: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).run
(str | None) = None: The name of the run to query. Names can be found in the JobStatus. If not provided, the last job run will be used.mode
(str | JobLogMode) = TAIL: The mode of log fetching to be used. Supported modes can be found in JobLogMode. If not provided, JobLogMode.TAIL will be used.max_lines
(int | None) = None: The number of log lines to be fetched. If not provided, the complete log will be fetched.
Returns: str
Examples
- Python
import anyscale
anyscale.job.get_logs(name="my-job", run="job-run-name")
anyscale.job.wait
"Wait for a job to enter a specific state.
Arguments
name
(str | None) = None: Name of the job.id
(str | None) = None: Unique ID of the jobcloud
(str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).project
(str | None) = None: Named project to use for the job. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).state
(JobState | str) = SUCCEEDED: Target state of the jobtimeout_s
(float) = 1800: Number of seconds to wait before timing out, this timeout will not affect job execution
Examples
- Python
import anyscale
anyscale.job.wait(name="my-job", timeout_s=180)