From de986e890e61380b51460f442961685dffd5e530 Mon Sep 17 00:00:00 2001 From: YueGuobin Date: Fri, 6 Nov 2026 22:05:52 +0800 Subject: [PATCH] feat: name nodes and templates in Docker image delete conflicts The compute translates the container ids in a daemon delete conflict into the GNS3 node and project behind each container. Leftover containers from closed projects and containers created outside GNS3 are named as such. The controller lists the templates referencing the image in the conflict error, matched through the canonical image name. After a successful deletion it emits a docker.image.deleted notification with those templates: their nodes can no longer start. --- gns3server/api/routes/controller/computes.py | 46 +++++++++- gns3server/compute/docker/__init__.py | 65 +++++++++++++- gns3server/utils/images.py | 38 ++++++++ tests/api/routes/controller/test_computes.py | 77 +++++++++++++++++ tests/compute/docker/test_docker.py | 91 +++++++++++++++++++- tests/utils/test_images.py | 31 ++++++- 6 files changed, 341 insertions(+), 7 deletions(-) diff --git a/gns3server/api/routes/controller/computes.py b/gns3server/api/routes/controller/computes.py index 33ac14b1c..9123d7eae 100644 --- a/gns3server/api/routes/controller/computes.py +++ b/gns3server/api/routes/controller/computes.py @@ -26,11 +26,16 @@ from fastapi import APIRouter, Body, Depends, HTTPException, Path, Query, Reques import gns3server.db.models as models from gns3server import schemas from gns3server.controller import Controller -from gns3server.controller.controller_error import ControllerBadRequestError, ControllerError +from gns3server.controller.controller_error import ComputeConflictError, ControllerBadRequestError, ControllerError from gns3server.db.repositories.computes import ComputesRepository from gns3server.db.repositories.rbac import RbacRepository +from gns3server.db.repositories.templates import TemplatesRepository from gns3server.services.computes import ComputesService -from gns3server.utils.images import DOCKER_IMAGE_NAME_PATTERN, validate_docker_image_name +from gns3server.utils.images import ( + DOCKER_IMAGE_NAME_PATTERN, + canonical_docker_image_name, + validate_docker_image_name, +) from .dependencies.database import get_repository from .dependencies.rbac import has_privilege @@ -267,12 +272,19 @@ async def docker_delete_image( compute_id: Union[str, UUID], image: str = Path(..., pattern=DOCKER_IMAGE_NAME_PATTERN), force: bool = Query(False, description="Remove the image even if a container uses it"), + templates_repo: TemplatesRepository = Depends(get_repository(TemplatesRepository)), ) -> None: """ Delete a Docker image on a compute. The compute refuses to delete an image used by a container (even a stopped - one) and answers a conflict, unless force is set. + one) and answers a conflict naming the GNS3 nodes and projects using it, + unless force is set. + + Templates referencing the image do not block the deletion but are named in + the conflict error, and a docker.image.deleted notification reporting them + is emitted on the controller notification stream after a successful + deletion. Required privilege: Compute.Modify """ @@ -282,8 +294,34 @@ async def docker_delete_image( except ValueError as e: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(e)) from e + canonical_image = canonical_docker_image_name(image) + referencing_templates = [ + str(template.name) + for template in await templates_repo.get_templates() + if isinstance(template, models.DockerTemplate) + and template.image + and canonical_docker_image_name(str(template.image)) == canonical_image + ] + compute = Controller.instance().get_compute(str(compute_id)) - await compute.http_query("DELETE", f"/docker/images/{image}", params={"force": str(force).lower()}) + try: + await compute.http_query("DELETE", f"/docker/images/{image}", params={"force": str(force).lower()}) + except ComputeConflictError as e: + if referencing_templates: + response = e.response() + response["message"] += f" The image is also referenced by template(s): {', '.join(referencing_templates)}." + raise ComputeConflictError(e.url(), response) from e + raise + # tell the clients which templates pointed at the deleted image: their + # nodes can no longer start + Controller.instance().notification.controller_emit( + "docker.image.deleted", + { + "compute_id": str(compute_id), + "image": image, + "referenced_by_templates": referencing_templates, + }, + ) @router.get("/{compute_id}/virtualbox/vms", response_model=List[schemas.ComputeVirtualBoxVM]) diff --git a/gns3server/compute/docker/__init__.py b/gns3server/compute/docker/__init__.py index 44c2d3a01..4138c6e4d 100644 --- a/gns3server/compute/docker/__init__.py +++ b/gns3server/compute/docker/__init__.py @@ -22,6 +22,7 @@ import asyncio import json import logging import os +import re import shutil import sys @@ -29,6 +30,7 @@ import aiohttp import platformdirs from gns3server.compute.base_manager import BaseManager +from gns3server.compute.compute_error import ComputeError from gns3server.compute.docker.docker_error import ( DockerError, DockerHttp304Error, @@ -38,6 +40,7 @@ from gns3server.compute.docker.docker_error import ( from gns3server.compute.docker.docker_vm import DockerVM from gns3server.compute.docker.iol_docker_vm import IOLDockerVM from gns3server.compute.docker.vendor_docker_vm import VendorDockerVM +from gns3server.compute.project_manager import ProjectManager from gns3server.config import Config from gns3server.utils import parse_version from gns3server.utils.asyncio import locking @@ -56,6 +59,16 @@ CHUNK_SIZE = 1024 * 8 # 8KB # otherwise hang forever. This is an idle timeout, not a total time limit. PULL_IDLE_TIMEOUT = 60 +# Docker names GNS3 node containers "GNS3.{node name}.{project_id}", so a +# container name can be translated back into the node and project that block +# an image deletion. The node name may itself contain dots. +GNS3_CONTAINER_NAME_RE = re.compile( + r"^GNS3\.(?P.+)\.(?P[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12})$" +) +# The containers blocking an image deletion, as named by the daemon, e.g. +# 'container 6d59f00236ff is using its referenced image d529dd0c6e55' +CONFLICTING_CONTAINER_RE = re.compile(r"container ([0-9a-f]{12,64})\b") + class Docker(BaseManager): _NODE_CLASS = DockerVM @@ -582,11 +595,61 @@ class Docker(BaseManager): """ Delete a Docker image from the Docker daemon. + When the daemon refuses because containers use the image, the error + names the GNS3 nodes and projects behind them instead of raw + container ids. + :param image: Image name or id :param force: Remove the image even if a container uses it """ - await self.query("DELETE", f"images/{image}", params={"force": str(force).lower()}) + try: + await self.query("DELETE", f"images/{image}", params={"force": str(force).lower()}) + except DockerHttp409Error as e: + blockers = await self._describe_containers_using_image(str(e)) + if blockers: + raise DockerHttp409Error( + f"Cannot delete image '{image}': it is still used by {blockers}. " + f"Delete the node or container first, or repeat with force=true." + ) from e + raise # the image id translation recorded when this image was synced from the # controller no longer matches anything on this daemon self._image_id_translations.pop(image, None) + + async def _describe_containers_using_image(self, daemon_error: str) -> str: + """ + Translate the container ids named in a daemon image deletion conflict + into node, project or container descriptions. + + :param daemon_error: the raw daemon conflict message + :returns: a comma separated description, empty when the message names + no container + """ + + descriptions = [] + for container_id in CONFLICTING_CONTAINER_RE.findall(daemon_error): + try: + info = await self.query("GET", f"containers/{container_id}/json") + except DockerError: + info = None + if not info: + # the container cannot be inspected (or already vanished) + descriptions.append(f"container '{container_id}'") + continue + name = info.get("Name", container_id).lstrip("/") + state = "running" if info.get("State", {}).get("Running") else "stopped" + match = GNS3_CONTAINER_NAME_RE.match(name) + if match: + node = match.group("node") + try: + project = ProjectManager.instance().get_project(match.group("project_id")) + except ComputeError: + # the project is closed on this compute: a leftover container + descriptions.append(f"leftover container of node '{node}' ({state}, its project is closed)") + else: + descriptions.append(f"node '{node}' in project '{project.name}' ({state})") + else: + # a container created outside GNS3 + descriptions.append(f"container '{name}' ({state})") + return ", ".join(descriptions) diff --git a/gns3server/utils/images.py b/gns3server/utils/images.py index 327f28e81..512e570b0 100644 --- a/gns3server/utils/images.py +++ b/gns3server/utils/images.py @@ -72,6 +72,44 @@ def validate_docker_image_name(image: str) -> None: raise ValueError(f"Invalid Docker image name: {image}") +def canonical_docker_image_name(image: str) -> str: + """ + Normalize a Docker image reference for name comparisons. + + Registry hosts are dropped, Docker Hub's implicit "library/" namespace and + the implicit ":latest" tag are made explicit, so "alpine", + "library/alpine:latest" and "docker.io/library/alpine" all normalize to + the same string. A reference pinned by digest keeps its digest and loses + its tag. + """ + + reference = image.strip() + if "/" in reference: + registry, _, remainder = reference.partition("/") + if registry == "localhost" or "." in registry or ":" in registry: + # the first path element is a registry host, not a namespace + reference = remainder + if "@" in reference: + repository, _, digest = reference.rpartition("@") + if not repository: + return reference # a bare digest, nothing to normalize + # with a digest pinned the tag does not take part in the identity + repository = repository.partition(":")[0] + return f"{_canonical_docker_repository(repository)}@{digest}" + repository, separator, tag = reference.rpartition(":") + if not separator or not repository: + repository, tag = reference, "latest" + return f"{_canonical_docker_repository(repository)}:{tag or 'latest'}" + + +def _canonical_docker_repository(repository: str) -> str: + + if "/" not in repository: + # images without a namespace live in Docker Hub's "library/" namespace + return f"library/{repository}" + return repository + + async def list_images(image_type): """ Scan directories for available image for a given type. diff --git a/tests/api/routes/controller/test_computes.py b/tests/api/routes/controller/test_computes.py index 976bad4f3..955367d9f 100644 --- a/tests/api/routes/controller/test_computes.py +++ b/tests/api/routes/controller/test_computes.py @@ -24,6 +24,7 @@ from fastapi import FastAPI, status from httpx import AsyncClient from gns3server.controller import Controller +from gns3server.controller.controller_error import ComputeConflictError from gns3server.schemas.controller.computes import Compute pytestmark = pytest.mark.asyncio @@ -260,6 +261,82 @@ class TestComputeFeatures: compute.http_query.assert_not_called() assert response.status_code == status.HTTP_422_UNPROCESSABLE_CONTENT + async def test_compute_delete_docker_image_conflict_names_referencing_templates( + self, app: FastAPI, client: AsyncClient, test_compute: Compute + ) -> None: + """ + Templates do not block the deletion but are named in the conflict + error, matched through their image reference spelling. + """ + + new_template = { + "name": "Alpine conflict test", + "compute_id": "local", + # a different spelling of the deleted 'alpine:3' + "image": "docker.io/library/alpine:3", + "template_type": "docker", + } + response = await client.post(app.url_path_for("create_template"), json=new_template) + assert response.status_code == status.HTTP_201_CREATED + + compute = MagicMock() + compute.http_query = AsyncioMagicMock( + side_effect=ComputeConflictError( + "http://localhost:3080/docker/images/alpine:3", + { + "message": "Cannot delete image 'alpine:3': it is still used by node 'alpine-1' " + "in project 'lab' (running). Delete the node or container first, or repeat with force=true." + }, + ) + ) + with patch("gns3server.api.routes.controller.computes.Controller.instance") as controller: + controller.return_value.get_compute.return_value = compute + response = await client.delete( + app.url_path_for("docker_delete_image", compute_id=test_compute.compute_id, image="alpine:3") + ) + assert response.status_code == status.HTTP_409_CONFLICT + message = response.json()["message"] + assert "node 'alpine-1' in project 'lab'" in message + assert "referenced by template(s): Alpine conflict test" in message + + async def test_compute_delete_docker_image_notifies_referencing_templates( + self, app: FastAPI, client: AsyncClient, test_compute: Compute + ) -> None: + """ + A successful deletion emits a docker.image.deleted notification with + the templates referencing the deleted image. + """ + + new_template = { + "name": "Alpine delete test", + "compute_id": "local", + # an image no other test in this class references: the assertion + # below is exact and the class shares one database + "image": "gns3/delete-event-test:1", + "template_type": "docker", + } + response = await client.post(app.url_path_for("create_template"), json=new_template) + assert response.status_code == status.HTTP_201_CREATED + + compute = MagicMock() + compute.http_query = AsyncioMagicMock(return_value={}) + with patch("gns3server.api.routes.controller.computes.Controller.instance") as controller: + controller.return_value.get_compute.return_value = compute + response = await client.delete( + app.url_path_for( + "docker_delete_image", compute_id=test_compute.compute_id, image="gns3/delete-event-test:1" + ) + ) + assert response.status_code == status.HTTP_204_NO_CONTENT + controller.return_value.notification.controller_emit.assert_called_once_with( + "docker.image.deleted", + { + "compute_id": str(test_compute.compute_id), + "image": "gns3/delete-event-test:1", + "referenced_by_templates": ["Alpine delete test"], + }, + ) + async def test_compute_load_docker_image(self, app: FastAPI, client: AsyncClient, test_compute: Compute) -> None: compute = MagicMock() diff --git a/tests/compute/docker/test_docker.py b/tests/compute/docker/test_docker.py index 92647e156..3895efa2c 100644 --- a/tests/compute/docker/test_docker.py +++ b/tests/compute/docker/test_docker.py @@ -16,6 +16,7 @@ # along with this program. If not, see . import asyncio +import uuid from unittest.mock import MagicMock, patch import pytest @@ -27,7 +28,8 @@ from gns3server.compute.docker import ( PULL_IDLE_TIMEOUT, Docker, ) -from gns3server.compute.docker.docker_error import DockerError, DockerHttp404Error +from gns3server.compute.docker.docker_error import DockerError, DockerHttp404Error, DockerHttp409Error +from gns3server.compute.project_manager import ProjectManager from tests.utils import AsyncioMagicMock, asyncio_patch @@ -434,6 +436,93 @@ async def test_delete_image_error_keeps_translation(): assert docker.image_id_translation("ubuntu:latest") == translation +DAEMON_DELETE_CONFLICT = ( + "Docker has returned an error: 409 conflict: unable to remove repository reference " + '"alpine:3" (must force) - container 6d59f00236ff is using its referenced image d529dd0c6e55' +) + + +@pytest.mark.asyncio +async def test_delete_image_conflict_names_the_node_and_project(): + """ + A container blocking the deletion is reported as the GNS3 node and project + it belongs to, not as a raw container id. + """ + + docker = Docker.instance() + project_id = str(uuid.uuid4()) + project = ProjectManager.instance().create_project(name="test-lab", project_id=project_id) + + async def query(method, path, **kwargs): + assert path.startswith("images/") or path.startswith("containers/") + if method == "DELETE": + raise DockerHttp409Error(DAEMON_DELETE_CONFLICT) + return {"Name": f"/GNS3.alpine-1.{project_id}", "State": {"Running": True}} + + try: + with asyncio_patch("gns3server.compute.docker.Docker.query", side_effect=query): + with pytest.raises(DockerHttp409Error) as excinfo: + await docker.delete_image("alpine:3") + message = str(excinfo.value) + assert "node 'alpine-1' in project 'test-lab' (running)" in message + assert "force=true" in message + assert "6d59f00236ff" not in message + finally: + ProjectManager.instance().remove_project(project.id) + + +@pytest.mark.asyncio +async def test_delete_image_conflict_reports_a_leftover_container(): + """ + When the project of the blocking container is closed on this compute the + container is reported as a leftover. + """ + + docker = Docker.instance() + + async def query(method, path, **kwargs): + if method == "DELETE": + raise DockerHttp409Error(DAEMON_DELETE_CONFLICT) + return {"Name": f"/GNS3.E2E-2.{uuid.uuid4()}", "State": {"Running": False}} + + with asyncio_patch("gns3server.compute.docker.Docker.query", side_effect=query): + with pytest.raises(DockerHttp409Error, match="leftover container of node 'E2E-2' \\(stopped"): + await docker.delete_image("alpine:3") + + +@pytest.mark.asyncio +async def test_delete_image_conflict_reports_a_non_gns3_container(): + """ + A container created outside GNS3 is reported by its plain container name. + """ + + docker = Docker.instance() + + async def query(method, path, **kwargs): + if method == "DELETE": + raise DockerHttp409Error(DAEMON_DELETE_CONFLICT) + return {"Name": "/my-own-container", "State": {"Running": True}} + + with asyncio_patch("gns3server.compute.docker.Docker.query", side_effect=query): + with pytest.raises(DockerHttp409Error, match="container 'my-own-container' \\(running\\)"): + await docker.delete_image("alpine:3") + + +@pytest.mark.asyncio +async def test_delete_image_conflict_without_containers_is_not_rewritten(): + """ + A daemon conflict naming no container (e.g. a multi repository reference) + is passed through unchanged. + """ + + docker = Docker.instance() + original = "Docker has returned an error: 409 conflict: image is referenced in multiple repositories" + + with asyncio_patch("gns3server.compute.docker.Docker.query", side_effect=DockerHttp409Error(original)): + with pytest.raises(DockerHttp409Error, match="multiple repositories"): + await docker.delete_image("alpine:3") + + @pytest.mark.asyncio async def test_docker_check_connection_docker_minimum_version(vm): diff --git a/tests/utils/test_images.py b/tests/utils/test_images.py index b932ab59b..1008b8851 100644 --- a/tests/utils/test_images.py +++ b/tests/utils/test_images.py @@ -20,7 +20,13 @@ import threading import pytest from gns3server.utils import force_unix_path -from gns3server.utils.images import images_directories, list_images, md5sum, remove_checksum +from gns3server.utils.images import ( + canonical_docker_image_name, + images_directories, + list_images, + md5sum, + remove_checksum, +) def test_images_directories(tmpdir, config): @@ -108,6 +114,29 @@ def test_remove_checksum(tmpdir): remove_checksum(str(tmpdir / "not_exists")) +@pytest.mark.parametrize( + "reference, expected", + ( + ("alpine", "library/alpine:latest"), + ("alpine:3", "library/alpine:3"), + ("library/alpine:3", "library/alpine:3"), + ("docker.io/library/alpine:3", "library/alpine:3"), + ("index.docker.io/library/alpine:3", "library/alpine:3"), + ("localhost/alpine:3", "library/alpine:3"), + ("gns3/frr", "gns3/frr:latest"), + ("gns3/frr:latest", "gns3/frr:latest"), + ("quay.io/some/namespace/image:2.0", "some/namespace/image:2.0"), + ("alpine@sha256:" + "a" * 64, "library/alpine@sha256:" + "a" * 64), + ("alpine:3@sha256:" + "a" * 64, "library/alpine@sha256:" + "a" * 64), + ), +) +def test_canonical_docker_image_name(reference, expected): + + assert canonical_docker_image_name(reference) == expected + # the canonical form is stable: canonicalizing twice does not change it + assert canonical_docker_image_name(expected) == expected + + @pytest.mark.asyncio async def test_list_images(tmpdir, config):