在 AWS 上启动 Ray 集群

本指南详细介绍了在 AWS 上启动 Ray 集群所需的步骤。

要启动 AWS Ray 集群，您应该使用 Ray 集群启动器和 AWS Python SDK。

安装 Ray 集群启动器

Ray 集群启动器是 ray CLI 的一部分。您可以使用 CLI 通过 ray up、ray down 和 ray attach 等命令来启动、停止和附加到正在运行的 Ray 集群。您可以使用 pip 安装支持集群启动器的 ray CLI。有关更详细的说明，请遵循Ray 安装文档。

# install ray
pip install -U ray[default]

安装和配置 AWS Python SDK (Boto3)

接下来，使用 pip install -U boto3 安装 AWS SDK，并按照AWS 指南配置您的 AWS 凭证。

# install AWS Python SDK (boto3)
pip install -U boto3

# setup AWS credentials using environment variables
export AWS_ACCESS_KEY_ID=foo
export AWS_SECRET_ACCESS_KEY=bar
export AWS_SESSION_TOKEN=baz

# alternatively, you can setup AWS credentials using ~/.aws/credentials file
echo "[default]
aws_access_key_id=foo
aws_secret_access_key=bar
aws_session_token=baz" >> ~/.aws/credentials

使用 Ray 集群启动器启动 Ray

一旦 Boto3 配置为管理您 AWS 账户中的资源，您就可以使用集群启动器启动您的集群了。提供的集群配置文件将创建一个小型集群，该集群包含一个 m5.large （按需）的 head 节点，并配置为自动扩展到最多两个 m5.large spot-instance 工作节点。

通过从本地机器运行以下命令来测试它是否正常工作

# Download the example-full.yaml
wget https://raw.githubusercontent.com/ray-project/ray/master/python/ray/autoscaler/aws/example-full.yaml

# Create or update the cluster. When the command finishes, it will print
# out the command that can be used to SSH into the cluster head node.
ray up example-full.yaml

# Get a remote shell on the head node.
ray attach example-full.yaml

# Try running a Ray program.
python -c 'import ray; ray.init()'
exit

# Tear down the cluster.
ray down example-full.yaml

恭喜！您已在 AWS 上成功启动了 Ray 集群！

如果您想了解更多关于 Ray 集群启动器的信息，请参阅这篇博客文章，其中提供了分步指南。

AWS 配置

使用 Amazon EFS

要使用 Ray 集群中的 Amazon EFS，您需要安装一些额外的实用程序并在 setup_commands 中挂载 EFS。请注意，这些说明仅在您使用 AWS 上的 Ray 集群启动器时有效。

# Note You need to replace the {{FileSystemId}} with your own EFS ID before using the config.
# You may also need to modify the SecurityGroupIds for the head and worker nodes in the config file.

setup_commands:
    - sudo kill -9 `sudo lsof /var/lib/dpkg/lock-frontend | awk '{print $2}' | tail -n 1`;
        sudo pkill -9 apt-get;
        sudo pkill -9 dpkg;
        sudo dpkg --configure -a;
        sudo apt-get -y install binutils;
        cd $HOME;
        git clone https://github.com/aws/efs-utils;
        cd $HOME/efs-utils;
        ./build-deb.sh;
        sudo apt-get -y install ./build/amazon-efs-utils*deb;
        cd $HOME;
        mkdir efs;
        sudo mount -t efs {{FileSystemId}}:/ efs;
        sudo chmod 777 efs;

配置 IAM 角色和 EC2 实例配置文件

默认情况下，Ray AWS 集群中的 Ray 节点拥有完整的 EC2 和 S3 权限（即 arn:aws:iam::aws:policy/AmazonEC2FullAccess 和 arn:aws:iam::aws:policy/AmazonS3FullAccess）。这是尝试 Ray 集群的一个很好的默认设置，但您可能出于各种原因（例如，出于安全原因减少权限）希望更改 Ray 节点拥有的权限。您可以通过为相关的 node_config 提供自定义的 IamInstanceProfile 来实现这一点。

