Volume Management Options for Apple Containers: Creating, Mounting, and Managing Persistent Storage

Apple Containers provide comprehensive volume management capabilities through the container CLI and Container API, supporting named and anonymous volumes with options for creation, inspection, mounting, and pruning.

The apple/container repository implements a robust storage subsystem that handles persistent data for containers through Swift-based services. Understanding the volume management options for Apple containers enables developers to efficiently provision storage, enforce naming conventions, and reclaim unused space. The implementation spans client-side parsing logic, server-side XPC services, and validation utilities written in Swift.

Creating Named and Anonymous Volumes

Volumes in Apple containers can be provisioned explicitly as named volumes or generated automatically as anonymous volumes when mounting without a source.

Named Volume Creation

Create explicit named volumes using the container volume create command with optional labels, driver-specific options, and size constraints:

container volume create [--label <label> …] [--opt <opt> …] [-s <size>] <name>

The command accepts three key parameters:

• --label <label> – Attach metadata key-value pairs to the volume.
• --opt <opt> – Specify driver-specific options such as journal=ordered.
• -s <size> – Set initial size with byte suffixes (K, M, G, T, P).

The creation logic resides in Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift (lines 317-395), which handles validation and storage allocation. Driver options are parsed in VolumesHarness.swift (lines 45-48), defaulting to the "local" driver if omitted.

Anonymous Volume Generation

When running containers with mount points that lack explicit source paths, the system auto-generates anonymous volumes. The VolumeStorage.generateAnonymousVolumeName() function in Sources/ContainerResource/Volume/VolumeConfiguration.swift (lines 52-56) creates UUID-based names prefixed with anon-.

container run -v /data image:latest  # Creates anon-<uuid> automatically

Mounting Volumes at Container Runtime

Bind volumes into running containers using the -v or --volume flag, or the more verbose --mount syntax. The CLI parser in Sources/Services/ContainerAPIService/Client/Parser.swift (lines 447-523) handles both formats through Parser.volumes and Parser.mount.

# Mount named volume

container run -v mydata:/var/lib/app image:latest

# Mount with read-only restriction

container run -v mydata:/var/lib/app:ro image:latest

# Host path bind (creates anonymous volume)

container run -v /host/path:/data image:latest

Listing, Inspecting, and Deleting Volumes

The volume lifecycle management commands provide complete visibility and control over persistent storage assets.

Core Management Commands

• container volume list [-q|--quiet] – Display all volumes; use -q to return only names.
• container volume inspect <name> – Output JSON details for specific volumes, including mount points, labels, and usage statistics.
• container volume delete <name> … – Remove specific volumes; blocked if referenced by running containers.
• container volume prune – Delete all volumes with no container references and report reclaimed space.

These operations are implemented in Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift (lines 30-250) and exposed via the XPC bridge in VolumesHarness.swift.

Disk Usage Reporting and Storage Metrics

Monitor storage consumption using the system disk-free command. The container system df utility reports total, active, and reclaimable space for volumes through VolumesService.calculateDiskUsage() in Sources/Services/ContainerAPIService/Server/DiskUsage/DiskUsageService.swift (lines 46-68).

container system df

Volume Naming Rules and Validation

Apple containers enforce strict naming conventions through VolumeStorage.isValidVolumeName in Sources/ContainerResource/Volume/VolumeConfiguration.swift (lines 38-45).

Validation requirements:

• Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
• Maximum length: 255 characters
• Must start with alphanumeric character

Default configuration:

• Default size: 512 GB (VolumeStorage.defaultVolumeSizeBytes in lines 38-40)
• Anonymous naming: Lowercase UUID strings

Driver Support and Configuration Options

The current implementation supports only the local driver. Attempting to specify unsupported drivers triggers VolumeError.driverNotSupported (lines 28-33 in VolumeConfiguration.swift).

Configure volume behavior using --opt key-value pairs passed during creation:

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

Complete Volume Management Example

The following workflow demonstrates the full volume lifecycle:

# Create a 10GiB volume with specific journaling options

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

# Run container with volume mounted read-only

container run \
    -v mydata:/var/lib/app:ro \
    ghcr.io/example/app:latest

# Inspect volume configuration

container volume inspect mydata

# Clean up unused volumes

container volume prune

Summary

• Apple containers provide comprehensive volume management through the container CLI and underlying Swift services in the apple/container repository.
• Named volumes are created explicitly via container volume create with support for labels, size constraints, and driver options, while anonymous volumes generate UUID-based names automatically.
• Validation rules enforce alphanumeric naming with 255-character limits, and storage defaults begin at 512 GB unless overridden.
• Lifecycle management includes listing, inspecting, deleting, and pruning operations implemented in VolumesService.swift and VolumesHarness.swift.
• Disk usage is tracked through calculateDiskUsage() in DiskUsageService.swift, accessible via container system df.
• Only the local driver is currently supported, with configuration passed through --opt parameters.

Frequently Asked Questions

How do I create a volume with a specific size in Apple containers?

Use the -s flag with size suffixes. For example, container volume create -s 10g myvolume creates a 10-gigabyte volume. The size parser accepts K, M, G, T, and P suffixes. The default size is 512 GB as defined in VolumeStorage.defaultVolumeSizeBytes in Sources/ContainerResource/Volume/VolumeConfiguration.swift.

What happens when I delete a volume that is currently in use?

The container volume delete command blocks removal if the volume is referenced by any running or stopped containers. You must stop and remove dependent containers before deleting the volume. This safety check is implemented in VolumesService.swift to prevent data loss.

Can I use custom storage drivers with Apple containers?

No. Currently, only the local driver is supported. The VolumesHarness defaults to "local" if no driver is specified, and attempting to use an unsupported driver raises VolumeError.driverNotSupported as defined in VolumeConfiguration.swift. Custom driver support may be added in future releases.

How do I identify which volumes are consuming the most disk space?

Run container system df to see total, active, and reclaimable space across all volumes. For detailed JSON output of specific volumes, use container volume inspect <name>, which includes size and usage metadata calculated by DiskUsageService.swift.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}