Add endpoint to reset Docker storage - #7166
Conversation
Corrupted Docker image layers cannot be always fixed by removing and re-pulling a single image, because layers are shared between images. The only (easy) way to recover is wiping all of Docker's storage which is currently cumbersome and requires OS shell access. Home Assistant OS added a service that performs the Docker storage wipe on boot when a flag file exists in home-assistant/operating-system#4982, and home-assistant/os-agent#283 adds OS Agent DBus interface for creating that file. This adds a new API method POST /docker/reset-storage which calls OS Agent's ScheduleDockerStorageReset and creates a reboot_required issue, following the same pattern used for the Docker storage driver migration. This is expected to ship in HAOS 18.3, so the endpoint checks for that and returns 404 on older OS versions. Technically, it might be nicer to gate on OS Agent version, but from user perspective it's better to report the required OS version. Refs #6555
8fd3601 to
6ecb423
Compare
There was a problem hiding this comment.
Pull request overview
Adds a HAOS-gated API endpoint to schedule a complete Docker storage reset on reboot.
Changes:
- Adds the
/docker/reset-storageendpoint and D-Bus integration. - Creates a reboot-required issue after successful scheduling.
- Covers success, compatibility, connection, and failure scenarios.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
supervisor/api/__init__.py |
Registers the new endpoint. |
supervisor/api/docker.py |
Implements scheduling, validation, and error handling. |
supervisor/dbus/agent/system.py |
Exposes the OS Agent D-Bus call. |
tests/api/test_docker.py |
Tests endpoint behavior and failures. |
tests/dbus/agent/test_system.py |
Tests the D-Bus client method. |
tests/dbus_service_mocks/agent_system.py |
Mocks the new OS Agent method. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
agners
left a comment
agners
left a comment
There was a problem hiding this comment.
Other than the version thing, LGTM!
| web.get("/docker/registries", api_docker.registries), | ||
| web.post("/docker/registries", api_docker.create_registry), | ||
| web.delete("/docker/registries/{hostname}", api_docker.remove_registry), | ||
| web.post("/docker/reset-storage", api_docker.reset_storage), |
There was a problem hiding this comment.
/docker is allowed by Supervisor API manager role. Is that ok for this API as well? 🤔 I guess /docker/migrate-storage-driver is very similar and already enabled for the manager role 🤔 . For me manager is fine, just wanted to bring it up so this is a conscious decision.
There was a problem hiding this comment.
Fair point. But if we want to restrict that, let's also restrict other "dangerous" endpoints in a follow-up.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Proposed change
Corrupted Docker image layers cannot be always fixed by removing and re-pulling a single image, because layers are shared between images. The only (easy) way to recover is wiping all of Docker's storage which is currently cumbersome and requires OS shell access.
Home Assistant OS added a service that performs the Docker storage wipe on boot when a flag file exists in home-assistant/operating-system#4982, and home-assistant/os-agent#283 adds OS Agent DBus interface for creating that file.
This adds a new API method POST /docker/reset-storage which calls OS Agent's ScheduleDockerStorageReset and creates a reboot_required issue, following the same pattern used for the Docker storage driver migration.
This is expected to ship in HAOS 18.3, so the endpoint checks for that and returns 404 on older OS versions. Technically, it might be nicer to gate on OS Agent version, but from user perspective it's better to report the required OS version.
Type of change
Additional information
docker reset-storagecommand cli#674/docker/*endpoints exposed there)Checklist
ruff format supervisor tests)If API endpoints or add-on configuration are added/changed: