Skip to main content

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-id: Override project id used for this cluster. If not provided, the Anyscale project context will be used if it exists. Otherwise a default project will be used.
  • --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-id: Override project id used for this cluster. If not provided, the Anyscale project context will be used if it exists. Otherwise a default project will be used.
  • --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.

ParamTypeDescription
auth_tokenOptional StringAuthentication 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.

ParamTypeDescription
project_idStringID of the Project the Cluster belongs to
cluster_nameStringName of the Cluster
cluster_environment_build_idStringID of the Cluster Environment Build to start this Cluster with
cluster_compute_idOptional StringID of the Cluster Compute to start this Cluster with
cluster_compute_configOptional DictOne-off Cluster Compute that this Cluster will use, with same fields as ClusterComputeConfig
poll_rate_secondsOptional Integerseconds to wait when polling cluster operation status; defaults to 15
idle_timeout_minutesOptional IntegerIdle timeout (in minutes), after which the Cluster is terminated; Defaults to 120 minutes.
timeout_secondsOptional Integermaximum 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.

ParamTypeDescription
project_idStringID of the Project the Cluster belongs to
cluster_nameStringName of the Cluster
create_cluster_environmentCreateClusterEnvironmentCreateClusterEnvironment object
cluster_compute_idOptional StringCluster Compute to start this Cluster with
cluster_compute_configOptional DictOne-off Cluster Compute that this Cluster will use, with same fields as ClusterComputeConfig
poll_rate_secondsOptional Integerseconds to wait when polling operation status; defaults to 15
timeout_secondsOptional Integermaximum 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

NameTypeDescriptionNotes
cluster_idstrDefaults 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

NameTypeDescriptionNotes
create_clusterCreateCluster

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

NameTypeDescriptionNotes
cluster_idstrID 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

NameTypeDescriptionNotes
cluster_idstrID 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

NameTypeDescriptionNotes
clusters_queryClustersQuery

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

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to start.Defaults to null
start_cluster_optionsStartClusterOptions

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

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to terminate.Defaults to null
terminate_cluster_optionsTerminateClusterOptions

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

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to update.Defaults to null
update_clusterUpdateCluster

Returns ClusterResponse

Cluster Models Legacy

ClusterHeadNodeInfo Legacy

Details about the head node of a running Cluster.

NameTypeDescriptionNotes
urlstrURL for the head node of this Cluster.[default to null]
ip_addressstrIP 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.

NameTypeDescriptionNotes
resultsList[Cluster][default to null]
metadataListResponseMetadata[optional] [default to null]

ClusterManagementStackVersions Legacy

An enumeration.

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

ClusterOperation Legacy

Describes a long running Cluster operation that will eventually complete.

NameTypeDescriptionNotes
idstrID of this operation.[default to null]
completedboolBoolean indicating if this operation is completed.[default to null]
progressOperationProgressDetails about the progress of this operation at the time of the request. This will be absent for completed operations.[optional] [default to null]
resultOperationResultThe result of this operation after it has completed. This is always provided when the operation is complete.[optional] [default to null]
cluster_idstrID of the Cluster that is being updated.[default to null]
cluster_operation_typeClusterOperationTypeThe 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.

NameTypeDescriptionNotes
resultCluster[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.

NameTypeDescriptionNotes
webterminal_auth_urlstrURL to authenticate with the webterminal[optional] [default to null]
metrics_dashboard_urlstrURL for Grafana (metrics) dashboard.[optional] [default to null]
data_metrics_dashboard_urlstrURL for the data Grafana dashboard.[optional] [default to null]
train_metrics_dashboard_urlstrURL for the train Grafana dashboard.[optional] [default to null]
serve_metrics_dashboard_urlstrURL for the serve Grafana dashboard.[optional] [default to null]
serve_deployment_metrics_dashboard_urlstrURL for the serve deployment Grafana dashboard.[optional] [default to null]
persistent_metrics_urlstrURL for the persistent Grafana (metrics) dashboard in the non-running cluster state.[optional] [default to null]
connect_urlstrURL for Anyscale connect.[optional] [default to null]
jupyter_notebook_urlstrURL for Jupyter Lab.[optional] [default to null]
ray_dashboard_urlstrURL for Ray dashboard.[optional] [default to null]
service_proxy_urlstrURL for web services proxy (e.g. jupyter, tensorboard, etc).[optional] [default to null]
user_service_urlstrURL 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.

NameTypeDescriptionNotes
resultClusterOperation[default to null]

ClustersQuery Legacy

Query model used to filter Clusters.

NameTypeDescriptionNotes
project_idstrFilters Clusters belonging to a Project. If this field is absent, no filtering is done.[optional] [default to null]
nameTextQueryFilters Clusters by name. If this field is absent, no filtering is done.[optional] [default to null]
pagingPageQueryPagination information.[optional] [default to null]
state_filterList[ClusterState]Filter Sessions by Session State. If this field is an empty set, no filtering is done.[optional] [default to []]
archive_statusArchiveStatusThe archive status to filter by. Defaults to unarchived.[optional] [default to null]

CreateCluster Legacy

Model used to create a new Cluster.

NameTypeDescriptionNotes
namestrName of this Cluster.[default to null]
project_idstrProject that this Cluster belongs to. If none, this Cluster will use the default Project.[optional] [default to null]
cluster_environment_build_idstrCluster Environment Build that this Cluster is using.[default to null]
cluster_compute_idstrCluster Compute that this Cluster is using.[optional] [default to null]
cluster_compute_configCreateClusterComputeConfigOne-off cluster compute that this cluster is using.[optional] [default to null]
idle_timeout_minutesintIdle 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_trafficboolWhether public internet traffic can access Serve endpoints or if an authentication token is required.[optional] [default to false]
user_service_accessUserServiceAccessTypesWhether user service can be accessed by public internet traffic.[optional] [default to null]
user_service_tokenstrUser 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_idstrThis 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.

NameTypeDescriptionNotes
cluster_environment_build_idstrCluster Environment Build used to start Cluster.[optional] [default to null]
cluster_compute_idstrCluster Compute used to start the Cluster.[optional] [default to null]
allow_public_internet_trafficboolWhether 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.

NameTypeDescriptionNotes
take_snapshotboolDEPRECATED: 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.

NameTypeDescriptionNotes
namestrName of this Cluster.[optional] [default to null]
idle_timeout_minutesintIdle timeout in minutes.[optional] [default to null]
cluster_environment_build_idstrCluster 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_idstrCluster 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]