# Storage Options for Container Volumes in Apple Container: A Complete Guide

> Explore Apple Container storage options for volumes. Learn about named/anonymous types, size limits, ext4 journaling, and driver-specific configurations in this complete guide.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-14

---

**Container volumes in the Apple Container framework support named and anonymous storage types, configurable size limits via the `-s` flag or `--opt size=`, three ext4 journaling modes (ordered, writeback, journal), and driver-specific options passed through `--opt` key-value pairs.**

The Apple Container framework provides flexible storage configuration for container workloads through its comprehensive volume management system. Understanding the available storage options for container volumes allows you to optimize persistence, performance, and capacity limits according to your application's specific requirements. This guide examines the implementation details found in the `apple/container` repository, including validation logic in [`VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/VolumeConfiguration.swift) and service handlers in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift).

## Volume Types: Named and Anonymous Storage

The framework distinguishes between two fundamental persistence models based on how the volume identifier is assigned during creation.

### Named Volumes

Named volumes receive explicit user-defined identifiers specified during creation. These identifiers must conform to the regex pattern defined in `VolumeStorage.volumeNamePattern` within [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift), permitting alphanumerics, hyphens, underscores, periods, and leading digits while prohibiting spaces or slashes. Invalid names trigger a `VolumeError.invalidVolumeName` error during validation in [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift).

### Anonymous Volumes

Anonymous volumes are generated automatically when using bind-mount syntax without specifying a name, such as `-v /path`. The system assigns a UUID-based identifier with the format `anon-{36-char-uuid}`, ensuring unique storage allocation without manual naming overhead.

## Configuring Volume Size and Capacity Limits

Storage capacity can be enforced at creation time through multiple mechanisms that override driver defaults.

### Explicit Size Configuration

Use the `-s <size>` flag to set a maximum volume size in bytes, with optional suffixes including `K`, `M`, `G`, `T`, or `P`. This value overrides any driver-specific `size=` option passed via `--opt`. According to [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), the size parameter accepts human-readable formats to simplify capacity planning across different storage backends.

### Default Volume Size Behavior

When no size is specified, the service falls back to `VolumeStorage.defaultVolumeSizeBytes`, defined in the configuration layer of [`Sources/ContainerResource/Volume/VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Volume/VolumeConfiguration.swift). This default ensures consistent baseline storage allocation across anonymous and unnamed volume creations handled in [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift).

## Filesystem Journaling Modes

For ext4-based storage drivers, the framework exposes kernel-level journaling controls that impact durability and performance characteristics.

### Available Journaling Modes

The system supports three journaling modes defined in the command reference:

- **ordered**: Journals metadata only, ensuring data is written before metadata (default for most ext4 implementations)
- **writeback**: Journals metadata but provides no ordering guarantees for data writes, offering higher performance with reduced safety guarantees
- **journal**: Full data and metadata journaling, providing maximum durability at the cost of write performance

### Journal Size Tuning

Each journaling mode can be combined with an explicit journal size using the syntax `mode:size`, such as `writeback:64m`. This allows fine-grained control over the journal buffer allocation within the ext4 filesystem structure.

## Driver-Specific Options and Validation

Beyond basic size and type configuration, the framework accepts arbitrary driver parameters and enforces strict naming conventions through compile-time constants.

### Custom Driver Options

Pass additional driver-specific flags using the `--opt <key>=<value>` syntax. For example, `--opt size=10g` provides an alternative to the `-s` flag, while other drivers may accept unique parameters for encryption, caching, or block size configuration. These options are processed in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) during the volume creation workflow.

### Volume Name Validation

The validation logic in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) enforces that all named volumes match the `VolumeStorage.volumeNamePattern` regular expression. Names containing spaces, slashes, or special characters will fail validation with a `VolumeError.invalidVolumeName` error before the storage allocation process begins.

## Practical Configuration Examples

The following examples demonstrate common storage configurations using the `container` CLI.

Create a named volume with 10 GiB capacity and ordered journaling:

```bash
container volume create \
    --opt size=10g \
    --opt journal=ordered \
    mydata-volume

```

Create an anonymous volume automatically during container runtime:

```bash
container run -v /host/path:/container/path myimage

```

Configure a high-performance volume with writeback journaling and a 64 MiB journal:

```bash
container volume create \
    --opt journal=writeback:64m \
    fast-cache

```

Inspect volume details including size and journaling configuration:

```bash
container volume inspect mydata-volume

```

List all volumes with JSON formatting to view storage parameters:

```bash
container volume list --format json

```

## Summary

- **Volume types**: Choose between persistent **named volumes** with custom identifiers or temporary **anonymous volumes** with auto-generated UUID-based names like `anon-{36-char-uuid}`.
- **Size management**: Configure capacity using the `-s` flag or `--opt size=`, with automatic fallback to `VolumeStorage.defaultVolumeSizeBytes` when unspecified.
- **Journaling control**: Select ext4 journaling modes (`ordered`, `writeback`, `journal`) and tune journal buffer sizes for specific durability and performance requirements.
- **Validation rules**: Ensure volume names comply with `VolumeStorage.volumeNamePattern` in [`VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/VolumeConfiguration.swift) to avoid `VolumeError.invalidVolumeName` errors during creation.
- **Driver flexibility**: Pass arbitrary driver options via `--opt` key-value pairs to customize underlying storage behavior beyond standard parameters.

## Frequently Asked Questions

### What is the difference between named and anonymous container volumes?

Named volumes are created with explicit user-defined identifiers that persist across container restarts, while anonymous volumes are automatically generated with UUID-based names when using bind-mount syntax without specifying a name. Named volumes must pass validation against `VolumeStorage.volumeNamePattern` in [`VolumeConfiguration.swift`](https://github.com/apple/container/blob/main/VolumeConfiguration.swift), whereas anonymous volumes bypass manual naming requirements entirely.

### How do I set a maximum size for a container volume?

Specify the size using the `-s` flag followed by a byte value with optional suffixes (K, M, G, T, P), or use `--opt size=<value>` for driver-specific sizing. For example, `container volume create -s 10g myvolume` allocates 10 gigabytes. If no size is provided, the system defaults to `VolumeStorage.defaultVolumeSizeBytes` as implemented in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift).

### Which journaling mode should I use for container volumes?

Choose **ordered** for balanced safety and performance (metadata journaling with data ordering guarantees), **writeback** for maximum write performance when data durability is less critical, or **journal** for full data and metadata journaling when absolute consistency is required. These modes are implemented in the ext4-based storage driver and can be combined with explicit journal sizes like `journal:64m`.

### What characters are allowed in volume names?

Volume names must match the regex pattern `VolumeStorage.volumeNamePattern`, which permits alphanumeric characters, hyphens, underscores, periods, and leading digits. Spaces, slashes, and special symbols are prohibited. Invalid names trigger a `VolumeError.invalidVolumeName` error during the validation phase in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) before any storage allocation occurs.