Cluster API Reference

Customer-hosted cloud features

note

Some features are only available on customer-hosted clouds. Reach out to support@anyscale.com for info.

Cluster CLI Legacy

anyscale cluster start Legacy

warning

This command is deprecated. Upgrade to anyscale workspace_v2 start.

Usage

anyscale cluster start [OPTIONS]

Start or update and restart a cluster on Anyscale.

Options

• --name/-n: Name of new or existing cluster to start or update.
• --env: Set the Anyscale app config to use for the cluster. This is a cluster environment name optionally followed by a colon and a build version number. Eg: my_cluster_env:1
• --docker: Custom docker image name.
• --python-version: Python version for the custom docker image.
• --ray-version: Ray version for the custom docker image.
• --compute: Name of compute config that is already registered with Anyscale. To use specific version, use the format compute_name:version.
• --compute-file: The YAML file of the compute config to launch this cluster with. An example can be found at https://docs.anyscale.com/configure/compute-configs/overview.
• --cluster-id/--id: Id of existing cluster to restart. This argument can be used to interact with any cluster you have access to in any project.
• --project: Override project name used for this cluster. If not provided, the Anyscale project context will be used if it exists. Otherwise a default project will be used.
• --cloud-name: Name of cloud to create a default compute config with. If a default cloud needs to be used and this is not provided, the organization default cloud will be used.
• --idle-timeout: DEPRECATED: Please specify the idle_termination_minutes field in the compute config. Idle timeout (in minutes), after which the cluster is stopped. Idle time is defined as the time during which a cluster is not running a user command and does not have an attached driver. Time spent running Jupyter commands, or commands run through ssh, is still considered 'idle'. -1 means no timeout. Default: 120 minutes
• --user-service-access: Whether user service (eg: serve deployment) can be accessed by public internet traffic. If public, a user service endpoint can be queried from the public internet with the provided authentication token. If private, the user service endpoint can only be queried from within the same Anyscale cloud and will not require an authentication token.

anyscale cluster terminate Legacy

warning

This command is deprecated. Upgrade to anyscale workspace_v2 terminate.

Usage

anyscale cluster terminate [OPTIONS]

Terminate a cluster on Anyscale.

Options

• --name/-n: Name of existing cluster to terminate.
• --cluster-id/--id: Id of existing cluster to termiante. This argument can be used to interact with any cluster you have access to in any project.
• --project: Override project name used for this cluster. If not provided, the Anyscale project context will be used if it exists. Otherwise a default project will be used.
• --cloud-id: Use cloud ID to disambiguate only when selecting a cluster to terminate with --namethat doesn't belong to any project. This requires cloud isolation to be enabled.
• --cloud: Use cloud to disambiguate only when selecting a cluster to terminate with --namethat doesn't belong to any project. This requires cloud isolation to be enabled.

Cluster SDK Legacy

The AnyscaleSDK class must be constructed in order to make calls to the SDK. This class allows you to create an authenticated client in which to use the SDK.

Param	Type	Description
auth_token	Optional String	Authentication token used to verify you have permissions to access Anyscale. If not provided, permissions default to the credentials set for your current user. Credentials can be set by following the instructions on this page: https://console.anyscale.com/credentials

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK()

launch_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Starts a Cluster in the specified Project.

If a Cluster with the specified name already exists, we will update that Cluster. Otherwise, a new Cluster will be created.

Returns the started Cluster object.

Raises an Exception if starting Cluster fails or times out.

Param	Type	Description
project_id	String	ID of the Project the Cluster belongs to
cluster_name	String	Name of the Cluster
cluster_environment_build_id	String	ID of the Cluster Environment Build to start this Cluster with
cluster_compute_id	Optional String	ID of the Cluster Compute to start this Cluster with
cluster_compute_config	Optional Dict	One-off Cluster Compute that this Cluster will use, with same fields as ClusterComputeConfig
poll_rate_seconds	Optional Integer	seconds to wait when polling cluster operation status; defaults to 15
idle_timeout_minutes	Optional Integer	Idle timeout (in minutes), after which the Cluster is terminated; Defaults to 120 minutes.
timeout_seconds	Optional Integer	maximum number of seconds to wait for cluster operation to complete before timing out; defaults to no timeout

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

cluster = sdk.launch_cluster(
    project_id="project_id",
    cluster_name="my-cluster",
    cluster_environment_build_id="cluster_environment_build_id",
    cluster_compute_id="cluster_compute_id")

print(f"Cluster started successfully: {cluster}")

launch_cluster_with_new_cluster_environment Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Builds a new Cluster Environment, then starts a Cluster in the specified Project with the new build.

If a Cluster with the specified name already exists, we will update that Cluster. Otherwise, a new Cluster will be created.

Returns the started Cluster object.

Raises an Exception if building Cluster Environment fails or starting the Cluster fails.

