feat(api): Add blkio cgroup tuning via --blkio flag

[chrisgeo]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Closes #1512.

Use case

Docker Compose exposes block-I/O tuning through service.blkio_config
(weights, weight-per-device, and read/write bps/iops throttles). Compose
translators such as container-compose can parse the field today, but they
must warn-skip it on apple/container because there is no runtime flag
surface for it — blkio_config: silently degrades into an unconfigured
container. This PR adds the missing surface so:

1. container-compose (and other compose translators) can pass
   service.blkio_config straight through to container run /
   container create without dropping fields.
2. Operators tuning noisy-neighbor / IO-bound workloads (databases,
   build steps, log shippers sharing a host disk) can apply BFQ-style
   weights and per-device throttles directly from the CLI, matching the
   docker run --blkio-weight* / --device-{read,write}-{bps,iops}
   ergonomics they already know.
3. The cgroup blockIO config flows through the runtime data path so a
   future podman-style translator or higher-level orchestrator gets the
   same plumbing for free.

CLI shape

Per the grouped, repeatable key=value form proposed in
#1512 (comment) (lives under MANAGEMENT OPTIONS, not
RESOURCE OPTIONS, to keep the resource help wall short):

container run --blkio weight=500 ...
container run --blkio device=/dev/sda,weight=700,leaf-weight=300 ...
container run --blkio device=/dev/sda,read-bps=1048576,write-bps=1048576 ...
container run --blkio device=/dev/sda,read-iops=1000,write-iops=1000 ...

device= accepts an absolute host path (resolved via stat(2) for
major/minor) or a literal <major>:<minor>. Per-device keys: weight,
leaf-weight, read-bps, write-bps, read-iops, write-iops. Global
keys (no device=): weight, leaf-weight. The parser rejects unknown
keys, conflicting global weights, and global-only keys mixed onto
device-less specs.

Runtime plumbing

To keep OS-specific options out of the cross-platform container config,
blockIO is carried as opaque runtime data, not on
ContainerConfiguration.Resources:

• CLI (ContainerRun / ContainerCreate) calls Parser.blockIO(specs:),
  wraps the result in LinuxRuntimeData(blockIO:), JSON-encodes it, and
  passes it as runtimeData to ContainerClient.create.
• RuntimeService.bootstrap reads RuntimeConfiguration.runtimeData
  from disk and threads it into configureContainer, which decodes
  LinuxRuntimeData and applies czConfig.blockIO (a
  Containerization.LinuxBlockIO, the Sendable wrapper around the OCI
  type).

Dependency

Depends on apple/containerization#739, which introduces
Containerization.LinuxBlockIO and wires it into
LinuxContainer.Configuration. While #739 is unmerged this branch pins
containerization to its branch
(full-chaos/containerization@feat/chaos-1380-blkio-runtime,
revision 3d009df). Before merge, the pin moves back to
apple/containerization at whatever revision lands #739.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

swift build clean, swift test --filter ParserTest passes
(105 tests, 5 new) — tests call Parser.blockIO directly now that the
field is no longer on Resources:

• testResourcesBlockIOFlags — combined global + per-device + throttle
• testResourcesBlockIOAcceptsMajorMinorLiteral — device=8:0 literal
• testResourcesRejectsInvalidBlockIOWeight — weight outside 10..1000
• testResourcesRejectsUnknownBlockIOKey — typo detection
• testResourcesRejectsGlobalKeyOnDeviceSpec — read-bps without device=

RuntimeConfigurationTests pass (runtime-data round-trip).
container run --help confirmed renders the new --blkio flag under
MANAGEMENT OPTIONS.

[chrisgeo]

Pushed 5d11a29 addressing review feedback.

1. blockIO no longer lives on ContainerConfiguration

Per the suggestion on ContainerConfiguration.swift, the field is now on LinuxRuntimeData and is carried opaquely through RuntimeConfiguration.runtimeData:

• CLI (ContainerRun / ContainerCreate) calls Parser.blockIO(specs:), wraps the result in LinuxRuntimeData(blockIO:), JSON-encodes it, and passes it as runtimeData to ContainerClient.create.
• RuntimeService.bootstrap reads RuntimeConfiguration.runtimeData from disk and threads it into configureContainer, which decodes LinuxRuntimeData and applies czConfig.blockIO.
• ContainerConfiguration.Resources.blockIO is removed; Parser.resources no longer takes blkio.

This keeps OS-specific options out of the generic container config type, as you described.

2. --blkio reshaped as options under Flags.Management

• The flag moved from Flags.Resource to Flags.Management (it shows up under MANAGEMENT OPTIONS in container run --help now).
• Help text collapsed to a single line: Block I/O cgroup tuning options (Linux only; see command reference for the supported keys). The detailed key/value schema will live in the command reference doc rather than the help wall.
• The structured key=value parsing in Parser.blockIO is unchanged, so existing behavior is preserved.

3. Tests

swift test --filter ParserTest — 105 tests pass, including the 5 blkio cases (now rewired to call Parser.blockIO directly since the field is gone from Resources). RuntimeConfigurationTests also still pass.

Deferred cleanup

The three self-review notes on Package.swift, Package.resolved, and .gitignore are intentionally left for now:

• Package.swift / Package.resolved still pin to the containerization#739 branch because that upstream PR is still open. They will revert to apple/containerization at whatever revision lands [container-run-create]: add support for --network none #739, as the PR description notes.
• .gitignore shows no diff against main on the current branch, so there is nothing to revert there — flagging in case I'm missing something on your end.