feat(api): add support for project cluster agents

nejch · max-wittig · commit 32dbc6f2bee5 · 2024-07-16T15:21:50.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -14,6 +14,7 @@ API examples
    gl_objects/bulk_imports
    gl_objects/messages
    gl_objects/ci_lint
+   gl_objects/cluster_agents
    gl_objects/commits
    gl_objects/deploy_keys
    gl_objects/deploy_tokens
diff --git a/docs/gl_objects/cluster_agents.rst b/docs/gl_objects/cluster_agents.rst
@@ -0,0 +1,41 @@
+##############
+Cluster agents
+##############
+
+You can list and manage project cluster agents with the GitLab agent for Kubernetes.
+
+.. warning::
+   Check the GitLab API documentation linked below for project permissions
+   required to access specific cluster agent endpoints.
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectClusterAgent`
+  + :class:`gitlab.v4.objects.ProjectClusterAgentManager`
+  + :attr:`gitlab.v4.objects.Project.cluster_agents`
+
+* GitLab API: https://docs.gitlab.com/ee/api/cluster_agents.html
+
+Examples
+--------
+
+List cluster agents for a project::
+
+    cluster_agents = project.cluster_agents.list()
+
+Register a cluster agent with a project::
+
+    cluster_agent = project.cluster_agents.create({"name": "Agent 1"})
+
+Retrieve a specific cluster agent for a project::
+
+    cluster_agent = project.cluster_agents.get(cluster_agent.id)
+
+Delete a registered cluster agent from a project::
+
+    cluster_agent = project.cluster_agents.delete(cluster_agent.id)
+    # or
+    cluster.delete()
diff --git a/gitlab/v4/objects/__init__.py b/gitlab/v4/objects/__init__.py
@@ -10,6 +10,7 @@
 from .broadcast_messages import *
 from .bulk_imports import *
 from .ci_lint import *
+from .cluster_agents import *
 from .clusters import *
 from .commits import *
 from .container_registry import *
diff --git a/gitlab/v4/objects/cluster_agents.py b/gitlab/v4/objects/cluster_agents.py
@@ -0,0 +1,26 @@
+from typing import Any, cast, Union
+
+from gitlab.base import RESTManager, RESTObject
+from gitlab.mixins import NoUpdateMixin, ObjectDeleteMixin, SaveMixin
+from gitlab.types import RequiredOptional
+
+__all__ = [
+    "ProjectClusterAgent",
+    "ProjectClusterAgentManager",
+]
+
+
+class ProjectClusterAgent(SaveMixin, ObjectDeleteMixin, RESTObject):
+    _repr_attr = "name"
+
+
+class ProjectClusterAgentManager(NoUpdateMixin, RESTManager):
+    _path = "/projects/{project_id}/cluster_agents"
+    _obj_cls = ProjectClusterAgent
+    _from_parent_attrs = {"project_id": "id"}
+    _create_attrs = RequiredOptional(required=("name",))
+
+    def get(
+        self, id: Union[str, int], lazy: bool = False, **kwargs: Any
+    ) -> ProjectClusterAgent:
+        return cast(ProjectClusterAgent, super().get(id=id, lazy=lazy, **kwargs))
diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py
@@ -43,6 +43,7 @@
 from .boards import ProjectBoardManager  # noqa: F401
 from .branches import ProjectBranchManager, ProjectProtectedBranchManager  # noqa: F401
 from .ci_lint import ProjectCiLintManager  # noqa: F401
+from .cluster_agents import ProjectClusterAgentManager  # noqa: F401
 from .clusters import ProjectClusterManager  # noqa: F401
 from .commits import ProjectCommitManager  # noqa: F401
 from .container_registry import ProjectRegistryRepositoryManager  # noqa: F401
@@ -183,6 +184,7 @@ class Project(
     branches: ProjectBranchManager
     ci_lint: ProjectCiLintManager
     clusters: ProjectClusterManager
+    cluster_agents: ProjectClusterAgentManager
     commits: ProjectCommitManager
     customattributes: ProjectCustomAttributeManager
     deployments: ProjectDeploymentManager
diff --git a/tests/unit/objects/test_cluster_agents.py b/tests/unit/objects/test_cluster_agents.py
@@ -0,0 +1,97 @@
+"""
+GitLab API: https://docs.gitlab.com/ee/api/cluster_agents.html
+"""
+
+import pytest
+import responses
+
+from gitlab.v4.objects import ProjectClusterAgent
+
+agent_content = {
+    "id": 1,
+    "name": "agent-1",
+    "config_project": {
+        "id": 20,
+        "description": "",
+        "name": "test",
+        "name_with_namespace": "Administrator / test",
+        "path": "test",
+        "path_with_namespace": "root/test",
+        "created_at": "2022-03-20T20:42:40.221Z",
+    },
+    "created_at": "2022-04-20T20:42:40.221Z",
+    "created_by_user_id": 42,
+}
+
+
+@pytest.fixture
+def resp_list_project_cluster_agents():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.GET,
+            url="http://localhost/api/v4/projects/1/cluster_agents",
+            json=[agent_content],
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
+@pytest.fixture
+def resp_get_project_cluster_agent():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.GET,
+            url="http://localhost/api/v4/projects/1/cluster_agents/1",
+            json=agent_content,
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
+@pytest.fixture
+def resp_create_project_cluster_agent():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.POST,
+            url="http://localhost/api/v4/projects/1/cluster_agents",
+            json=agent_content,
+            content_type="application/json",
+            status=201,
+        )
+        yield rsps
+
+
+@pytest.fixture
+def resp_delete_project_cluster_agent():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.DELETE,
+            url="http://localhost/api/v4/projects/1/cluster_agents/1",
+            status=204,
+        )
+        yield rsps
+
+
+def test_list_project_cluster_agents(project, resp_list_project_cluster_agents):
+    agent = project.cluster_agents.list()[0]
+    assert isinstance(agent, ProjectClusterAgent)
+    assert agent.name == "agent-1"
+
+
+def test_get_project_cluster_agent(project, resp_get_project_cluster_agent):
+    agent = project.cluster_agents.get(1)
+    assert isinstance(agent, ProjectClusterAgent)
+    assert agent.name == "agent-1"
+
+
+def test_create_project_cluster_agent(project, resp_create_project_cluster_agent):
+    agent = project.cluster_agents.create({"name": "agent-1"})
+    assert isinstance(agent, ProjectClusterAgent)
+    assert agent.name == "agent-1"
+
+
+def test_delete_project_cluster_agent(project, resp_delete_project_cluster_agent):
+    agent = project.cluster_agents.get(1, lazy=True)
+    agent.delete()