available_node_types:
  ray.worker.default:
    node_config:
      ...
      IamInstanceProfile:
        Arn: arn:aws:iam::YOUR_AWS_ACCOUNT:YOUR_INSTANCE_PROFILE

有关配置 IAM 角色和 EC2 实例配置文件的更多详细信息，请参阅此讨论。

访问 S3

在各种场景下，工作节点可能需要写入 S3 存储桶的权限，例如，Ray Tune 提供了一个选项，可以将检查点写入 S3，而不是直接同步回驱动程序。

如果您看到类似“无法找到凭证”的错误，请确保在集群配置文件中为工作节点配置了正确的 IamInstanceProfile。这可能看起来像这样：

available_node_types:
  ray.worker.default:
    node_config:
      ...
      IamInstanceProfile:
        Arn: arn:aws:iam::YOUR_AWS_ACCOUNT:YOUR_INSTANCE_PROFILE

您可以通过 SSH 进入工作节点并运行以下命令来验证设置是否正确：

aws configure list

您应该会看到类似以下内容：

      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                <not set>             None    None
access_key     ****************XXXX         iam-role
secret_key     ****************YYYY         iam-role
    region                <not set>             None    None

有关访问 S3 的更多详细信息，请参阅此讨论。

使用 Amazon CloudWatch 监控 Ray

Amazon CloudWatch 是一项监控和可观察性服务，可提供数据和可操作的见解，用于监控您的应用程序、响应系统范围的性能变化以及优化资源利用率。CloudWatch 与 Ray 的集成需要一个预装了统一 CloudWatch 代理的 AMI（或 Docker 镜像）。

Amazon Ray 团队提供了预装了统一 CloudWatch 代理的 AMI，目前在 us-east-1、us-east-2、us-west-1 和 us-west-2 区域可用。如有任何问题、评论或疑虑，请联系Amazon Ray 团队。

下表列出了各区域预装了统一 CloudWatch 代理的 AMI，您也可以在DLAMI 发行说明中找到 AMI。每个 DLAMI（深度学习 AMI）都预装了统一 CloudWatch 代理，其相应的发行说明包括用于查询最新 AMI ID 的 AWS CLI 命令。

所有可用的统一 CloudWatch 代理镜像

基本 AMI	AMI ID	区域	统一 CloudWatch 代理版本
AWS 深度学习 AMI（Ubuntu 24.04，64 位）	ami-087feac195f30e722	us-east-1	v1.300057.1b1167
AWS 深度学习 AMI（Ubuntu 24.04，64 位）	ami-0ed6c422a7c93278a	us-east-2	v1.300057.1b1167
AWS 深度学习 AMI（Ubuntu 24.04，64 位）	ami-0c5ddf2c101267018	us-west-1	v1.300057.1b1167
AWS 深度学习 AMI（Ubuntu 24.04，64 位）	ami-0cfd95c6c87d00570	us-west-2	v1.300057.1b1167

注意

使用 Amazon CloudWatch 会产生费用，详情请参阅CloudWatch 定价。

入门

1. 创建一个名为 cloudwatch-basic.yaml 的最小集群配置文件 YAML，内容如下：

provider:
    type: aws
    region: us-west-2
    availability_zone: us-west-2a
    # Start by defining a `cloudwatch` section to enable CloudWatch integration with your Ray cluster.
    cloudwatch:
        agent:
            # Path to Unified CloudWatch Agent config file
            config: "cloudwatch/example-cloudwatch-agent-config.json"
        dashboard:
            # CloudWatch Dashboard name
            name: "example-dashboard-name"
            # Path to the CloudWatch Dashboard config file
            config: "cloudwatch/example-cloudwatch-dashboard-config.json"

auth:
    ssh_user: ubuntu

