Storage resources

This page is the schema reference for Rune's storage resources. For the big-picture model and the lifecycle, see the storage concept.

StorageClass

Cluster-scoped. Names a driver and default parameters.

storageClass:
  name: do-nyc3
  driver: do-volume
  parameters:
    region: nyc3
    fsType: ext4
    apiTokenSecretRef: do/api-token
  reclaimPolicy: retain
  default: false
  allowedTopologies:
    - matchLabels:
        rune.io/region: nyc3
    - matchExpressions:
        - key: rune.io/zone
          operator: In
          values: [nyc3a, nyc3b]
  labels:
    tier: cloud

TopologySelector is a list of matchLabels and/or matchExpressions (operators: In, NotIn, Exists, DoesNotExist).

Secret references in parameters

Any value in a StorageClass or Volume parameters map may be a secret: reference instead of a literal. The controller resolves the reference against the secrets store before the driver sees it, so drivers always receive plaintext.

storageClass:
  name: do-nyc3
  driver: do-volume
  parameters:
    region: nyc3
    # FQDN: pinned to a specific namespace — recommended for
    # cluster-scoped StorageClasses since one shared secret serves
    # every namespace's volumes.
    apiToken: secret:do-api-token.shared.rune/token

Form: secret:<name>[.<namespace>.rune]/<key>. Values without the secret: prefix pass through verbatim. A missing secret or key fails the operation with InvalidParameters.

Shorthand vs FQDN — important for StorageClass

The shorthand form secret:<name>/<key> (no namespace) is resolved against the consuming Volume's namespace, not the StorageClass's. Since StorageClass is cluster-scoped, a single class with a shorthand ref will look up the secret in whichever namespace happens to be using the class at that moment — so every namespace would need its own copy of the secret. For shared infrastructure tokens (DO API token, S3 credentials, etc.) use the FQDN form to pin the lookup to one namespace regardless of which Volume triggered the operation. Shorthand is fine on Volume.parameters overrides (the Volume already has its own namespace).

Volume

Namespaced. A unit of durable storage.

volume:
  name: pgdata-postgres-0
  namespace: prod
  storageClassName: local
  size: 10Gi
  accessMode: ReadWriteOnce
  reclaimPolicy: retain
  parameters: {}
  labels:
    app: postgres

Driver-specific parameters

local

local-host

do-volume

Required DigitalOcean token scopes

A Full Access token works, but the driver only needs the following custom scopes. These mirror exactly the eight HTTP endpoints the driver calls (pkg/storage/driver/dovolume/client.go); anything else is over-privileged.

The driver does not call /v2/regions, /v2/sizes, or update the volume metadata, so regions:read, sizes:read, and block_storage:update are not needed despite what the DO console's default scope hints sometimes suggest.

Region pinning

DO block-storage volumes belong to a single region. The driver provisions in the region named on the StorageClass, and DO refuses to attach a volume to a droplet in a different region. For a multi-region cluster, create one StorageClass per region:

storageClass:
  name: do-volumes-nyc3
  driver: do-volume
  parameters: { region: nyc3, fsType: ext4, apiTokenSecretRef: shared/do-api-token }
---
storageClass:
  name: do-volumes-fra1
  driver: do-volume
  parameters: { region: fra1, fsType: ext4, apiTokenSecretRef: shared/do-api-token }

Use allowedTopologies (RUNE-072) or the namespace scoping of your StorageClass references to keep claims targeted at the right region.

hcloud-volume

The driver calls the following Hetzner Cloud API endpoints:

Capabilities:

• Snapshots: false — Hetzner Cloud has no volume-snapshot API. Writes to Snapshot against an hcloud-volume class are rejected at cast time.
• Expand: true, OnlineExpand: false — rune volume resize works but the volume must be unbound first.
• BlockDevice: true — the driver formats the volume on first mount and exposes the underlying block device at /dev/disk/by-id/scsi-0HC_Volume_<id>.

aws-ebs

The driver reads AWS credentials from the standard chain (instance role first), so the recommended setup attaches an instance profile to the node and configures no credentials on the StorageClass. The terraform-aws-rune module does this by default.

Required IAM permissions

The instance role (or supplied credentials) needs these EC2 actions — one row per Driver method:

