This page shows you how to attach hyperdisks to virtual machines
(VMs) in a Managed Service for Apache Spark cluster. You can configure the disks independently
for master, primary worker, and secondary worker node groups. These disks are
attached to cluster nodes in addition to the
[boot disk](https://docs.cloud.google.com/managed-spark/docs/concepts/compute/dataproc-persistent-disks) and
any [local SSDs](https://docs.cloud.google.com/managed-spark/docs/concepts/compute/dataproc-local-ssds)
attached to cluster nodes.

## Before you begin

<br />

### Required roles

Certain IAM roles are required to
run the examples on this page. Depending on organization policies, these
roles may have already been granted. To check role grants, see
[Do you need to grant roles?](https://docs.cloud.google.com/managed-spark/docs/concepts/iam#do_you_need_to_grant_roles).

For more information about granting roles, see
[Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

#### User roles


To get the permissions that
you need to create a Managed Service for Apache Spark cluster,

ask your administrator to grant you the
following IAM roles:

- [Dataproc Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/dataproc.md.txt#dataproc.editor) (`roles/dataproc.editor`) on the project
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the Compute Engine default service account


#### Service account role


To ensure that the Compute Engine default service account has the necessary
permissions to create a Managed Service for Apache Spark cluster,

ask your administrator to grant the
[Dataproc Worker](https://docs.cloud.google.com/iam/docs/roles-permissions/dataproc.md.txt#dataproc.worker) (`roles/dataproc.worker`) IAM role to the Compute Engine default service account on the project.


**Important:** You must grant this role to the Compute Engine default service account, *not* to your user account. Failure to grant the role to the correct principal might result in permission errors.

<br />

## Disk characteristics

Attached disks have the following characteristics:

- **Lifecycle**: The lifetime of an attached disk matches the lifetime of the VM that it is attached to. Managed Service for Apache Spark creates the disk when it creates the VM and deletes the disk when it deletes the VM.
- **Immutability**: You cannot update the properties of an attached disk, such as size, IOPS, or throughput, after the cluster is created.
- **Mounting and usage** : Managed Service for Apache Spark mounts disks at `/mnt/N`, where `N` is a positive integer (for example, `/mnt/1`, `/mnt/2`). HDFS and scratch data, such as shuffle outputs, use the attached disks instead of the boot persistent disk.

## Disk configuration

You can specify the following disk configuration parameters when you attach disks
to Managed Service for Apache Spark cluster nodes:

- **Disk type** - required: The type of disk to attach to VM instances.
  The following [hyperdisks](https://docs.cloud.google.com/compute/docs/disks/hyperdisks.md.txt)
  are supported:

  - `hyperdisk-balanced`
  - `hyperdisk-extreme`
  - `hyperdisk-ml`
  - `hyperdisk-throughput`

  The [`hyperdisk balanced high availability`](https://docs.cloud.google.com/compute/docs/disks/hd-types/hyperdisk-balanced-ha.md.txt)
  type and [persistent](https://docs.cloud.google.com/compute/docs/disks/persistent-disks.md.txt) disks can't be
  attached to cluster nodes.
  To attach a hyperdisk to a cluster node, the machine type used in the node must support hyperdisks. See [Machine series support for hyperdisk](https://docs.cloud.google.com/compute/docs/disks/hyperdisks.md.txt#machine-type-support).
- **Size** - optional: The size of the disk. The value must be a whole number
  followed by a `GB` for gigabyte or `TB` for terabyte. For example,
  `10GB` attaches a 10 gigabyte disk. For more information, see
  [Hyperdisk size limits](https://docs.cloud.google.com/compute/docs/disks/hyperdisks.md.txt#size-limits).

- **IOPs** - optional: Indicates the
  [IOPS](https://docs.cloud.google.com/compute/docs/disks/hyperdisks.md.txt#hd-performance-limits) to provision for
  the attached disk. This parameter sets the limit for disk I/O operations
  per second. For more information, see [Default performance levels](https://docs.cloud.google.com/compute/docs/disks/hyperdisk-performance.md.txt#default-perf).

- **Throughput** - optional: Indicates the
  [throughput](https://docs.cloud.google.com/compute/docs/disks/hyperdisks.md.txt#hd-performance-limits) to provision
  for the attached disk. This parameter sets the limit for throughput in
  `MiB` per second. For more information, see [Default performance levels](https://docs.cloud.google.com/compute/docs/disks/hyperdisk-performance.md.txt#default-perf).

## Attach disks to a cluster

You can attach disks when you
[create a Managed Service for Apache Spark cluster](https://docs.cloud.google.com/managed-spark/docs/quickstarts/create-cluster-console.md.txt#create_a_cluster)
using the gcloud CLI or the Dataproc API
to specify the disk configurations.

### gcloud CLI

- To attach disks when you create a cluster, use the
  `--master-attached-disks`, `--worker-attached-disks`, or
  `--secondary-worker-attached-disks` flag with the `gcloud dataproc
  clusters create` command.

- Each flag accepts a list of disk configurations separated by semicolons.
  Each disk configuration is a comma-separated list of key-value pairs for
  `type`, `size`, `iops`, and `throughput` (see
  [Disk configuration](https://docs.cloud.google.com/managed-spark/docs/concepts/compute/attached-disks.md.txt#disk-config)).

Example: The following command creates a cluster and attaches two hyperdisks to
each primary worker node.

```bash
gcloud dataproc clusters create CLUSTER_NAME \
    --region=REGION \
    --worker-attached-disks='type=hyperdisk-balanced,size=100GB,iops=5000,throughput=200;type=hyperdisk-throughput,size=9000GB'
```

### API

- To attach disks, include an [`attachedDiskConfigs`](https://docs.cloud.google.com/managed-spark/docs/reference/rest/v1/InstanceGroupConfig.md.txt#attacheddiskconfig) array in the
  `diskConfig` object for the `masterConfig`,
  `workerConfig`, or `secondaryWorkerConfig` instance group.

- Provide the configuration in the body of a `clusters.create` API
  request.

Example: The following JSON snippet shows an `attachedDiskConfigs` array
that attaches two hyperdisks.

> [!NOTE]
> **Note:** The `diskType` field in `attachedDiskConfigs` is deprecated. Use `type` instead.

```json
[
  {
    "type": "hyperdisk-balanced",
    "diskSizeGb": 100,
    "provisionedIops": 5000,
    "provisionedThroughput": 200
  },
  {
    "type": "hyperdisk-throughput",
    "diskSizeGb": 9000
  }
]
```