available_node_types:
    ray.head.default:
        node_config:
        InstanceType: c5a.large
        ImageId: ami-0cfd95c6c87d00570  # Unified CloudWatch agent pre-installed AMI, us-west-2
        resources: {}
    ray.worker.default:
        node_config:
            InstanceType: c5a.large
            ImageId: ami-0cfd95c6c87d00570  # Unified CloudWatch agent pre-installed AMI, us-west-2
            IamInstanceProfile:
                Name: ray-autoscaler-cloudwatch-v1
        resources: {}
        min_workers: 0

2. 下载 CloudWatch 代理和仪表板配置。

首先，在与 cloudwatch-basic.yaml 相同的目录下创建一个 cloudwatch 目录。然后，将示例CloudWatch 代理和CloudWatch 仪表板配置文件下载到 cloudwatch 目录中。

$ mkdir cloudwatch
$ cd cloudwatch
$ wget https://raw.githubusercontent.com/ray-project/ray/master/python/ray/autoscaler/aws/cloudwatch/example-cloudwatch-agent-config.json
$ wget https://raw.githubusercontent.com/ray-project/ray/master/python/ray/autoscaler/aws/cloudwatch/example-cloudwatch-dashboard-config.json

3. 运行 ray up cloudwatch-basic.yaml 来启动您的 Ray 集群。

这将在 us-west-2 区域默认启动您的 Ray 集群。当启动不同区域的集群时，您需要更改集群配置文件 YAML 文件中的 region 和 ImageId。请参阅上面的“统一 CloudWatch 代理镜像”表，了解各区域可用的 AMI。

在 CloudWatch 控制台中查看您的 Ray 集群的日志、指标和仪表板！

可以通过确保您已安装AWS CLI V2+并运行以下命令，来获取所有写入 CloudWatch 日志组的日志的 tail：

aws logs tail $log_group_name --follow

高级设置

有关完整的示例，请参阅example-cloudwatch.yaml。

1. 选择一个预装了统一 CloudWatch 代理的 AMI。

确保您在与 AMI 相同的区域启动您的 Ray EC2 集群，然后在集群配置文件 YAML 文件中为您的集群的 head 和 worker 节点指定要使用的 ImageId。

以下 CLI 命令返回 us-west-2 区域最新可用的统一 CloudWatch 代理镜像。

aws ec2 describe-images --region us-west-2 --filters "Name=owner-id,Values=160082703681" "Name=name,Values=*cloudwatch*" --query 'Images[*].[ImageId,CreationDate]' --output text | sort -k2 -r | head -n1

available_node_types:
    ray.head.default:
        node_config:
        InstanceType: c5a.large
        ImageId: ami-0cfd95c6c87d00570
    ray.worker.default:
        node_config:
        InstanceType: c5a.large
        ImageId: ami-0cfd95c6c87d00570

构建您自己的预装了统一 CloudWatch 代理的 AMI

1. 请遵循CloudWatch 代理安装用户指南，在 EC2 实例上安装统一 CloudWatch 代理。

2. 请遵循EC2 AMI 创建用户指南，从此 EC2 实例创建 AMI。

2. 定义您自己的 CloudWatch 代理、仪表板和告警 JSON 配置文件。

您可以从使用示例CloudWatch 代理、CloudWatch 仪表板和CloudWatch 告警配置文件开始。

这些示例配置文件包含以下功能：

