> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airshipci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Disks

> Sizing the root volume, raising throughput, and attaching extra or existing disks.

The default root volume is 75 GiB. For most CI that is enough space and not
enough **throughput** — a fast instance on a default volume spends its life
waiting on I/O. Raising throughput is usually the cheapest speed-up available.

## AWS

One `BlockDeviceMappings` entry configures the root volume.

```yaml theme={null}
extra_config:
  BlockDeviceMappings:
    - VolumeSize: 100
      VolumeType: gp3
      Iops: 6000
      Throughput: 1000
```

| Key | Accepts |
| - | - |
| `VolumeSize` | 8–16384 GiB. Default 75 |
| `VolumeType` | `gp2`, `gp3`, `io1`, `io2`. Default `gp2` |
| `Iops` | gp3: 3000–16000. io1 and io2: required. Not valid for gp2 |
| `Throughput` | gp3 only, 125–1000 MiB/s |
| `VolumeInitializationRate` | 100–300 MiB/s, for snapshot-backed AMIs |

> [!WARNING]
>
> `Throughput` may be at most a quarter MiB/s per IOPS, so `Throughput: 1000`
> needs `Iops: 4000` or more. Combinations EC2 would refuse are **config
> errors**, caught by the checker, rather than failed launches an hour later.

`DeviceName` is accepted and ignored — the AMI's own root device is always the
one sized. Volumes are always encrypted.

> [!TIP]
>
> gp3 defaults to 125 MiB/s whatever its size. On a cache-enabled runner that
> caps restores well below what the network can do, so `Throughput: 1000` with
> `Iops: 6000` is the usual starting point. [Caching](https://docs.airshipci.com/performance/caching.md)

## Google Cloud

Three keys, for three different jobs.

```yaml theme={null}
extra_config:
  baseDisk:
    diskSizeGb: 100
    diskType: pd-ssd
```

**baseDisk** `mapping`

The **boot disk**. `diskSizeGb` 10–65536, default 75. `diskType`
`pd-balanced` (the default), `pd-ssd`, or a `zones/.../diskTypes/...` path.

**additionalDisk** `mapping`

An **empty second disk**, attached raw — the job formats and mounts it.
Takes the same `diskSizeGb` and `diskType`. A `diskType` written as a zonal
path is read for its type only; the disk is created in whichever zone the
runner lands in.

**existingDisk** `mapping`

A disk **you already have**. `source` (`projects/P/zones/Z/disks/N`, or
`regions/R/disks/N` for a regional disk), optional `deviceName`, `mode`
(`READ_WRITE` by default, or `READ_ONLY`) and `interface` (`SCSI`, `NVME`).
`type` and `diskSizeGb` are accepted and ignored, since the disk exists.

```yaml theme={null}
extra_config:
  additionalDisk: {diskSizeGb: 500, diskType: pd-ssd}
  existingDisk:
    source: projects/my-project/zones/us-central1-b/disks/shared-fixtures
    mode: READ_ONLY
```

An existing disk is **never deleted** with the machine. Two things follow:

* A **zonal** disk pins the runner to its zone, so a `region:` that says
  otherwise is a config error.
* A `READ_WRITE` disk fits one machine at a time. While another runner holds
  it, launches fail as retryable and the job waits its turn — which is a
  usable way to serialise jobs that share state, if you want that.

## Azure

```yaml theme={null}
extra_config:
  storageProfile:
    osDisk:
      diskSizeGB: 100
      managedDisk:
        storageAccountType: Premium_LRS
```

| Key | Accepts |
| - | - |
| `osDisk.diskSizeGB` | 30–4095. Default 75 for Linux; for Windows, the image's own size |
| `osDisk.managedDisk.storageAccountType` | `Standard_LRS`, `StandardSSD_LRS`, `Premium_LRS`, … Default: the image's own |

Managed disks are encrypted by Azure with platform-managed keys, and the OS
disk is deleted with the machine.

## Sizing it

> **Space: count your biggest job**
>
> Checkout, dependency cache, build output, container images and layers.
> Docker-heavy builds are the usual surprise.

> **Throughput: raise it first**
>
> Before more cores. A restore that saturates 1 GiB/s of network still lands
> on a 125 MiB/s disk unless you say otherwise.

> **Keep large scratch off the root**
>
> On Google Cloud, `additionalDisk` gives the job a clean raw disk to format
> and throw away with the machine.

> **Bake, do not download**
>
> An image with your toolchain and base containers already on it beats any
> disk setting. [Custom images](https://docs.airshipci.com/performance/custom-images.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.