Cluster API Reference
Customer-hosted cloud features
Some features are only available on customer-hosted clouds. Reach out to support@anyscale.com for info.
Cluster CLI Legacy
anyscale cluster start
Legacy
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 formatcompute_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
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--name
that 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--name
that 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
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
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}")
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
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
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
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
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
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
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
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
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. | [optional] [default to null] |
data_metrics_dashboard_url | str | URL for the data Grafana dashboard. | [optional] [default to null] |
train_metrics_dashboard_url | str | URL for the train Grafana dashboard. | [optional] [default to null] |
serve_metrics_dashboard_url | str | URL for the serve Grafana dashboard. | [optional] [default to null] |
serve_deployment_metrics_dashboard_url | str | URL for the serve deployment Grafana dashboard. | [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] |