Param	Type	Description
project_id	String	ID of the Project the Cluster belongs to
cluster_name	String	Name of the Cluster
create_cluster_environment	CreateClusterEnvironment	CreateClusterEnvironment object
cluster_compute_id	Optional String	Cluster Compute to start this Cluster with
cluster_compute_config	Optional Dict	One-off Cluster Compute that this Cluster will use, with same fields as ClusterComputeConfig
poll_rate_seconds	Optional Integer	seconds to wait when polling operation status; defaults to 15
timeout_seconds	Optional Integer	maximum number of seconds to wait for operations to complete before timing out; defaults to no timeout

Example

from anyscale import AnyscaleSDK
from anyscale.sdk.anyscale_client.models.create_cluster_environment import (
    CreateClusterEnvironment,
)

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

create_cluster_environment = CreateClusterEnvironment(
    name="my-cluster-environment",
    config_json={"base_image": "anyscale/ray:1.4.1-py37"}
)

cluster = sdk.launch_cluster_with_new_cluster_environment(
    project_id="project_id",
    cluster_name="my-cluster",
    create_cluster_environment=create_cluster_environment,
    cluster_compute_id="cluster_compute_id",
)

print(f"Cluster started successfully: {cluster}")

info

The OpenAPI schemas for types below can be found at the Anyscale OpenAPI Documentation

All of the following functions are synchronous by default. To make an asynchronous HTTP request, please pass async_req=True. The return value for the asynchronous calls is a thread.

thread = api.create_cloud(create_cloud, async_req=True)
result = thread.get()

archive_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Archives the cluster. It is a no-op if the cluster is already archived.

Parameters

Name	Type	Description	Notes
cluster_id	str		Defaults to null

Returns void (empty response body)

create_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Creates a Cluster.

Parameters

Name	Type	Description	Notes
create_cluster	CreateCluster

Returns ClusterResponse

delete_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Deletes a Cluster.

Parameters

Name	Type	Description	Notes
cluster_id	str	ID of the Cluster to delete.	Defaults to null

Returns void (empty response body)

get_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Retrieves a Cluster.

Parameters

Name	Type	Description	Notes
cluster_id	str	ID of the Cluster to retreive.	Defaults to null

Returns ClusterResponse

search_clusters Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Searches for all Clusters the user has access to that satisfies the query.

Parameters

Name	Type	Description	Notes
clusters_query	ClustersQuery

Returns ClusterListResponse

start_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Initializes workflow to transition the Cluster into the Running state. This is a long running operation. Clients will need to poll the operation's status to determine completion. The options parameter is DEPRECATED.

Parameters

Name	Type	Description	Notes
cluster_id	str	ID of the Cluster to start.	Defaults to null
start_cluster_options	StartClusterOptions

Returns ClusteroperationResponse

terminate_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Initializes workflow to transition the Cluster into the Terminated state. This is a long running operation. Clients will need to poll the operation's status to determine completion.

Parameters

Name	Type	Description	Notes
cluster_id	str	ID of the Cluster to terminate.	Defaults to null
terminate_cluster_options	TerminateClusterOptions

Returns ClusteroperationResponse

update_cluster Legacy

Upgrade recommended

Cluster commands are deprecated. Use workspaces, jobs, or services APIs based on your specific needs.

Updates a Cluster.

Parameters

Name	Type	Description	Notes
cluster_id	str	ID of the Cluster to update.	Defaults to null
update_cluster	UpdateCluster

Returns ClusterResponse

Cluster Models Legacy

ClusterHeadNodeInfo Legacy

Details about the head node of a running Cluster.

Name	Type	Description	Notes
url	str	URL for the head node of this Cluster.	[default to null]
ip_address	str	IP address for the head node of this Cluster.	[default to null]

ClusterListResponse Legacy

A list response form the API. Contains a field "results" which has the contents of the response.

Name	Type	Description	Notes
results	List[Cluster]		[default to null]
metadata	ListResponseMetadata		[optional] [default to null]

ClusterManagementStackVersions Legacy

An enumeration.

Possible Values: ['v1', 'v2']

ClusterOperation Legacy

Describes a long running Cluster operation that will eventually complete.

Name	Type	Description	Notes
id	str	ID of this operation.	[default to null]
completed	bool	Boolean indicating if this operation is completed.	[default to null]
progress	OperationProgress	Details about the progress of this operation at the time of the request. This will be absent for completed operations.	[optional] [default to null]
result	OperationResult	The result of this operation after it has completed. This is always provided when the operation is complete.	[optional] [default to null]
cluster_id	str	ID of the Cluster that is being updated.	[default to null]
cluster_operation_type	ClusterOperationType	The variety of operation being performed: start sets the Cluster's goal state to Running, terminate sets the Cluster's goal state to Terminated	[default to null]

ClusterResponse Legacy

A response from the API. Contains a field "result" which has the contents of the response.

Name	Type	Description	Notes
result	Cluster		[default to null]

ClusterServicesUrls Legacy

URLs for additional services running in the Cluster. (ex/ Jupyter, Ray Dashboard). This fields can only be populated after the Cluster has finished starting. An absent field indicates the service is not available.

