Skip to main content

Manage AWS IAM roles for Anyscale clusters

This page describes how to use and manage IAM roles for Anyscale clouds deployed on AWS.

When you deploy an Anyscale cluster, the nodes in the cluster have an instance profile attached. The permissions in this instance profile grant access to required resources for workspace, jobs, and services.

What IAM roles does Anyscale use?​

The following table defines the IAM roles used by Anyscale on AWS:

TermDescription
Control plane roleAnyscale uses the term control plane role to describe the set of permissions granted by the customer to the Anyscale control plane.

Anyscale on AWS uses a model where admins configure a control plane role that the Anyscale contol plane assumes using a cross-account IAM configuration.
Anyscale cluster IAM rolesWhen you deploy an Anyscale cluster, all virtual machines in the cluster assume an instance profile based on an IAM role. This provides the nodes in your cluster direct access to resources in your cloud provider, such as your S3 bucket.

You configure a default IAM role for clusters when you deploy your Anyscale cloud. You can add additional IAM roles and define rules with cloud IAM mapping. See Anyscale cloud IAM mapping.

Minimum privileges for Anyscale cluster IAM roles​

Anyscale uses the S3 bucket registered during cloud deployment to store production artifacts related to your Anyscale workloads. The IAM role used by your cluster must have access to this bucket.

The following shows the minimum permissions required to interact with the default S3 bucket:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListObjectsInBucket",
            "Effect": "Allow",
            "Action": ["s3:ListBucket"],
            "Resource": ["arn:aws:s3:::{bucket-name}"]
        },
        {
            "Sid": "AllObjectActions",
            "Effect": "Allow",
            "Action": "s3:*Object",
            "Resource": ["arn:aws:s3:::{bucket-name}/*"]
        }
    ]
}
note

If you are accessing an S3 bucket in another account, AWS requires that you also add permissions to your S3 bucket. See S3 bucket IAM permissions.

Common IAM privileges​

To use an IAM role to interact with other AWS services, you must add permissions. Follow the AWS documentation for configuring IAM permissions for the following common services:

Determine the IAM role used by an Anyscale cluster​

Anyscale base images include the boto3 library. Run the following Python code to get the identity of the IAM role attached to your cluster:

import boto3

client = boto3.client('sts')
client.get_caller_identity()

Specifiy an IAM role for an Anyscale cluster​

You can attach a custom IAM role to your Anyscale cluster. This IAM role must have access to the default S3 bucket deployed with your Anyscale cloud.

note

Each cluster runs with a single instance profile. Specifying an instance profile overrides the default IAM role for the cluster.

Anyscale clusters use IAM roles by assuming them using instance profiles. See AWS docs on using instance profiles.

To use an instance profile with an Anyscale cluster, complete the following steps:

  1. Locate the instance profile ARN for your desired IAM role.
  2. Create or modify a compute config. See Create or version a compute config.
  3. Add the Instance Profile ARN in the Advanced settings > Instance config field.
  4. Use the compute config when configuring a workspace, job, or service.

The following are examples of using the Anyscale console or CLI to configure an instance profile:

The following is an example JSON configuration to set the IAM Instance Profile:

{
"IamInstanceProfile": { "Arn": "<IAM Instance Profile ARN>" }
}

S3 bucket IAM permissions​

Your IAM role must have access to the S3 bucket registered with your Anyscale cloud deployment. You can optionally grant access to data in other S3 buckets.

The following example configuration grants access to the main Anyscale IAM role used by the control plane, the default IAM role assumed by your cluster, and a new user-defined IAM role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "allow-role-access",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<account_id>:role/<your-anyscale-iam-role-name>",
                    "arn:aws:iam::<account_id>:role/<default-cluster-iam-role-name>",
                    "arn:aws:iam::<account_id>:role/<new-cluster-iam-role-name>",
                ]
            },
            "Action": [
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:ListBucketMultipartUploads",
                "s3:ListMultipartUploadParts",
                "s3:AbortMultipartUpload",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::<your-bucket-name>/*",
                "arn:aws:s3:::<your-bucket-name>"
            ]
        }
    ]
}