From b4c3ebfed840133249adc4bf96f316695a8068bd Mon Sep 17 00:00:00 2001 From: Raj Date: Tue, 21 Oct 2025 16:58:11 -0700 Subject: [PATCH] add volume prune command (#783) - Closes #508. ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Adds a `container volume prune` command that removes volumes with no container references and reports the amount of disk space reclaimed. This helps users clean up unused volumes and easily reclaim disk space. Also updates the `volume delete` documentation to clarify and highlight how the `--all` flag works. ## Testing - [x] Tested locally - [x] Added/updated tests - [x] Added/updated docs --- .../ContainerClient/Core/ClientVolume.swift | 14 ++ Sources/ContainerClient/Core/XPC+.swift | 1 + .../Volume/VolumeCommand.swift | 1 + .../Volume/VolumePrune.swift | 48 +++++++ .../Helpers/APIServer/APIServer+Start.swift | 1 + .../Volumes/VolumesHarness.swift | 11 ++ .../Volumes/VolumesService.swift | 74 +++++++++- .../Subcommands/Volumes/TestCLIVolumes.swift | 129 ++++++++++++++++++ docs/command-reference.md | 57 +++++++- 9 files changed, 332 insertions(+), 4 deletions(-) create mode 100644 Sources/ContainerCommands/Volume/VolumePrune.swift diff --git a/Sources/ContainerClient/Core/ClientVolume.swift b/Sources/ContainerClient/Core/ClientVolume.swift index 2d557f28..c16fce19 100644 --- a/Sources/ContainerClient/Core/ClientVolume.swift +++ b/Sources/ContainerClient/Core/ClientVolume.swift @@ -81,4 +81,18 @@ public struct ClientVolume { return try JSONDecoder().decode(Volume.self, from: responseData) } + public static func prune() async throws -> ([String], UInt64) { + let client = XPCClient(service: serviceIdentifier) + let message = XPCMessage(route: .volumePrune) + let reply = try await client.send(message) + + guard let responseData = reply.dataNoCopy(key: .volumes) else { + return ([], 0) + } + + let volumeNames = try JSONDecoder().decode([String].self, from: responseData) + let size = reply.uint64(key: .size) + return (volumeNames, size) + } + } diff --git a/Sources/ContainerClient/Core/XPC+.swift b/Sources/ContainerClient/Core/XPC+.swift index baf45291..4b94d36c 100644 --- a/Sources/ContainerClient/Core/XPC+.swift +++ b/Sources/ContainerClient/Core/XPC+.swift @@ -147,6 +147,7 @@ public enum XPCRoute: String { case volumeDelete case volumeList case volumeInspect + case volumePrune case ping diff --git a/Sources/ContainerCommands/Volume/VolumeCommand.swift b/Sources/ContainerCommands/Volume/VolumeCommand.swift index 6d0d897d..af01a65d 100644 --- a/Sources/ContainerCommands/Volume/VolumeCommand.swift +++ b/Sources/ContainerCommands/Volume/VolumeCommand.swift @@ -26,6 +26,7 @@ extension Application { VolumeDelete.self, VolumeList.self, VolumeInspect.self, + VolumePrune.self, ], aliases: ["v"] ) diff --git a/Sources/ContainerCommands/Volume/VolumePrune.swift b/Sources/ContainerCommands/Volume/VolumePrune.swift new file mode 100644 index 00000000..34ae7477 --- /dev/null +++ b/Sources/ContainerCommands/Volume/VolumePrune.swift @@ -0,0 +1,48 @@ +//===----------------------------------------------------------------------===// +// Copyright © 2025 Apple Inc. and the container project authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +//===----------------------------------------------------------------------===// + +import ArgumentParser +import ContainerClient +import Foundation + +extension Application.VolumeCommand { + public struct VolumePrune: AsyncParsableCommand { + public init() {} + public static let configuration = CommandConfiguration( + commandName: "prune", + abstract: "Remove volumes with no container references") + + @OptionGroup + var global: Flags.Global + + public func run() async throws { + let (volumeNames, size) = try await ClientVolume.prune() + let formatter = ByteCountFormatter() + let freed = formatter.string(fromByteCount: Int64(size)) + + if volumeNames.isEmpty { + print("No volumes to prune") + } else { + print("Pruned volumes:") + for name in volumeNames { + print(name) + } + print() + } + print("Reclaimed \(freed) in disk space") + } + } +} diff --git a/Sources/Helpers/APIServer/APIServer+Start.swift b/Sources/Helpers/APIServer/APIServer+Start.swift index 7422253d..da9a8412 100644 --- a/Sources/Helpers/APIServer/APIServer+Start.swift +++ b/Sources/Helpers/APIServer/APIServer+Start.swift @@ -264,6 +264,7 @@ extension APIServer { routes[XPCRoute.volumeDelete] = harness.delete routes[XPCRoute.volumeList] = harness.list routes[XPCRoute.volumeInspect] = harness.inspect + routes[XPCRoute.volumePrune] = harness.prune } } } diff --git a/Sources/Services/ContainerAPIService/Volumes/VolumesHarness.swift b/Sources/Services/ContainerAPIService/Volumes/VolumesHarness.swift index 8f2d7dcd..68a01a7a 100644 --- a/Sources/Services/ContainerAPIService/Volumes/VolumesHarness.swift +++ b/Sources/Services/ContainerAPIService/Volumes/VolumesHarness.swift @@ -92,4 +92,15 @@ public struct VolumesHarness: Sendable { reply.set(key: .volume, value: data) return reply } + + @Sendable + public func prune(_ message: XPCMessage) async throws -> XPCMessage { + let (volumeNames, size) = try await service.prune() + let data = try JSONEncoder().encode(volumeNames) + + let reply = message.reply() + reply.set(key: .volumes, value: data) + reply.set(key: .size, value: size) + return reply + } } diff --git a/Sources/Services/ContainerAPIService/Volumes/VolumesService.swift b/Sources/Services/ContainerAPIService/Volumes/VolumesService.swift index 4e8a6e45..1ff59258 100644 --- a/Sources/Services/ContainerAPIService/Volumes/VolumesService.swift +++ b/Sources/Services/ContainerAPIService/Volumes/VolumesService.swift @@ -72,6 +72,77 @@ public actor VolumesService { } } + public func prune() async throws -> ([String], UInt64) { + try await lock.withLock { _ in + let allVolumes = try await self.store.list() + + // do entire prune operation atomically with container list + return try await self.containersService.withContainerList { containers in + var inUseSet = Set() + for container in containers { + for mount in container.configuration.mounts { + if mount.isVolume, let volumeName = mount.volumeName { + inUseSet.insert(volumeName) + } + } + } + + let volumesToPrune = allVolumes.filter { volume in + !inUseSet.contains(volume.name) + } + + var prunedNames = [String]() + var totalSize: UInt64 = 0 + + for volume in volumesToPrune { + do { + // calculate actual disk usage before deletion + let volumePath = self.volumePath(for: volume.name) + let actualSize = self.calculateDirectorySize(at: volumePath) + + try await self.store.delete(volume.name) + try self.removeVolumeDirectory(for: volume.name) + + prunedNames.append(volume.name) + totalSize += actualSize + self.log.info("Pruned volume", metadata: ["name": "\(volume.name)", "size": "\(actualSize)"]) + } catch { + self.log.error("Failed to prune volume \(volume.name): \(error)") + } + } + + return (prunedNames, totalSize) + } + } + } + + private nonisolated func calculateDirectorySize(at path: String) -> UInt64 { + let url = URL(fileURLWithPath: path) + let fileManager = FileManager.default + + guard + let enumerator = fileManager.enumerator( + at: url, + includingPropertiesForKeys: [.totalFileAllocatedSizeKey], + options: [.skipsHiddenFiles] + ) + else { + return 0 + } + + var totalSize: UInt64 = 0 + for case let fileURL as URL in enumerator { + guard let resourceValues = try? fileURL.resourceValues(forKeys: [.totalFileAllocatedSizeKey]), + let fileSize = resourceValues.totalFileAllocatedSize + else { + continue + } + totalSize += UInt64(fileSize) + } + + return totalSize + } + private func parseSize(_ sizeString: String) throws -> UInt64 { let measurement = try Measurement.parse(parsing: sizeString) let bytes = measurement.converted(to: .bytes).value @@ -162,7 +233,8 @@ public actor VolumesService { format: "ext4", source: blockPath(for: name), labels: labels, - options: driverOpts + options: driverOpts, + sizeInBytes: sizeInBytes ) try await store.create(volume) diff --git a/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift b/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift index 7746dad0..49f83379 100644 --- a/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift +++ b/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift @@ -18,6 +18,7 @@ import ContainerClient import Foundation import Testing +@Suite(.serialized) class TestCLIVolumes: CLITest { func doVolumeCreate(name: String) throws { @@ -323,4 +324,132 @@ class TestCLIVolumes: CLITest { #expect(status2 == 0, "second container should succeed") } + + @Test func testVolumePruneNoVolumes() throws { + // Prune with no volumes should succeed with 0 reclaimed + let (output, error, status) = try run(arguments: ["volume", "prune"]) + if status != 0 { + throw CLIError.executionFailed("volume prune failed: \(error)") + } + + #expect(output.contains("0 B") || output.contains("No volumes to prune"), "should show no space reclaimed or no volumes message") + } + + @Test func testVolumePruneUnusedVolumes() throws { + let testName = getTestName() + let volumeName1 = "\(testName)_vol1" + let volumeName2 = "\(testName)_vol2" + + // Clean up any existing resources from previous runs + doVolumeDeleteIfExists(name: volumeName1) + doVolumeDeleteIfExists(name: volumeName2) + + defer { + doVolumeDeleteIfExists(name: volumeName1) + doVolumeDeleteIfExists(name: volumeName2) + } + + try doVolumeCreate(name: volumeName1) + try doVolumeCreate(name: volumeName2) + let (listBefore, _, statusBefore) = try run(arguments: ["volume", "list", "--quiet"]) + #expect(statusBefore == 0) + #expect(listBefore.contains(volumeName1)) + #expect(listBefore.contains(volumeName2)) + + // Prune should remove both + let (output, error, status) = try run(arguments: ["volume", "prune"]) + if status != 0 { + throw CLIError.executionFailed("volume prune failed: \(error)") + } + + #expect(output.contains(volumeName1) || !output.contains("No volumes to prune"), "should prune volume1") + #expect(output.contains(volumeName2) || !output.contains("No volumes to prune"), "should prune volume2") + #expect(output.contains("Reclaimed"), "should show reclaimed space") + + // Verify volumes are gone + let (listAfter, _, statusAfter) = try run(arguments: ["volume", "list", "--quiet"]) + #expect(statusAfter == 0) + #expect(!listAfter.contains(volumeName1), "volume1 should be pruned") + #expect(!listAfter.contains(volumeName2), "volume2 should be pruned") + } + + @Test func testVolumePruneSkipsVolumeInUse() throws { + let testName = getTestName() + let volumeInUse = "\(testName)_inuse" + let volumeUnused = "\(testName)_unused" + let containerName = "\(testName)_c1" + + // Clean up any existing resources from previous runs + doVolumeDeleteIfExists(name: volumeInUse) + doVolumeDeleteIfExists(name: volumeUnused) + doRemoveIfExists(name: containerName, force: true) + + defer { + try? doStop(name: containerName) + doRemoveIfExists(name: containerName, force: true) + doVolumeDeleteIfExists(name: volumeInUse) + doVolumeDeleteIfExists(name: volumeUnused) + } + + try doVolumeCreate(name: volumeInUse) + try doVolumeCreate(name: volumeUnused) + try doLongRun(name: containerName, args: ["-v", "\(volumeInUse):/data"]) + try waitForContainerRunning(containerName) + + // Prune should only remove the unused volume + let (_, error, status) = try run(arguments: ["volume", "prune"]) + if status != 0 { + throw CLIError.executionFailed("volume prune failed: \(error)") + } + + // Verify in-use volume still exists + let (listAfter, _, statusAfter) = try run(arguments: ["volume", "list", "--quiet"]) + #expect(statusAfter == 0) + #expect(listAfter.contains(volumeInUse), "volume in use should NOT be pruned") + #expect(!listAfter.contains(volumeUnused), "unused volume should be pruned") + + try doStop(name: containerName) + doRemoveIfExists(name: containerName, force: true) + doVolumeDeleteIfExists(name: volumeInUse) + } + + @Test func testVolumePruneSkipsVolumeAttachedToStoppedContainer() async throws { + let testName = getTestName() + let volumeName = "\(testName)_vol" + let containerName = "\(testName)_c1" + + // Clean up any existing resources from previous runs + doVolumeDeleteIfExists(name: volumeName) + doRemoveIfExists(name: containerName, force: true) + + defer { + doRemoveIfExists(name: containerName, force: true) + doVolumeDeleteIfExists(name: volumeName) + } + + try doVolumeCreate(name: volumeName) + try doCreate(name: containerName, image: alpine, volumes: ["\(volumeName):/data"]) + try await Task.sleep(for: .seconds(1)) + + // Prune should NOT remove the volume (container exists, even if stopped) + let (_, error, status) = try run(arguments: ["volume", "prune"]) + if status != 0 { + throw CLIError.executionFailed("volume prune failed: \(error)") + } + + let (listAfter, _, statusAfter) = try run(arguments: ["volume", "list", "--quiet"]) + #expect(statusAfter == 0) + #expect(listAfter.contains(volumeName), "volume attached to stopped container should NOT be pruned") + + doRemoveIfExists(name: containerName, force: true) + let (_, error2, status2) = try run(arguments: ["volume", "prune"]) + if status2 != 0 { + throw CLIError.executionFailed("volume prune failed: \(error2)") + } + + // Verify volume is gone + let (listFinal, _, statusFinal) = try run(arguments: ["volume", "list", "--quiet"]) + #expect(statusFinal == 0) + #expect(!listFinal.contains(volumeName), "volume should be pruned after container is deleted") + } } diff --git a/docs/command-reference.md b/docs/command-reference.md index 3b9f67dd..f935f6f8 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -617,15 +617,66 @@ container volume rm $VOL ### `container volume delete (rm)` -Removes one or more volumes by name. +Removes one or more volumes by name. Volumes that are currently in use by containers (running or stopped) cannot be deleted. **Usage** ```bash -container volume delete NAME... +container volume delete [OPTIONS] [NAME...] ``` -Only global flags are available. +**Arguments** + +* `NAME...`: Volume names to delete + +**Options** + +* `-a, --all`: Delete all volumes (only removes volumes not in use) +* **Global**: `--debug`, `--version`, `-h`/`--help` + +**Examples** + +```bash +# delete a specific volume +container volume delete myvolume + +# delete multiple volumes +container volume delete vol1 vol2 vol3 + +# delete all unused volumes +container volume delete --all +``` + +### `container volume prune` + +Removes all volumes that have no container references. This includes volumes that are not attached to any running or stopped containers. The command reports the actual disk space reclaimed after deletion. + +**Usage** + +```bash +container volume prune [OPTIONS] +``` + +**Options** + +* **Global**: `--debug`, `--version`, `-h`/`--help` + +**Examples** + +```bash +# remove all unused volumes +container volume prune +``` + +**Example output:** + +``` +Pruned volumes: +vol1 +vol2 + +Reclaimed 71.8 MB in disk space +``` ### `container volume list (ls)`