Name	Type	Description	Notes
webterminal_auth_url	str	URL to authenticate with the webterminal	[optional] [default to null]
metrics_dashboard_url	str	URL for Grafana (metrics) dashboard in the running cluster state.	[optional] [default to null]
persistent_metrics_url	str	URL for the persistent Grafana (metrics) dashboard in the non-running cluster state.	[optional] [default to null]
connect_url	str	URL for Anyscale connect.	[optional] [default to null]
jupyter_notebook_url	str	URL for Jupyter Lab.	[optional] [default to null]
ray_dashboard_url	str	URL for Ray dashboard.	[optional] [default to null]
service_proxy_url	str	URL for web services proxy (e.g. jupyter, tensorboard, etc).	[optional] [default to null]
user_service_url	str	URL to access user services (e.g. Ray Serve)	[optional] [default to null]

ClusterState Legacy

Possible States for a Cluster.

Possible Values: ['Terminated', 'StartingUp', 'StartupErrored', 'Running', 'Updating', 'UpdatingErrored', 'Terminating', 'AwaitingStartup', 'TerminatingErrored', 'Unknown']

ClusterStatus Legacy

An enumeration.

Possible Values: ['STARTING', 'RUNNING', 'RECOVERING', 'RESTARTING', 'TERMINATING', 'TERMINATED']

ClusterStatusDetails Legacy

ClusterStatusDetails is a more granular status than ClusterStatus.

Possible Values: ['LAUNCHING_NODES', 'CONFIGURING_HEAD_NODE']

ClusteroperationResponse Legacy

A response from the API. Contains a field "result" which has the contents of the response.

Name	Type	Description	Notes
result	ClusterOperation		[default to null]

ClustersQuery Legacy

Query model used to filter Clusters.

Name	Type	Description	Notes
project_id	str	Filters Clusters belonging to a Project. If this field is absent, no filtering is done.	[optional] [default to null]
name	TextQuery	Filters Clusters by name. If this field is absent, no filtering is done.	[optional] [default to null]
paging	PageQuery	Pagination information.	[optional] [default to null]
state_filter	List[ClusterState]	Filter Sessions by Session State. If this field is an empty set, no filtering is done.	[optional] [default to []]
archive_status	ArchiveStatus	The archive status to filter by. Defaults to unarchived.	[optional] [default to null]

CreateCluster Legacy

Model used to create a new Cluster.

Name	Type	Description	Notes
name	str	Name of this Cluster.	[default to null]
project_id	str	Project that this Cluster belongs to. If none, this Cluster will use the default Project.	[optional] [default to null]
cluster_environment_build_id	str	Cluster Environment Build that this Cluster is using.	[default to null]
cluster_compute_id	str	Cluster Compute that this Cluster is using.	[optional] [default to null]
cluster_compute_config	CreateClusterComputeConfig	One-off cluster compute that this cluster is using.	[optional] [default to null]
idle_timeout_minutes	int	Idle timeout (in minutes), after which the Cluster is terminated. Idle time is defined as the time during which a Cluster is not running a user command (through 'anyscale exec' or the Web UI), and does not have an attached driver. Time spent running Jupyter commands, or commands run through ssh, is still considered 'idle'.	[optional] [default to null]
allow_public_internet_traffic	bool	Whether public internet traffic can access Serve endpoints or if an authentication token is required.	[optional] [default to false]
user_service_access	UserServiceAccessTypes	Whether user service can be accessed by public internet traffic.	[optional] [default to null]
user_service_token	str	User service token that is used to authenticate access to public user services. This must be a valid 32 byte URL safe string and can be generated by calling `secrets.token_urlsafe(32))`. This is ignored if the user service has private access. If not specified for a public user service, a token is autogenerated.	[optional] [default to null]
ha_job_id	str	This is used internally by Anyscale to associate clusters to a job. It is set automatically and should not be used directly.	[optional] [default to null]

StartClusterOptions Legacy

Options to set when starting a Cluster.

Name	Type	Description	Notes
cluster_environment_build_id	str	Cluster Environment Build used to start Cluster.	[optional] [default to null]
cluster_compute_id	str	Cluster Compute used to start the Cluster.	[optional] [default to null]
allow_public_internet_traffic	bool	Whether public internet traffic can access Serve endpoints or if an authentication token is required. Will not update current value if not provided.	[optional] [default to null]

TerminateClusterOptions Legacy

Options to set when terminating a Cluster.

Name	Type	Description	Notes
take_snapshot	bool	DEPRECATED: Snapshotting is no longer supported.For reproducible environments between clusters, please use Cluster Environments or Runtime Environments.	[optional] [default to false]

UpdateCluster Legacy

Model used to update a Cluster. A field will not be updated if its value is absent.

Name	Type	Description	Notes
name	str	Name of this Cluster.	[optional] [default to null]
idle_timeout_minutes	int	Idle timeout in minutes.	[optional] [default to null]
cluster_environment_build_id	str	Cluster Environment Build that this Cluster is using. This property may only be changed if the Cluster is in the Terminated state.Use the Start Cluster operation if you wish to change this for a non-Terminated Cluster.	[optional] [default to null]
cluster_compute_id	str	Cluster Compute that this Cluster is using. This property may only be changed if the Cluster is in the Terminated state. Use the Start Cluster operation if you wish to change this for a non-Terminated Cluster.	[optional] [default to null]