日志和指标：写入 /tmp/ray/session_*/logs/**.out 的日志将在 {cluster_name}-ray_logs_out 日志组中可用，写入 /tmp/ray/session_*/logs/**.err 的日志将在 {cluster_name}-ray_logs_err 日志组中可用。日志流的名称将以发出其日志的 EC2 实例 ID 命名。扩展的 EC2 指标，包括 CPU/磁盘/内存使用情况和进程统计信息，可以在 {cluster_name}-ray-CWAgent 指标命名空间中找到。

仪表板：您将拥有一个集群级别的仪表板，显示集群总 CPU 和可用对象存储内存。进程数、磁盘使用情况、内存使用情况和 CPU 利用率将显示为集群级别的总和以及单节点的最大值/平均值。

告警：配置了节点级别的告警，用于跟踪长时间的高内存、磁盘和 CPU 使用情况。告警操作尚未设置，必须在您的告警配置文件中手动提供。

有关更高级的选项，请参阅代理、仪表板和告警配置用户指南。

CloudWatch 代理、仪表板和告警 JSON 配置文件支持以下变量：

{instance_id}：替换为 Ray 集群中的每个 EC2 实例 ID。

{region}：替换为 Ray 集群的区域。

{cluster_name}：替换为 Ray 集群的名称。

有关统一 CloudWatch 代理原生支持的其他变量，请参阅 CloudWatch 代理配置文件详细信息。

注意

请记住替换 CloudWatch 告警配置文件中的 AlarmActions 占位符！

"AlarmActions":[
    "TODO: Add alarm actions! See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html"
 ]

3. 在您的集群配置文件 YAML 中引用您的 CloudWatch JSON 配置文件。

指定您的 CloudWatch JSON 配置文件相对于您将运行 ray up 的工作目录的文件路径。

provider:
   cloudwatch:
       agent:
           config: "cloudwatch/example-cloudwatch-agent-config.json"

4. 设置您的 IAM 角色和 EC2 实例配置文件。

默认情况下，在 Ray 集群启动时会创建 ray-autoscaler-cloudwatch-v1 IAM 角色和 EC2 实例配置文件。该角色包含集成 CloudWatch 与 Ray 所需的所有其他权限，即 CloudWatchAgentAdminPolicy、AmazonSSMManagedInstanceCore、ssm:SendCommand、ssm:ListCommandInvocations 和 iam:PassRole 管理策略。

确保在您的集群配置文件 YAML 中配置所有工作节点以使用 ray-autoscaler-cloudwatch-v1 EC2 实例配置文件。

ray.worker.default:
    node_config:
        InstanceType: c5a.large
        IamInstanceProfile:
            Name: ray-autoscaler-cloudwatch-v1

5. 将 Ray 系统指标导出到 CloudWatch。

要将 Ray 的 Prometheus 系统指标导出到 CloudWatch，请首先确保您的集群安装了 Ray Dashboard，然后取消注释example-cloudwatch.yaml 文件中的 head_setup_commands 部分。您可以在 {cluster_name}-ray-prometheus 指标命名空间中找到 Ray Prometheus 指标。

  head_setup_commands:
# Make `ray_prometheus_waiter.sh` executable.
- >-
  RAY_INSTALL_DIR=`pip show ray | grep -Po "(?<=Location:).*"`
  && sudo chmod +x $RAY_INSTALL_DIR/ray/autoscaler/aws/cloudwatch/ray_prometheus_waiter.sh
# Copy `prometheus.yml` to Unified CloudWatch Agent folder
- >-
  RAY_INSTALL_DIR=`pip show ray | grep -Po "(?<=Location:).*"`
  && sudo cp -f $RAY_INSTALL_DIR/ray/autoscaler/aws/cloudwatch/prometheus.yml /opt/aws/amazon-cloudwatch-agent/etc
# First get current cluster name, then let the Unified CloudWatch Agent restart and use `AmazonCloudWatch-ray_agent_config_{cluster_name}` parameter at SSM Parameter Store.
- >-
  nohup sudo sh -c "`pip show ray | grep -Po "(?<=Location:).*"`/ray/autoscaler/aws/cloudwatch/ray_prometheus_waiter.sh
  `cat ~/ray_bootstrap_config.yaml | jq '.cluster_name'`
  >> '/opt/aws/amazon-cloudwatch-agent/logs/ray_prometheus_waiter.out' 2>> '/opt/aws/amazon-cloudwatch-agent/logs/ray_prometheus_waiter.err'" &

6. 更新 CloudWatch 代理、仪表板和告警配置文件。

您可以通过修改 Ray 集群配置文件 YAML 引用的 CloudWatch 配置文件，然后重新运行 ray up example-cloudwatch.yaml 来应用对集群的 CloudWatch 日志、指标、仪表板和告警的更改。统一 CloudWatch 代理将自动在所有集群节点上重新启动，并应用您的配置更改。