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):