---
title: "Cloud SDK reference"
description: "Customer-hosted cloud features"
---

# Cloud SDK reference

#### Customer-hosted cloud features

:::note
Some features are only available on customer-hosted clouds. Reach out to [support@anyscale.com](mailto:support@anyscale.com) for info.
:::

## Cloud SDK

### `anyscale.cloud.add_collaborators`

Batch add collaborators to a cloud.

**Arguments**

-   **`cloud` (str)**: The cloud to add users to.
-   **`collaborators` (List\[[CreateCloudCollaborator](#createcloudcollaborator)\])**: The list of collaborators to add to the cloud.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.cloud.models import CloudPermissionLevel, CreateCloudCollaborator

anyscale.cloud.add_collaborators(
    cloud="cloud_name",
    collaborators=[
        CreateCloudCollaborator(
            email="test1@anyscale.com",
            permission_level=CloudPermissionLevel.WRITE,
        ),
        CreateCloudCollaborator(
            email="test2@anyscale.com",
            permission_level=CloudPermissionLevel.READONLY,
        ),
    ],
)
```
:::

::::

### `anyscale.cloud.list`

List clouds or fetch a single cloud by ID/name.

**Arguments**

-   **`cloud_id` (str | None) = None**: If provided, returns just the cloud with this ID wrapped in a one-page iterator.
-   **`name` (str | None) = None**: Substring or exact name to match against the cloud name.
-   **`max_items` (int | None) = None**: Maximum total number of items to yield (default: iterate all).
-   **`page_size` (int | None) = None**: Number of items to fetch per API request (default: API default).

**Returns**: ResultIterator\[[Cloud](#cloud)\]

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Example: Get the first 50 clouds
for cloud in anyscale.cloud.list(max_items=50):
    print(cloud.name)
```
:::

::::

### `anyscale.cloud.get`

Get the cloud model for the provided cloud ID or name.

If neither ID nor name is provided, returns `None`.

**Arguments**

-   **`id` (str | None) = None**: The ID of the cloud to retrieve.
-   **`name` (str | None) = None**: The name of the cloud to retrieve.

**Returns**: [Cloud](#cloud) | None

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Get a cloud by ID
cloud_by_id = anyscale.cloud.get(id="cloud_id")

# Get a cloud by name
cloud_by_name = anyscale.cloud.get(name="cloud_name")
```
:::

::::

### `anyscale.cloud.get_default`

Get the user's default cloud.

**Arguments**

**Returns**: [Cloud](#cloud) | None

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Get the user's default cloud
default_cloud = anyscale.cloud.get_default()
```
:::

::::

### `anyscale.cloud.terminate_system_cluster`

Terminate the system cluster for the specified cloud.

**Arguments**

-   **`cloud_id` (str)**: The ID of the cloud whose system cluster should be terminated.
-   **`wait` (bool | None) = False**: If True, wait for the system cluster to be terminated before returning. Defaults to False.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

# Terminate the system cluster for the cloud with the specified ID
anyscale.cloud.terminate_system_cluster(cloud_id="cloud_id", wait=True)
```
:::

::::

## Cloud models

### `Cloud`

Minimal Cloud resource model.

#### Fields

-   **`name` (str)**: Name of this Cloud.
-   **`id` (str)**: Unique identifier for this Cloud.
-   **`provider` ([CloudProvider](#cloudprovider) | str)**: Cloud provider (AWS, GCP, AZURE, GENERIC) or UNKNOWN if not recognized.
-   **`compute_stack` ([ComputeStack](#computestack) | str)**: The compute stack associated with this cloud's primary cloud resource, or UNKNOWN if not recognized.
-   **`region` (str | None)**: Region for this Cloud.
-   **`created_at` (datetime | None)**: When the Cloud was created.
-   **`is_default` (bool | None)**: Whether this is the default cloud.
-   **`is_aggregated_logs_enabled` (bool | None)**: Whether aggregated logs are enabled for this cloud.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
from datetime import datetime
from anyscale.cloud.models import Cloud, CloudProvider, ComputeStack

cloud = Cloud(
    name="my-cloud",
    id="cloud-123",
    provider="AWS",  # This will be validated as CloudProvider.AWS
    region="us-west-2",
    created_at=datetime.now(),
    is_default=True,
    compute_stack="VM"  # This will be validated as ComputeStack.VM
)
```
:::

::::

### `CloudPermissionLevel`

Permission levels for cloud collaborators.

#### Values

-   **`WRITE`**: Write permission level for the cloud
-   **`READONLY`**: Readonly permission level for the cloud

### `CreateCloudCollaborator`

User to be added as a collaborator to a cloud.

#### Fields

-   **`email` (str)**: Email of the user to be added as a collaborator.
-   **`permission_level` ([CloudPermissionLevel](#cloudpermissionlevel))**: Permission level the added user should have for the cloud (one of: WRITE,READONLY).

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.cloud.models import CloudPermissionLevel, CreateCloudCollaborator

create_cloud_collaborator = CreateCloudCollaborator(
   # Email of the user to be added as a collaborator
    email="test@anyscale.com",
    # Permission level for the user to the cloud (CloudPermissionLevel.WRITE, CloudPermissionLevel.READONLY)
    permission_level=CloudPermissionLevel.READONLY,
)
```
:::

::::

### `CloudResource`

Cloud resource configuration.

#### Fields

-   **`cloud_resource_id` (str | None)**: Unique identifier for this cloud resource.
-   **`name` (str | None)**: The name of this cloud resource.
-   **`provider` ([CloudProvider](#cloudprovider) | str)**: The cloud provider type (e.g., AWS, GCP, AZURE, or GENERIC).
-   **`compute_stack` ([ComputeStack](#computestack) | str)**: The compute stack (VM or K8S).
-   **`region` (str | None)**: The region (e.g., us-west-2).
-   **`networking_mode` ([NetworkingMode](#networkingmode) | None)**: Whether to use public or private networking.
-   **`object_storage` ([ObjectStorage](#objectstorage) | None)**: Object storage configuration.
-   **`file_storage` ([FileStorage](#filestorage) | None)**: File storage configuration.
-   **`aws_config` ([AWSConfig](#awsconfig) | None)**: AWS provider-specific configurations.
-   **`gcp_config` ([GCPConfig](#gcpconfig) | None)**: GCP provider-specific configurations.
-   **`kubernetes_config` ([KubernetesConfig](#kubernetesconfig) | None)**: Kubernetes stack configurations.

#### Examples

::::tabs

:::tab[YAML]
```yaml
cloud_resource_id: cldrsrc_12345678901234567890123456
name: my-cloud-resource
provider: AWS
compute_stack: VM
region: us-west-2
networking_mode: PUBLIC
object_storage:
  bucket_name: s3://my-bucket
file_storage:
  file_storage_id: fs-12345678901234567
aws_config:
  vpc_id: vpc-12345678901234567
  subnet_ids:
  - subnet-11111111111111111
  - subnet-22222222222222222
  security_group_ids:
  - sg-12345678901234567
  anyscale_iam_role_id: arn:aws:iam::123456789012:role/anyscale-iam-role
  cluster_iam_role_id: arn:aws:iam::123456789012:role/cluster-node-role
  cluster_instance_profile_id: arn:aws:iam::123456789012:instance-profile/cluster-node-profile
  memorydb_cluster_name: my-memorydb-cluster
```
:::

::::

### `ComputeStack`

Type of compute stack for the cloud.

#### Values

-   **`UNKNOWN`**: Unknown compute stack.
-   **`VM`**: Virtual machine-based compute stack.
-   **`K8S`**: Kubernetes-based compute stack.

### `CloudProvider`

Cloud infrastructure provider.

#### Values

-   **`UNKNOWN`**: Unknown cloud provider.
-   **`AWS`**: Amazon Web Services.
-   **`GCP`**: Google Cloud Platform.
-   **`AZURE`**: Microsoft Azure.
-   **`GENERIC`**: Generic cloud provider.

### `NetworkingMode`

Networking mode for cloud resources.

#### Values

-   **`PUBLIC`**: Direct networking.
-   **`PRIVATE`**: Customer-defined networking.

### `ObjectStorage`

Object storage configuration.

#### Fields

-   **`bucket_name` (str | None)**: The cloud storage bucket name, prefixed with the storage scheme (s3://bucket-name, gs://bucket-name, or abfss://bucket-[name@account.dfs.core.windows.net](mailto:name@account.dfs.core.windows.net)).
-   **`region` (str | None)**: The region for the cloud storage bucket. Defaults to the region of the cloud resource.
-   **`endpoint` (str | None)**: The cloud storage endpoint, used to override the default cloud storage scheme's endpoint. For example, for S3, this will be passed to the AWS\_ENDPOINT\_URL environment variable.

#### Examples

::::tabs

:::tab[YAML]
```yaml
object_storage:
  bucket_name: s3://my-bucket
```
:::

::::

### `FileStorage`

File storage configuration.

#### Fields

-   **`file_storage_id` (str | None)**: For AWS, the EFS ID. For GCP, the Filestore instance name.
-   **`mount_targets` (List\[[NFSMountTarget](#nfsmounttarget)\] | None)**: The mount target(s) to use.
-   **`mount_path` (str | None)**: For GCP, the Filestore root directory. For NFS, the path of the server to mount from (e.g., <mount-target-address>/<mount-path> will be mounted).
-   **`persistent_volume_claim` (str | None)**: For Kubernetes resources, the name of the persistent volume claim used to mount shared storage into pods.
-   **`csi_ephemeral_volume_driver` (str | None)**: For Kubernetes resources, the CSI ephemeral volume driver used to mount shared storage into pods.

#### Examples

::::tabs

:::tab[YAML]
```yaml
file_storage:
  file_storage_id: fs-12345678901234567
```
:::

::::

### `NFSMountTarget`

NFS mount target configuration.

#### Fields

-   **`address` (str)**: The address of the NFS mount target.
-   **`zone` (str | None)**: The zone of the NFS mount target. If not set, this mount target may be used in any zone.

#### Examples

::::tabs

:::tab[YAML]
```yaml
nfs_mount_target:
  address: 123.456.789.012
```
:::

::::

### `AWSConfig`

AWS provider-specific configurations.

#### Fields

-   **`vpc_id` (str | None)**: The VPC ID.
-   **`subnet_ids` (List\[str\] | None)**: List of subnet IDs.
-   **`zones` (List\[str\] | None)**: The availability zone corresponding to each subnet ID.
-   **`security_group_ids` (List\[str\] | None)**: List of security group IDs.
-   **`anyscale_iam_role_id` (str | None)**: The Anyscale IAM role ARN.
-   **`external_id` (str | None)**: The trust policy external ID for the cross-account IAM role
-   **`cluster_iam_role_id` (str | None)**: The IAM role ARN used by Ray clusters.
-   **`cluster_instance_profile_id` (str | None)**: The IAM instance profile ARN attached to Ray cluster nodes. Defaults to the instance profile with the same name as the `cluster_iam_role_id` role. Set this explicitly when your IAM tooling generates a profile name that differs from the role name.
-   **`memorydb_cluster_name` (str | None)**: The MemoryDB cluster name.
-   **`memorydb_cluster_arn` (str | None)**: The MemoryDB cluster ARN.
-   **`memorydb_cluster_endpoint` (str | None)**: The MemoryDB cluster endpoint.
-   **`cloudformation_id` (str | None)**: The CloudFormation stack ID, for Anyscale-managed resources.

#### Examples

::::tabs

:::tab[YAML]
```yaml
aws_config:
  vpc_id: vpc-12345678901234567
  subnet_ids:
    - subnet-11111111111111111
    - subnet-22222222222222222
  security_group_ids:
    - sg-12345678901234567
  anyscale_iam_role_id: arn:aws:iam::123456789012:role/anyscale-iam-role
  cluster_iam_role_id: arn:aws:iam::123456789012:role/cluster-node-role
  cluster_instance_profile_id: arn:aws:iam::123456789012:instance-profile/cluster-node-profile
  memorydb_cluster_name: my-memorydb-cluster
```
:::

::::

### `GCPConfig`

GCP provider-specific configurations.

#### Fields

-   **`project_id` (str | None)**: The GCP project ID.
-   **`host_project_id` (str | None)**: The host project ID for shared VPCs.
-   **`provider_name` (str | None)**: Workload Identity Federation provider name for Anyscale access.
-   **`vpc_name` (str | None)**: VPC name.
-   **`subnet_names` (List\[str\] | None)**: List of GCP subnet names.
-   **`firewall_policy_names` (List\[str\] | None)**: List of GCP firewall policy names.
-   **`anyscale_service_account_email` (str | None)**: The Anyscale service account email.
-   **`cluster_service_account_email` (str | None)**: The service account email attached to Ray clusters.
-   **`memorystore_instance_name` (str | None)**: The Memorystore instance name.
-   **`memorystore_endpoint` (str | None)**: The Memorystore instance endpoint.
-   **`deployment_manager_id` (str | None)**: The deployment manager deployment ID, for Anyscale-managed resources.

#### Examples

::::tabs

:::tab[YAML]
```yaml
gcp_config:
  project_id: my-project
  provider_name: projects/123456789012/locations/global/workloadIdentityPools/my-cloud/providers/my-provider
  vpc_name: my-vpc
  subnet_names:
    - my-subnet
  firewall_policy_names:
    - my-firewall-policy
  anyscale_service_account_email: my-anyscale-service-account@my-project.iam.gserviceaccount.com
  cluster_service_account_email: my-cluster-service-account@my-project.iam.gserviceaccount.com
  memorystore_instance_name: my-memorystore-instance
```
:::

::::

### `KubernetesConfig`

Kubernetes stack configurations.

#### Fields

-   **`anyscale_operator_iam_identity` (str | None)**: The cloud provider IAM identity federated with the Anyscale Operator's Kubernetes service account, which will be used by Anyscale control plane for validation during Anyscale Operator bootstrap in the dataplane. IN AWS EKS, this is the ARN of the IAM role. For GCP GKE, this is the service account email.
-   **`zones` (List\[str\] | None)**: List of zones to launch pods in.

#### Examples

::::tabs

:::tab[YAML]
```yaml
kubernetes_config:
  anyscale_operator_iam_identity: arn:aws:iam::123456789012:role/anyscale-operator-role
  zones:
    - us-west-2a
    - us-west-2b
    - us-west-2c
```
:::

::::

---

Previous: [Aggregated instance usage](/reference/sdk/aggregated-instance-usage.md) | Next: [Compute config](/reference/sdk/compute-config.md)