Cluster YAML Configuration Options
Contents
Cluster YAML Configuration Options#
The cluster configuration is defined within a YAML file that will be used by the Cluster Launcher to launch the head node, and by the Autoscaler to launch worker nodes. Once the cluster configuration is defined, you will need to use the Ray CLI to perform any operations such as starting and stopping the cluster.
Syntax#
cluster_name: str max_workers: int upscaling_speed: float idle_timeout_minutes: int docker: docker provider: provider auth: auth available_node_types: node_types head_node_type: str file_mounts: file_mounts cluster_synced_files: - str rsync_exclude: - str rsync_filter: - str initialization_commands: - str setup_commands: - str head_setup_commands: - str worker_setup_commands: - str head_start_ray_commands: - str worker_start_ray_commands: - str
Custom types#
Docker#
image: str head_image: str worker_image: str container_name: str pull_before_run: bool run_options: - str head_run_options: - str worker_run_options: - str disable_automatic_runtime_detection: bool disable_shm_size_detection: bool
Auth#
ssh_user: str ssh_private_key: str
ssh_user: str ssh_private_key: str ssh_public_key: str
ssh_user: str ssh_private_key: str
Provider#
type: str region: str availability_zone: str cache_stopped_nodes: bool security_group: Security Group
type: str location: str resource_group: str subscription_id: str cache_stopped_nodes: bool
type: str region: str availability_zone: str project_id: str cache_stopped_nodes: bool
Security Group#
GroupName: str IpPermissions: - IpPermission
Node types#
The available_nodes_types
object’s keys represent the names of the different node types.
Deleting a node type from available_node_types
and updating with ray up will cause the autoscaler to scale down all nodes of that type.
In particular, changing the key of a node type object will
result in removal of nodes corresponding to the old key; nodes with the new key name will then be
created according to cluster configuration and Ray resource demands.
<node_type_1_name>: node_config: Node config resources: Resources min_workers: int max_workers: int worker_setup_commands: - str docker: Node Docker <node_type_2_name>: ... ...
Node config#
Cloud-specific configuration for nodes of a given node type.
Modifying the node_config
and updating with ray up will cause the autoscaler to scale down all existing nodes of the node type;
nodes with the newly applied node_config
will then be created according to cluster configuration and Ray resource demands.
A YAML object which conforms to the EC2 create_instances
API in the AWS docs.
A YAML object as defined in the deployment template whose resources are defined in the Azure docs.
A YAML object as defined in the GCP docs.
Node Docker#
worker_image: str pull_before_run: bool worker_run_options: - str disable_automatic_runtime_detection: bool disable_shm_size_detection: bool
Resources#
CPU: int GPU: int object_store_memory: int memory: int <custom_resource1>: int <custom_resource2>: int ...
File mounts#
<path1_on_remote_machine>: str # Path 1 on local machine
<path2_on_remote_machine>: str # Path 2 on local machine
...
Properties and Definitions#
cluster_name
#
The name of the cluster. This is the namespace of the cluster.
Required: Yes
Importance: High
Type: String
Default: “default”
Pattern:
[a-zA-Z0-9_]+
max_workers
#
The maximum number of workers the cluster will have at any given time.
Required: No
Importance: High
Type: Integer
Default:
2
Minimum:
0
Maximum: Unbounded
upscaling_speed
#
The number of nodes allowed to be pending as a multiple of the current number of nodes. For example, if set to 1.0, the cluster can grow in size by at most 100% at any time, so if the cluster currently has 20 nodes, at most 20 pending launches are allowed. Note that although the autoscaler will scale down to min_workers
(which could be 0), it will always scale up to 5 nodes at a minimum when scaling up.
Required: No
Importance: Medium
Type: Float
Default:
1.0
Minimum:
0.0
Maximum: Unbounded
idle_timeout_minutes
#
The number of minutes that need to pass before an idle worker node is removed by the Autoscaler.
Required: No
Importance: Medium
Type: Integer
Default:
5
Minimum:
0
Maximum: Unbounded
docker
#
Configure Ray to run in Docker containers.
Required: No
Importance: High
Type: Docker
Default:
{}
In rare cases when Docker is not available on the system by default (e.g., bad AMI), add the following commands to initialization_commands to install it.
initialization_commands:
- curl -fsSL https://get.docker.com -o get-docker.sh
- sudo sh get-docker.sh
- sudo usermod -aG docker $USER
- sudo systemctl restart docker -f
provider
#
The cloud provider-specific configuration properties.
Required: Yes
Importance: High
Type: Provider
auth
#
Authentication credentials that Ray will use to launch nodes.
Required: Yes
Importance: High
Type: Auth
available_node_types
#
Tells the autoscaler the allowed node types and the resources they provide. Each node type is identified by a user-specified key.
Required: No
Importance: High
Type: Node types
Default:
available_node_types:
ray.head.default:
node_config:
InstanceType: m5.large
BlockDeviceMappings:
- DeviceName: /dev/sda1
Ebs:
VolumeSize: 140
resources: {"CPU": 2}
ray.worker.default:
node_config:
InstanceType: m5.large
InstanceMarketOptions:
MarketType: spot
resources: {"CPU": 2}
min_workers: 0
head_node_type
#
The key for one of the node types in available_node_types. This node type will be used to launch the head node.
If the field head_node_type
is changed and an update is executed with ray up, the currently running head node will
be considered outdated. The user will receive a prompt asking to confirm scale-down of the outdated head node, and the cluster will restart with a new
head node. Changing the node_config of the node_type with key head_node_type
will also result in cluster restart after a user prompt.
Required: Yes
Importance: High
Type: String
Pattern:
[a-zA-Z0-9_]+
file_mounts
#
The files or directories to copy to the head and worker nodes.
Required: No
Importance: High
Type: File mounts
Default:
[]
cluster_synced_files
#
A list of paths to the files or directories to copy from the head node to the worker nodes. The same path on the head node will be copied to the worker node. This behavior is a subset of the file_mounts behavior, so in the vast majority of cases one should just use file_mounts.
Required: No
Importance: Low
Type: List of String
Default:
[]
rsync_exclude
#
A list of patterns for files to exclude when running rsync up
or rsync down
. The filter is applied on the source directory only.
Example for a pattern in the list: **/.git/**
.
Required: No
Importance: Low
Type: List of String
Default:
[]
rsync_filter
#
A list of patterns for files to exclude when running rsync up
or rsync down
. The filter is applied on the source directory and recursively through all subdirectories.
Example for a pattern in the list: .gitignore
.
Required: No
Importance: Low
Type: List of String
Default:
[]
initialization_commands
#
A list of commands that will be run before the setup commands. If Docker is enabled, these commands will run outside the container and before Docker is setup.
Required: No
Importance: Medium
Type: List of String
Default:
[]
setup_commands
#
A list of commands to run to set up nodes. These commands will always run on the head and worker nodes and will be merged with head setup commands for head and with worker setup commands for workers.
Required: No
Importance: Medium
Type: List of String
Default:
# Default setup_commands:
setup_commands:
- echo 'export PATH="$HOME/anaconda3/envs/tensorflow_p36/bin:$PATH"' >> ~/.bashrc
- pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp36-cp36m-manylinux2014_x86_64.whl
Setup commands should ideally be idempotent (i.e., can be run multiple times without changing the result); this allows Ray to safely update nodes after they have been created. You can usually make commands idempotent with small modifications, e.g.
git clone foo
can be rewritten astest -e foo || git clone foo
which checks if the repo is already cloned first.Setup commands are run sequentially but separately. For example, if you are using anaconda, you need to run
conda activate env && pip install -U ray
because splitting the command into two setup commands will not work.Ideally, you should avoid using setup_commands by creating a docker image with all the dependencies preinstalled to minimize startup time.
Tip: if you also want to run apt-get commands during setup add the following list of commands:
setup_commands: - sudo pkill -9 apt-get || true - sudo pkill -9 dpkg || true - sudo dpkg --configure -a
head_setup_commands
#
A list of commands to run to set up the head node. These commands will be merged with the general setup commands.
Required: No
Importance: Low
Type: List of String
Default:
[]
worker_setup_commands
#
A list of commands to run to set up the worker nodes. These commands will be merged with the general setup commands.
Required: No
Importance: Low
Type: List of String
Default:
[]
head_start_ray_commands
#
Commands to start ray on the head node. You don’t need to change this.
Required: No
Importance: Low
Type: List of String
Default:
head_start_ray_commands:
- ray stop
- ulimit -n 65536; ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml
worker_start_ray_commands
#
Command to start ray on worker nodes. You don’t need to change this.
Required: No
Importance: Low
Type: List of String
Default:
worker_start_ray_commands:
- ray stop
- ulimit -n 65536; ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076
docker.image
#
The default Docker image to pull in the head and worker nodes. This can be overridden by the head_image and worker_image fields. If neither image
nor (head_image and worker_image) are specified, Ray will not use Docker.
Required: Yes (If Docker is in use.)
Importance: High
Type: String
The Ray project provides Docker images on DockerHub. The repository includes following images:
rayproject/ray-ml:latest-gpu
: CUDA support, includes ML dependencies.rayproject/ray:latest-gpu
: CUDA support, no ML dependencies.rayproject/ray-ml:latest
: No CUDA support, includes ML dependencies.rayproject/ray:latest
: No CUDA support, no ML dependencies.
docker.head_image
#
Docker image for the head node to override the default docker image.
Required: No
Importance: Low
Type: String
docker.worker_image
#
Docker image for the worker nodes to override the default docker image.
Required: No
Importance: Low
Type: String
docker.container_name
#
The name to use when starting the Docker container.
Required: Yes (If Docker is in use.)
Importance: Low
Type: String
Default: ray_container
docker.pull_before_run
#
If enabled, the latest version of image will be pulled when starting Docker. If disabled, docker run
will only pull the image if no cached version is present.
Required: No
Importance: Medium
Type: Boolean
Default:
True
docker.run_options
#
The extra options to pass to docker run
.
Required: No
Importance: Medium
Type: List of String
Default:
[]
docker.head_run_options
#
The extra options to pass to docker run
for head node only.
Required: No
Importance: Low
Type: List of String
Default:
[]
docker.worker_run_options
#
The extra options to pass to docker run
for worker nodes only.
Required: No
Importance: Low
Type: List of String
Default:
[]
docker.disable_automatic_runtime_detection
#
If enabled, Ray will not try to use the NVIDIA Container Runtime if GPUs are present.
Required: No
Importance: Low
Type: Boolean
Default:
False
docker.disable_shm_size_detection
#
If enabled, Ray will not automatically specify the size /dev/shm
for the started container and the runtime’s default value (64MiB for Docker) will be used.
If --shm-size=<>
is manually added to run_options
, this is automatically set to True
, meaning that Ray will defer to the user-provided value.
Required: No
Importance: Low
Type: Boolean
Default:
False
auth.ssh_user
#
The user that Ray will authenticate with when launching new nodes.
Required: Yes
Importance: High
Type: String
auth.ssh_private_key
#
The path to an existing private key for Ray to use. If not configured, Ray will create a new private keypair (default behavior). If configured, the key must be added to the project-wide metadata and KeyName
has to be defined in the node configuration.
Required: No
Importance: Low
Type: String
The path to an existing private key for Ray to use.
Required: Yes
Importance: High
Type: String
You may use ssh-keygen -t rsa -b 4096
to generate a new ssh keypair.
The path to an existing private key for Ray to use. If not configured, Ray will create a new private keypair (default behavior). If configured, the key must be added to the project-wide metadata and KeyName
has to be defined in the node configuration.
Required: No
Importance: Low
Type: String
auth.ssh_public_key
#
Not available.
The path to an existing public key for Ray to use.
Required: Yes
Importance: High
Type: String
Not available.
provider.type
#
The cloud service provider. For AWS, this must be set to aws
.
Required: Yes
Importance: High
Type: String
The cloud service provider. For Azure, this must be set to azure
.
Required: Yes
Importance: High
Type: String
The cloud service provider. For GCP, this must be set to gcp
.
Required: Yes
Importance: High
Type: String
provider.region
#
The region to use for deployment of the Ray cluster.
Required: Yes
Importance: High
Type: String
Default: us-west-2
Not available.
The region to use for deployment of the Ray cluster.
Required: Yes
Importance: High
Type: String
Default: us-west1
provider.availability_zone
#
A string specifying a comma-separated list of availability zone(s) that nodes may be launched in. Nodes will be launched in the first listed availability zone and will be tried in the following availability zones if launching fails.
Required: No
Importance: Low
Type: String
Default: us-west-2a,us-west-2b
Not available.
A string specifying a comma-separated list of availability zone(s) that nodes may be launched in.
Required: No
Importance: Low
Type: String
Default: us-west1-a
provider.location
#
Not available.
The location to use for deployment of the Ray cluster.
Required: Yes
Importance: High
Type: String
Default: westus2
Not available.
provider.resource_group
#
Not available.
The resource group to use for deployment of the Ray cluster.
Required: Yes
Importance: High
Type: String
Default: ray-cluster
Not available.
provider.subscription_id
#
Not available.
The subscription ID to use for deployment of the Ray cluster. If not specified, Ray will use the default from the Azure CLI.
Required: No
Importance: High
Type: String
Default:
""
Not available.
provider.project_id
#
Not available.
Not available.
The globally unique project ID to use for deployment of the Ray cluster.
Required: Yes
Importance: Low
Type: String
Default:
null
provider.cache_stopped_nodes
#
If enabled, nodes will be stopped when the cluster scales down. If disabled, nodes will be terminated instead. Stopped nodes launch faster than terminated nodes.
Required: No
Importance: Low
Type: Boolean
Default:
True
provider.security_group
#
A security group that can be used to specify custom inbound rules.
Required: No
Importance: Medium
Type: Security Group
Not available.
Not available.
security_group.GroupName
#
The name of the security group. This name must be unique within the VPC.
Required: No
Importance: Low
Type: String
Default:
"ray-autoscaler-{cluster-name}"
security_group.IpPermissions
#
The inbound rules associated with the security group.
Required: No
Importance: Medium
Type: IpPermission
available_node_types.<node_type_name>.node_type.node_config
#
The configuration to be used to launch the nodes on the cloud service provider. Among other things, this will specify the instance type to be launched.
Required: Yes
Importance: High
Type: Node config
available_node_types.<node_type_name>.node_type.resources
#
The resources that a node type provides, which enables the autoscaler to automatically select the right type of nodes to launch given the resource demands of the application. The resources specified will be automatically passed to the ray start
command for the node via an environment variable. If not provided, Autoscaler can automatically detect them only for AWS/Kubernetes cloud providers. For more information, see also the resource demand scheduler
Required: Yes (except for AWS/K8s)
Importance: High
Type: Resources
Default:
{}
In some cases, adding special nodes without any resources may be desirable. Such nodes can be used as a driver which connects to the cluster to launch jobs. In order to manually add a node to an autoscaled cluster, the ray-cluster-name tag should be set and ray-node-type tag should be set to unmanaged. Unmanaged nodes can be created by setting the resources to {}
and the maximum workers to 0. The Autoscaler will not attempt to start, stop, or update unmanaged nodes. The user is responsible for properly setting up and cleaning up unmanaged nodes.
available_node_types.<node_type_name>.node_type.min_workers
#
The minimum number of workers to maintain for this node type regardless of utilization.
Required: No
Importance: High
Type: Integer
Default:
0
Minimum:
0
Maximum: Unbounded
available_node_types.<node_type_name>.node_type.max_workers
#
The maximum number of workers to have in the cluster for this node type regardless of utilization. This takes precedence over minimum workers. By default, the number of workers of a node type is unbounded, constrained only by the cluster-wide max_workers. (Prior to Ray 1.3.0, the default value for this field was 0.)
Note, for the nodes of type head_node_type
the default number of max workers is 0.
Required: No
Importance: High
Type: Integer
Default: cluster-wide max_workers
Minimum:
0
Maximum: cluster-wide max_workers
available_node_types.<node_type_name>.node_type.worker_setup_commands
#
A list of commands to run to set up worker nodes of this type. These commands will replace the general worker setup commands for the node.
Required: No
Importance: low
Type: List of String
Default:
[]
available_node_types.<node_type_name>.node_type.resources.CPU
#
The number of CPUs made available by this node. If not configured, Autoscaler can automatically detect them only for AWS/Kubernetes cloud providers.
Required: Yes (except for AWS/K8s)
Importance: High
Type: Integer
The number of CPUs made available by this node.
Required: Yes
Importance: High
Type: Integer
The number of CPUs made available by this node.
Required: No
Importance: High
Type: Integer
available_node_types.<node_type_name>.node_type.resources.GPU
#
The number of GPUs made available by this node. If not configured, Autoscaler can automatically detect them only for AWS/Kubernetes cloud providers.
Required: No
Importance: Low
Type: Integer
The number of GPUs made available by this node.
Required: No
Importance: High
Type: Integer
The number of GPUs made available by this node.
Required: No
Importance: High
Type: Integer
available_node_types.<node_type_name>.node_type.resources.memory
#
The memory in bytes allocated for python worker heap memory on the node. If not configured, Autoscaler will automatically detect the amount of RAM on the node for AWS/Kubernetes and allocate 70% of it for the heap.
Required: No
Importance: Low
Type: Integer
The memory in bytes allocated for python worker heap memory on the node.
Required: No
Importance: High
Type: Integer
The memory in bytes allocated for python worker heap memory on the node.
Required: No
Importance: High
Type: Integer
available_node_types.<node_type_name>.node_type.resources.object-store-memory
#
The memory in bytes allocated for the object store on the node. If not configured, Autoscaler will automatically detect the amount of RAM on the node for AWS/Kubernetes and allocate 30% of it for the object store.
Required: No
Importance: Low
Type: Integer
The memory in bytes allocated for the object store on the node.
Required: No
Importance: High
Type: Integer
The memory in bytes allocated for the object store on the node.
Required: No
Importance: High
Type: Integer
available_node_types.<node_type_name>.docker
#
A set of overrides to the top-level Docker configuration.
Required: No
Importance: Low
Type: docker
Default:
{}
Examples#
Minimal configuration#
# An unique identifier for the head node and workers of this cluster.
cluster_name: aws-example-minimal
# Cloud-provider specific configuration.
provider:
type: aws
region: us-west-2
# An unique identifier for the head node and workers of this cluster.
cluster_name: minimal
# The maximum number of workers nodes to launch in addition to the head
# node. min_workers default to 0.
max_workers: 1
# Cloud-provider specific configuration.
provider:
type: azure
location: westus2
resource_group: ray-cluster
# How Ray will authenticate with newly launched nodes.
auth:
ssh_user: ubuntu
# you must specify paths to matching private and public key pair files
# use `ssh-keygen -t rsa -b 4096` to generate a new ssh key pair
ssh_private_key: ~/.ssh/id_rsa
# changes to this should match what is specified in file_mounts
ssh_public_key: ~/.ssh/id_rsa.pub
# A unique identifier for the head node and workers of this cluster.
cluster_name: minimal
# Cloud-provider specific configuration.
provider:
type: gcp
region: us-west1
availability_zone: us-west1-a
project_id: null # Globally unique project id
# How Ray will authenticate with newly launched nodes.
auth:
ssh_user: ubuntu
Full configuration#
# An unique identifier for the head node and workers of this cluster.
cluster_name: default
# The maximum number of workers nodes to launch in addition to the head
# node.
max_workers: 2
# The autoscaler will scale up the cluster faster with higher upscaling speed.
# E.g., if the task requires adding more nodes then autoscaler will gradually
# scale up the cluster in chunks of upscaling_speed*currently_running_nodes.
# This number should be > 0.
upscaling_speed: 1.0
# This executes all commands on all nodes in the docker container,
# and opens all the necessary ports to support the Ray cluster.
# Empty string means disabled.
docker:
image: "rayproject/ray-ml:latest-gpu" # You can change this to latest-cpu if you don't need GPU support and want a faster startup
# image: rayproject/ray:latest-cpu # use this one if you don't need ML dependencies, it's faster to pull
container_name: "ray_container"
# If true, pulls latest version of image. Otherwise, `docker run` will only pull the image
# if no cached version is present.
pull_before_run: True
run_options: # Extra options to pass into "docker run"
- --ulimit nofile=65536:65536
# Example of running a GPU head with CPU workers
# head_image: "rayproject/ray-ml:latest-gpu"
# Allow Ray to automatically detect GPUs
# worker_image: "rayproject/ray-ml:latest-cpu"
# worker_run_options: []
# If a node is idle for this many minutes, it will be removed.
idle_timeout_minutes: 5
# Cloud-provider specific configuration.
provider:
type: aws
region: us-west-2
# Availability zone(s), comma-separated, that nodes may be launched in.
# Nodes will be launched in the first listed availability zone and will
# be tried in the subsequent availability zones if launching fails.
availability_zone: us-west-2a,us-west-2b
# Whether to allow node reuse. If set to False, nodes will be terminated
# instead of stopped.
cache_stopped_nodes: True # If not present, the default is True.
# How Ray will authenticate with newly launched nodes.
auth:
ssh_user: ubuntu
# By default Ray creates a new private keypair, but you can also use your own.
# If you do so, make sure to also set "KeyName" in the head and worker node
# configurations below.
# ssh_private_key: /path/to/your/key.pem
# Tell the autoscaler the allowed node types and the resources they provide.
# The key is the name of the node type, which is just for debugging purposes.
# The node config specifies the launch config and physical instance type.
available_node_types:
ray.head.default:
# The node type's CPU and GPU resources are auto-detected based on AWS instance type.
# If desired, you can override the autodetected CPU and GPU resources advertised to the autoscaler.
# You can also set custom resources.
# For example, to mark a node type as having 1 CPU, 1 GPU, and 5 units of a resource called "custom", set
# resources: {"CPU": 1, "GPU": 1, "custom": 5}
resources: {}
# Provider-specific config for this node type, e.g. instance type. By default
# Ray will auto-configure unspecified fields such as SubnetId and KeyName.
# For more documentation on available fields, see:
# http://boto3.readthedocs.io/en/latest/reference/services/ec2.html#EC2.ServiceResource.create_instances
node_config:
InstanceType: m5.large
# Default AMI for us-west-2.
# Check https://github.com/ray-project/ray/blob/master/python/ray/autoscaler/_private/aws/config.py
# for default images for other zones.
ImageId: ami-0387d929287ab193e
# You can provision additional disk space with a conf as follows
BlockDeviceMappings:
- DeviceName: /dev/sda1
Ebs:
VolumeSize: 140GB
# Additional options in the boto docs.
ray.worker.default:
# The minimum number of worker nodes of this type to launch.
# This number should be >= 0.
min_workers: 0
# The maximum number of worker nodes of this type to launch.
# This takes precedence over min_workers.
max_workers: 2
# The node type's CPU and GPU resources are auto-detected based on AWS instance type.
# If desired, you can override the autodetected CPU and GPU resources advertised to the autoscaler.
# You can also set custom resources.
# For example, to mark a node type as having 1 CPU, 1 GPU, and 5 units of a resource called "custom", set
# resources: {"CPU": 1, "GPU": 1, "custom": 5}
resources: {}
# Provider-specific config for this node type, e.g. instance type. By default
# Ray will auto-configure unspecified fields such as SubnetId and KeyName.
# For more documentation on available fields, see:
# http://boto3.readthedocs.io/en/latest/reference/services/ec2.html#EC2.ServiceResource.create_instances
node_config:
InstanceType: m5.large
# Default AMI for us-west-2.
# Check https://github.com/ray-project/ray/blob/master/python/ray/autoscaler/_private/aws/config.py
# for default images for other zones.
ImageId: ami-0387d929287ab193e
# Run workers on spot by default. Comment this out to use on-demand.
# NOTE: If relying on spot instances, it is best to specify multiple different instance
# types to avoid interruption when one instance type is experiencing heightened demand.
# Demand information can be found at https://aws.amazon.com/ec2/spot/instance-advisor/
InstanceMarketOptions:
MarketType: spot
# Additional options can be found in the boto docs, e.g.
# SpotOptions:
# MaxPrice: MAX_HOURLY_PRICE
# Additional options in the boto docs.
# Specify the node type of the head node (as configured above).
head_node_type: ray.head.default
# Files or directories to copy to the head and worker nodes. The format is a
# dictionary from REMOTE_PATH: LOCAL_PATH, e.g.
file_mounts: {
# "/path1/on/remote/machine": "/path1/on/local/machine",
# "/path2/on/remote/machine": "/path2/on/local/machine",
}
# Files or directories to copy from the head node to the worker nodes. The format is a
# list of paths. The same path on the head node will be copied to the worker node.
# This behavior is a subset of the file_mounts behavior. In the vast majority of cases
# you should just use file_mounts. Only use this if you know what you're doing!
cluster_synced_files: []
# Whether changes to directories in file_mounts or cluster_synced_files in the head node
# should sync to the worker node continuously
file_mounts_sync_continuously: False
# Patterns for files to exclude when running rsync up or rsync down
rsync_exclude:
- "**/.git"
- "**/.git/**"
# Pattern files to use for filtering out files when running rsync up or rsync down. The file is searched for
# in the source directory and recursively through all subdirectories. For example, if .gitignore is provided
# as a value, the behavior will match git's behavior for finding and using .gitignore files.
rsync_filter:
- ".gitignore"
# List of commands that will be run before `setup_commands`. If docker is
# enabled, these commands will run outside the container and before docker
# is setup.
initialization_commands: []
# List of shell commands to run to set up nodes.
setup_commands: []
# Note: if you're developing Ray, you probably want to create a Docker image that
# has your Ray repo pre-cloned. Then, you can replace the pip installs
# below with a git checkout <your_sha> (and possibly a recompile).
# To run the nightly version of ray (as opposed to the latest), either use a rayproject docker image
# that has the "nightly" (e.g. "rayproject/ray-ml:nightly-gpu") or uncomment the following line:
# - pip install -U "ray[default] @ https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp37-cp37m-manylinux2014_x86_64.whl"
# Custom commands that will be run on the head node after common setup.
head_setup_commands: []
# Custom commands that will be run on worker nodes after common setup.
worker_setup_commands: []
# Command to start ray on the head node. You don't need to change this.
head_start_ray_commands:
- ray stop
- ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml
# Command to start ray on worker nodes. You don't need to change this.
worker_start_ray_commands:
- ray stop
- ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076
# An unique identifier for the head node and workers of this cluster.
cluster_name: default
# The maximum number of workers nodes to launch in addition to the head
# node.
max_workers: 2
# The autoscaler will scale up the cluster faster with higher upscaling speed.
# E.g., if the task requires adding more nodes then autoscaler will gradually
# scale up the cluster in chunks of upscaling_speed*currently_running_nodes.
# This number should be > 0.
upscaling_speed: 1.0
# This executes all commands on all nodes in the docker container,
# and opens all the necessary ports to support the Ray cluster.
# Empty object means disabled.
docker:
image: "rayproject/ray-ml:latest-gpu" # You can change this to latest-cpu if you don't need GPU support and want a faster startup
# image: rayproject/ray:latest-gpu # use this one if you don't need ML dependencies, it's faster to pull
container_name: "ray_container"
# If true, pulls latest version of image. Otherwise, `docker run` will only pull the image
# if no cached version is present.
pull_before_run: True
run_options: # Extra options to pass into "docker run"
- --ulimit nofile=65536:65536
# Example of running a GPU head with CPU workers
# head_image: "rayproject/ray-ml:latest-gpu"
# Allow Ray to automatically detect GPUs
# worker_image: "rayproject/ray-ml:latest-cpu"
# worker_run_options: []
# If a node is idle for this many minutes, it will be removed.
idle_timeout_minutes: 5
# Cloud-provider specific configuration.
provider:
type: azure
# https://azure.microsoft.com/en-us/global-infrastructure/locations
location: westus2
resource_group: ray-cluster
# set subscription id otherwise the default from az cli will be used
# subscription_id: 00000000-0000-0000-0000-000000000000
# set unique subnet mask or a random mask will be used
# subnet_mask: 10.0.0.0/16
# set unique id for resources in this cluster
# if not set a default id will be generated based on the resource group and cluster name
# unique_id: RAY1
# How Ray will authenticate with newly launched nodes.
auth:
ssh_user: ubuntu
# you must specify paths to matching private and public key pair files
# use `ssh-keygen -t rsa -b 4096` to generate a new ssh key pair
ssh_private_key: ~/.ssh/id_rsa
# changes to this should match what is specified in file_mounts
ssh_public_key: ~/.ssh/id_rsa.pub
# More specific customization to node configurations can be made using the ARM template azure-vm-template.json file
# See documentation here: https://docs.microsoft.com/en-us/azure/templates/microsoft.compute/2019-03-01/virtualmachines
# Changes to the local file will be used during deployment of the head node, however worker nodes deployment occurs
# on the head node, so changes to the template must be included in the wheel file used in setup_commands section below
# Tell the autoscaler the allowed node types and the resources they provide.
# The key is the name of the node type, which is just for debugging purposes.
# The node config specifies the launch config and physical instance type.
available_node_types:
ray.head.default:
# The resources provided by this node type.
resources: {"CPU": 2}
# Provider-specific config, e.g. instance type.
node_config:
azure_arm_parameters:
vmSize: Standard_D2s_v3
# List images https://docs.microsoft.com/en-us/azure/virtual-machines/linux/cli-ps-findimage
imagePublisher: microsoft-dsvm
imageOffer: ubuntu-1804
imageSku: 1804-gen2
imageVersion: latest
ray.worker.default:
# The minimum number of worker nodes of this type to launch.
# This number should be >= 0.
min_workers: 0
# The maximum number of worker nodes of this type to launch.
# This takes precedence over min_workers.
max_workers: 2
# The resources provided by this node type.
resources: {"CPU": 2}
# Provider-specific config, e.g. instance type.
node_config:
azure_arm_parameters:
vmSize: Standard_D2s_v3
# List images https://docs.microsoft.com/en-us/azure/virtual-machines/linux/cli-ps-findimage
imagePublisher: microsoft-dsvm
imageOffer: ubuntu-1804
imageSku: 1804-gen2
imageVersion: latest
# optionally set priority to use Spot instances
priority: Spot
# set a maximum price for spot instances if desired
# billingProfile:
# maxPrice: -1
# Specify the node type of the head node (as configured above).
head_node_type: ray.head.default
# Files or directories to copy to the head and worker nodes. The format is a
# dictionary from REMOTE_PATH: LOCAL_PATH, e.g.
file_mounts: {
# "/path1/on/remote/machine": "/path1/on/local/machine",
# "/path2/on/remote/machine": "/path2/on/local/machine",
"~/.ssh/id_rsa.pub": "~/.ssh/id_rsa.pub"
}
# Files or directories to copy from the head node to the worker nodes. The format is a
# list of paths. The same path on the head node will be copied to the worker node.
# This behavior is a subset of the file_mounts behavior. In the vast majority of cases
# you should just use file_mounts. Only use this if you know what you're doing!
cluster_synced_files: []
# Whether changes to directories in file_mounts or cluster_synced_files in the head node
# should sync to the worker node continuously
file_mounts_sync_continuously: False
# Patterns for files to exclude when running rsync up or rsync down
rsync_exclude:
- "**/.git"
- "**/.git/**"
# Pattern files to use for filtering out files when running rsync up or rsync down. The file is searched for
# in the source directory and recursively through all subdirectories. For example, if .gitignore is provided
# as a value, the behavior will match git's behavior for finding and using .gitignore files.
rsync_filter:
- ".gitignore"
# List of commands that will be run before `setup_commands`. If docker is
# enabled, these commands will run outside the container and before docker
# is setup.
initialization_commands:
# enable docker setup
- sudo usermod -aG docker $USER || true
- sleep 10 # delay to avoid docker permission denied errors
# get rid of annoying Ubuntu message
- touch ~/.sudo_as_admin_successful
# List of shell commands to run to set up nodes.
# NOTE: rayproject/ray-ml:latest has ray latest bundled
setup_commands: []
# Note: if you're developing Ray, you probably want to create a Docker image that
# has your Ray repo pre-cloned. Then, you can replace the pip installs
# below with a git checkout <your_sha> (and possibly a recompile).
# To run the nightly version of ray (as opposed to the latest), either use a rayproject docker image
# that has the "nightly" (e.g. "rayproject/ray-ml:nightly-gpu") or uncomment the following line:
# - pip install -U "ray[default] @ https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp38-cp38-manylinux2014_x86_64.whl"
# Custom commands that will be run on the head node after common setup.
# NOTE: rayproject/ray-ml:latest has azure packages bundled
head_setup_commands: []
# - pip install -U azure-cli-core==2.22.0 azure-mgmt-compute==14.0.0 azure-mgmt-msi==1.0.0 azure-mgmt-network==10.2.0 azure-mgmt-resource==13.0.0
# Custom commands that will be run on worker nodes after common setup.
worker_setup_commands: []
# Command to start ray on the head node. You don't need to change this.
head_start_ray_commands:
- ray stop
- ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml
# Command to start ray on worker nodes. You don't need to change this.
worker_start_ray_commands:
- ray stop
- ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076
# An unique identifier for the head node and workers of this cluster.
cluster_name: default
# The maximum number of workers nodes to launch in addition to the head
# node.
max_workers: 2
# The autoscaler will scale up the cluster faster with higher upscaling speed.
# E.g., if the task requires adding more nodes then autoscaler will gradually
# scale up the cluster in chunks of upscaling_speed*currently_running_nodes.
# This number should be > 0.
upscaling_speed: 1.0
# This executes all commands on all nodes in the docker container,
# and opens all the necessary ports to support the Ray cluster.
# Empty string means disabled.
docker:
image: "rayproject/ray-ml:latest-gpu" # You can change this to latest-cpu if you don't need GPU support and want a faster startup
# image: rayproject/ray:latest-gpu # use this one if you don't need ML dependencies, it's faster to pull
container_name: "ray_container"
# If true, pulls latest version of image. Otherwise, `docker run` will only pull the image
# if no cached version is present.
pull_before_run: True
run_options: # Extra options to pass into "docker run"
- --ulimit nofile=65536:65536
# Example of running a GPU head with CPU workers
# head_image: "rayproject/ray-ml:latest-gpu"
# Allow Ray to automatically detect GPUs
# worker_image: "rayproject/ray-ml:latest-cpu"
# worker_run_options: []
# If a node is idle for this many minutes, it will be removed.
idle_timeout_minutes: 5
# Cloud-provider specific configuration.
provider:
type: gcp
region: us-west1
availability_zone: us-west1-a
project_id: null # Globally unique project id
# How Ray will authenticate with newly launched nodes.
auth:
ssh_user: ubuntu
# By default Ray creates a new private keypair, but you can also use your own.
# If you do so, make sure to also set "KeyName" in the head and worker node
# configurations below. This requires that you have added the key into the
# project wide meta-data.
# ssh_private_key: /path/to/your/key.pem
# Tell the autoscaler the allowed node types and the resources they provide.
# The key is the name of the node type, which is just for debugging purposes.
# The node config specifies the launch config and physical instance type.
available_node_types:
ray_head_default:
# The resources provided by this node type.
resources: {"CPU": 2}
# Provider-specific config for the head node, e.g. instance type. By default
# Ray will auto-configure unspecified fields such as subnets and ssh-keys.
# For more documentation on available fields, see:
# https://cloud.google.com/compute/docs/reference/rest/v1/instances/insert
node_config:
machineType: n1-standard-2
disks:
- boot: true
autoDelete: true
type: PERSISTENT
initializeParams:
diskSizeGb: 50
# See https://cloud.google.com/compute/docs/images for more images
sourceImage: projects/deeplearning-platform-release/global/images/family/common-cpu
# Additional options can be found in in the compute docs at
# https://cloud.google.com/compute/docs/reference/rest/v1/instances/insert
# If the network interface is specified as below in both head and worker
# nodes, the manual network config is used. Otherwise an existing subnet is
# used. To use a shared subnet, ask the subnet owner to grant permission
# for 'compute.subnetworks.use' to the ray autoscaler account...
# networkInterfaces:
# - kind: compute#networkInterface
# subnetwork: path/to/subnet
# aliasIpRanges: []
ray_worker_small:
# The minimum number of worker nodes of this type to launch.
# This number should be >= 0.
min_workers: 0
# The maximum number of worker nodes of this type to launch.
# This takes precedence over min_workers.
max_workers: 2
# The resources provided by this node type.
resources: {"CPU": 2}
# Provider-specific config for the head node, e.g. instance type. By default
# Ray will auto-configure unspecified fields such as subnets and ssh-keys.
# For more documentation on available fields, see:
# https://cloud.google.com/compute/docs/reference/rest/v1/instances/insert
node_config:
machineType: n1-standard-2
disks:
- boot: true
autoDelete: true
type: PERSISTENT
initializeParams:
diskSizeGb: 50
# See https://cloud.google.com/compute/docs/images for more images
sourceImage: projects/deeplearning-platform-release/global/images/family/common-cpu
# Run workers on preemtible instance by default.
# Comment this out to use on-demand.
scheduling:
- preemptible: true
# Un-Comment this to launch workers with the Service Account of the Head Node
# serviceAccounts:
# - email: ray-autoscaler-sa-v1@<project_id>.iam.gserviceaccount.com
# scopes:
# - https://www.googleapis.com/auth/cloud-platform
# Additional options can be found in in the compute docs at
# https://cloud.google.com/compute/docs/reference/rest/v1/instances/insert
# Specify the node type of the head node (as configured above).
head_node_type: ray_head_default
# Files or directories to copy to the head and worker nodes. The format is a
# dictionary from REMOTE_PATH: LOCAL_PATH, e.g.
file_mounts: {
# "/path1/on/remote/machine": "/path1/on/local/machine",
# "/path2/on/remote/machine": "/path2/on/local/machine",
}
# Files or directories to copy from the head node to the worker nodes. The format is a
# list of paths. The same path on the head node will be copied to the worker node.
# This behavior is a subset of the file_mounts behavior. In the vast majority of cases
# you should just use file_mounts. Only use this if you know what you're doing!
cluster_synced_files: []
# Whether changes to directories in file_mounts or cluster_synced_files in the head node
# should sync to the worker node continuously
file_mounts_sync_continuously: False
# Patterns for files to exclude when running rsync up or rsync down
rsync_exclude:
- "**/.git"
- "**/.git/**"
# Pattern files to use for filtering out files when running rsync up or rsync down. The file is searched for
# in the source directory and recursively through all subdirectories. For example, if .gitignore is provided
# as a value, the behavior will match git's behavior for finding and using .gitignore files.
rsync_filter:
- ".gitignore"
# List of commands that will be run before `setup_commands`. If docker is
# enabled, these commands will run outside the container and before docker
# is setup.
initialization_commands: []
# List of shell commands to run to set up nodes.
setup_commands: []
# Note: if you're developing Ray, you probably want to create a Docker image that
# has your Ray repo pre-cloned. Then, you can replace the pip installs
# below with a git checkout <your_sha> (and possibly a recompile).
# To run the nightly version of ray (as opposed to the latest), either use a rayproject docker image
# that has the "nightly" (e.g. "rayproject/ray-ml:nightly-gpu") or uncomment the following line:
# - pip install -U "ray[default] @ https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp37-cp37m-manylinux2014_x86_64.whl"
# Custom commands that will be run on the head node after common setup.
head_setup_commands:
- pip install google-api-python-client==1.7.8
# Custom commands that will be run on worker nodes after common setup.
worker_setup_commands: []
# Command to start ray on the head node. You don't need to change this.
head_start_ray_commands:
- ray stop
- >-
ray start
--head
--port=6379
--object-manager-port=8076
--autoscaling-config=~/ray_bootstrap_config.yaml
# Command to start ray on worker nodes. You don't need to change this.
worker_start_ray_commands:
- ray stop
- >-
ray start
--address=$RAY_HEAD_IP:6379
--object-manager-port=8076
TPU Configuration#
It is possible to use TPU VMs on GCP. Currently, TPU pods (TPUs other than v2-8, v3-8 and v4-8) are not supported.
Before using a config with TPUs, ensure that the TPU API is enabled for your GCP project.
# This config is an example TPU config allowing you to run
# https://github.com/Yard1/swarm-jax on GCP TPUs
# Replace provider.project_id with your GCP project id
# After the nodes are up, run:
# ray attach tpu.yaml swarm_tpu_jax.py swarm-jax/data/enwik8 [NUM_TPUS] [EPOCHS]
# A unique identifier for the head node and workers of this cluster.
cluster_name: tputest
# The maximum number of worker nodes to launch in addition to the head
# node.
max_workers: 7
available_node_types:
ray_head_default:
resources: {"CPU": 2}
node_config:
machineType: n2-standard-2
disks:
- boot: true
autoDelete: true
type: PERSISTENT
initializeParams:
diskSizeGb: 50
# See https://cloud.google.com/compute/docs/images for more images
sourceImage: projects/deeplearning-platform-release/global/images/family/common-cpu
ray_tpu:
min_workers: 7
resources: {"TPU": 1} # use TPU custom resource in your code
node_config:
# Only v2-8, v3-8 and v4-8 accelerator types are currently supported.
# Support for TPU pods will be added in the future.
acceleratorType: v2-8
runtimeVersion: v2-alpha
schedulingConfig:
# Set to false to use non-preemptible TPUs
preemptible: true
provider:
type: gcp
region: us-central1
availability_zone: us-central1-b
project_id: null # replace with your GCP project id
setup_commands: []
# Specify the node type of the head node (as configured above).
# TPUs cannot be head nodes (will raise an exception).
head_node_type: ray_head_default
# Compute instances have python 3.7, but TPUs have 3.8 - need to update
# Install Jax and other dependencies on the Compute head node
head_setup_commands:
# Two first lines are a workaround for ssh timing out
- sleep 2
- sleep 2
- sudo chown -R $(whoami) /opt/conda/*
- conda create -y -n "ray" python=3.8.5
- conda activate ray && echo 'conda activate ray' >> ~/.bashrc
- python -m pip install --upgrade pip
- python -m pip install --upgrade "jax[cpu]==0.2.14"
- python -m pip install --upgrade fabric dataclasses optax==0.0.6 git+https://github.com/deepmind/dm-haiku google-api-python-client cryptography tensorboardX ray[default]
- python -m pip install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp38-cp38-manylinux2014_x86_64.whl
- git clone https://github.com/Yard1/swarm-jax.git && cd swarm-jax && python -m pip install .
# Install Jax and other dependencies on TPU
worker_setup_commands:
- pip3 install --upgrade pip
- pip3 install --upgrade "jax[tpu]==0.2.14" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
- pip3 install --upgrade fabric dataclasses optax==0.0.6 git+https://github.com/deepmind/dm-haiku tensorboardX ray[default]
- python3 -c "import jax; jax.device_count(); jax.numpy.add(1, 1)" # test if Jax has been installed correctly
- pip3 install -U https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp38-cp38-manylinux2014_x86_64.whl
- git clone https://github.com/Yard1/swarm-jax.git && cd swarm-jax && sudo pip3 install .