The managed policy AmazonEBSCSIDriverPolicy is a convenient superset of the above (it scopes some actions with conditions on the ebs.csi.aws.com/cluster tag — fine since the driver tags its volumes). terraform-aws-rune's enable_ebs_volume_access attaches a scoped inline policy instead.

Capabilities:

• Snapshots: true — EBS snapshot API.
• Expand: true, OnlineExpand: true — rune volume resize grows the volume in place via ModifyVolume while it stays attached. The filesystem is grown on the next mount.
• BlockDevice: true — the driver formats on first mount and resolves the device via the stable by-id symlink /dev/disk/by-id/nvme-Amazon_Elastic_Block_Store_<vol-id-no-dash> (Nitro instances).

Node → instance resolution

Attach/Detach map a Rune node onto an EC2 instance by the node's OS hostname, tried in order: an i-… instance ID, the private-dns-name (EC2 default hostname, matched exactly and as <name>.*), then the Name tag. An ambiguous match (two instances) is an error — keep hostnames / Name tags unique.

gce-pd

The driver reads credentials from Application Default Credentials (the instance service account first), so the recommended setup attaches a service account to the node and configures no credentials on the StorageClass. The terraform-google-rune module does this when enable_pd_csi_access = true.

Required IAM permissions

The service account (or supplied key) needs the Compute permissions the driver calls — bundled by roles/compute.storageAdmin, or a custom role with:

Capabilities:

• Snapshots: true — GCE disk snapshots (global resources).
• Expand: true, OnlineExpand: true — rune volume resize grows the disk in place via disks.resize while attached. The filesystem is grown on the next mount.
• BlockDevice: true — the driver formats on first mount and resolves the device via the stable by-id symlink /dev/disk/by-id/google-<diskName> (the disk is attached with DeviceName == <diskName>).

Node → instance resolution

Attach/Detach map a Rune node onto a GCE instance by the node's OS hostname, which on GCE equals the instance name (compute.instances.get in the StorageClass zone). A name mismatch surfaces as no GCE instance "<host>" in zone <zone> on the first Attach.

Status fields (read-only)

Snapshot

Namespaced. Point-in-time copy of one volume.

snapshot:
  name: pgdata-2025-11-15
  namespace: prod
  source:
    volume: pgdata-postgres-0
  labels:
    app: postgres

The source volume's driver must advertise Capabilities.Snapshots = true — the API server rejects writes against drivers that don't (e.g. local-host).

Status fields (read-only)

Service volumes[]

Top-level field on the service spec. See also the service spec reference.

service:
  name: postgres
  scale: 3
  volumes:
    - name: pgdata
      mountPath: /var/lib/postgresql/data
      readOnly: false
      subPath: ""
      claimTemplate:
        storageClassName: local
        size: 10Gi
        accessMode: ReadWriteOnce

claim

claim:
  name: web-data            # bare name → same namespace as the service
  # name: shared.common.rune  # FQDN form → cross-namespace

Cast-time error: an RWO claim mount on a service with scale > 1. Use claimTemplate for stateful sets.

claimTemplate

claimTemplate:
  storageClassName: local           # optional; defaults to the cluster default
  size: 10Gi                        # required
  accessMode: ReadWriteOnce         # required
  parameters: {}                    # optional driver-specific overrides
  reclaimPolicy: retain             # optional override

Per-replica volumes are auto-provisioned with stable names of the form <volume-name>-<service-name>-<ordinal>, e.g. pgdata-postgres-0.

Validation

All of the following are checked at cast time and on every API write:

• Exactly one of claim / claimTemplate per mount entry.
• mountPath is absolute, unique within the service, doesn't overlap any secretMounts/configmapMounts path, and isn't in the blocklist.
• For RWO claim mounts: service.scale == 1.
• claimTemplate.accessMode is in the chosen driver's Capabilities.AccessModes.
• Snapshot writes against drivers without Capabilities.Snapshots are rejected.
• local-host hostPath is absolute, has no .., sits under runefile.[storage].hostPathAllowlist.
• Process-runtime services may use local-host only; block-device drivers (do-volume, hcloud-volume, aws-ebs, gce-pd) are rejected at cast time.
• A Volume whose reclaimPolicy: delete targets the local-host driver is rejected.

See also

• Storage concept
• Persistent storage guide
• rune volume · rune snapshot · rune storageclass