From 81b058e6aaf0a5d951432aaeeab27522305e4ff0 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Mon, 9 Jun 2025 13:50:04 +0200 Subject: [PATCH] Added high-level diagrams --- .codeboarding/API Request Layer.md | 192 ++++++++++++++++++ .codeboarding/Cluster Management.md | 190 +++++++++++++++++ .codeboarding/Event Stream.md | 51 +++++ .codeboarding/Exception Handling.md | 70 +++++++ .codeboarding/Nomad Client Core.md | 62 ++++++ .codeboarding/Security & Configuration.md | 217 ++++++++++++++++++++ .codeboarding/Workload Orchestration.md | 235 ++++++++++++++++++++++ .codeboarding/on_boarding.md | 136 +++++++++++++ 8 files changed, 1153 insertions(+) create mode 100644 .codeboarding/API Request Layer.md create mode 100644 .codeboarding/Cluster Management.md create mode 100644 .codeboarding/Event Stream.md create mode 100644 .codeboarding/Exception Handling.md create mode 100644 .codeboarding/Nomad Client Core.md create mode 100644 .codeboarding/Security & Configuration.md create mode 100644 .codeboarding/Workload Orchestration.md create mode 100644 .codeboarding/on_boarding.md diff --git a/.codeboarding/API Request Layer.md b/.codeboarding/API Request Layer.md new file mode 100644 index 0000000..0e5b3b6 --- /dev/null +++ b/.codeboarding/API Request Layer.md @@ -0,0 +1,192 @@ +```mermaid +graph LR + API_Request_Layer["API Request Layer"] + Nomad_API_Endpoints["Nomad API Endpoints"] + API_Exception_Handling["API Exception Handling"] + Nomad_API_Endpoints -- "uses" --> API_Request_Layer + API_Request_Layer -- "raises" --> API_Exception_Handling + Nomad_API_Endpoints -- "can raise" --> API_Exception_Handling +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components of the Nomad API client library. The `API Request Layer` serves as the fundamental communication mechanism, abstracting HTTP request complexities and handling error conditions. Various `Nomad API Endpoints` classes utilize this request layer to interact with specific Nomad API functionalities. The `API Exception Handling` component provides a structured way to manage and propagate errors encountered during API interactions, which are raised by both the `API Request Layer` and directly by the `Nomad API Endpoints`. + +### API Request Layer +A foundational component that abstracts the complexities of making HTTP requests to the Nomad API. It handles URL construction, query parameter building, request execution, and robust error handling, serving as the underlying communication mechanism for all other API client modules. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester` (10:220) +- `nomad.api.base.Requester:__init__` (17:43) +- `nomad.api.base.Requester:request` (103:120) +- `nomad.api.base.Requester:_request` (122:220) +- `nomad.api.base.Requester:_url_builder` (77:84) +- `nomad.api.base.Requester:_query_string_builder` (86:101) +- `nomad.api.base.Requester:_endpoint_builder` (45:50) +- `nomad.api.base.Requester:_required_namespace` (52:75) + + +### Nomad API Endpoints +This component comprises various classes that provide specific interfaces to different Nomad API functionalities, such as managing jobs, agents, nodes, deployments, and ACLs. Each class in this component utilizes the API Request Layer to perform its operations. + + +**Related Classes/Methods**: + +- `nomad.api.scaling.Scaling` (8:74) +- `nomad.api.scaling.Scaling:get_scaling_policies` (31:59) +- `nomad.api.scaling.Scaling:get_scaling_policy` (61:74) +- `nomad.api.metrics.Metrics` (6:42) +- `nomad.api.metrics.Metrics:get_metrics` (32:42) +- `nomad.api.status.Leader` (30:60) +- `nomad.api.status.Leader:get_leader` (50:60) +- `nomad.api.status.Peers` (63:108) +- `nomad.api.status.Peers:get_peers` (98:108) +- `nomad.api.namespaces.Namespaces` (8:75) +- `nomad.api.namespaces.Namespaces:get_namespaces` (62:75) +- `nomad.api.jobs.Jobs` (9:127) +- `nomad.api.jobs.Jobs:get_jobs` (67:97) +- `nomad.api.jobs.Jobs:register_job` (99:109) +- `nomad.api.jobs.Jobs:parse` (111:127) +- `nomad.api.deployments.Deployments` (8:78) +- `nomad.api.deployments.Deployments:get_deployments` (58:78) +- `nomad.api.agent.Agent` (6:98) +- `nomad.api.agent.Agent:get_agent` (24:34) +- `nomad.api.agent.Agent:get_members` (36:46) +- `nomad.api.agent.Agent:get_servers` (48:58) +- `nomad.api.agent.Agent:join_agent` (60:71) +- `nomad.api.agent.Agent:update_servers` (73:85) +- `nomad.api.agent.Agent:force_leave` (87:98) +- `nomad.api.node.Node` (9:193) +- `nomad.api.node.Node:get_node` (52:62) +- `nomad.api.node.Node:get_allocations` (64:74) +- `nomad.api.node.Node:evaluate_node` (76:88) +- `nomad.api.node.Node:drain_node` (90:106) +- `nomad.api.node.Node:drain_node_with_spec` (108:144) +- `nomad.api.node.Node:eligible_node` (146:181) +- `nomad.api.node.Node:purge_node` (183:193) +- `nomad.api.evaluation.Evaluation` (8:74) +- `nomad.api.evaluation.Evaluation:get_evaluation` (48:60) +- `nomad.api.evaluation.Evaluation:get_allocations` (62:74) +- `nomad.api.job.Job` (9:363) +- `nomad.api.job.Job:get_job` (51:70) +- `nomad.api.job.Job:get_versions` (72:84) +- `nomad.api.job.Job:get_allocations` (86:112) +- `nomad.api.job.Job:get_evaluations` (114:137) +- `nomad.api.job.Job:get_deployments` (139:151) +- `nomad.api.job.Job:get_deployment` (153:165) +- `nomad.api.job.Job:get_summary` (167:179) +- `nomad.api.job.Job:register_job` (181:193) +- `nomad.api.job.Job:evaluate_job` (195:208) +- `nomad.api.job.Job:plan_job` (210:229) +- `nomad.api.job.Job:periodic_job` (231:246) +- `nomad.api.job.Job:dispatch_job` (248:277) +- `nomad.api.job.Job:revert_job` (279:301) +- `nomad.api.job.Job:stable_job` (303:318) +- `nomad.api.job.Job:deregister_job` (320:363) +- `nomad.api.system.System` (6:52) +- `nomad.api.system.System:initiate_garbage_collection` (30:40) +- `nomad.api.system.System:reconcile_summaries` (42:52) +- `nomad.api.allocations.Allocations` (8:83) +- `nomad.api.allocations.Allocations:get_allocations` (39:83) +- `nomad.api.operator.Operator` (6:64) +- `nomad.api.operator.Operator:get_configuration` (29:44) +- `nomad.api.operator.Operator:delete_peer` (46:64) +- `nomad.api.variable.Variable` (8:111) +- `nomad.api.variable.Variable:get_variable` (42:58) +- `nomad.api.variable.Variable:create_variable` (60:85) +- `nomad.api.variable.Variable:delete_variable` (87:111) +- `nomad.api.namespace.Namespace` (8:107) +- `nomad.api.namespace.Namespace:get_namespace` (51:63) +- `nomad.api.namespace.Namespace:create_namespace` (65:78) +- `nomad.api.namespace.Namespace:update_namespace` (80:93) +- `nomad.api.namespace.Namespace:delete_namespace` (95:107) +- `nomad.api.sentinel.Sentinel` (6:98) +- `nomad.api.sentinel.Sentinel:get_policies` (28:39) +- `nomad.api.sentinel.Sentinel:create_policy` (41:54) +- `nomad.api.sentinel.Sentinel:get_policy` (56:67) +- `nomad.api.sentinel.Sentinel:update_policy` (69:83) +- `nomad.api.sentinel.Sentinel:delete_policy` (85:98) +- `nomad.api.client.ls` (35:65) +- `nomad.api.client.ls:list_files` (49:65) +- `nomad.api.client.cat` (68:99) +- `nomad.api.client.cat:read_file` (83:99) +- `nomad.api.client.read_at` (102:130) +- `nomad.api.client.read_at:read_file_offset` (114:130) +- `nomad.api.client.stream_file` (133:161) +- `nomad.api.client.stream_file:stream` (145:161) +- `nomad.api.client.stream_logs` (164:202) +- `nomad.api.client.stream_logs:stream` (176:202) +- `nomad.api.client.stat` (205:235) +- `nomad.api.client.stat:stat_file` (219:235) +- `nomad.api.client.stats` (238:264) +- `nomad.api.client.stats:read_stats` (252:264) +- `nomad.api.client.allocation` (267:321) +- `nomad.api.client.allocation:read_allocation_stats` (282:293) +- `nomad.api.client.allocation:restart_allocation` (295:305) +- `nomad.api.client.allocation:signal_allocation` (307:321) +- `nomad.api.client.gc_allocation` (324:347) +- `nomad.api.client.gc_allocation:garbage_collect` (336:347) +- `nomad.api.client.gc_all_allocations` (350:372) +- `nomad.api.client.gc_all_allocations:garbage_collect` (362:372) +- `nomad.api.regions.Regions` (8:68) +- `nomad.api.regions.Regions:get_regions` (58:68) +- `nomad.api.validate.Validate` (6:44) +- `nomad.api.validate.Validate:validate_job` (30:44) +- `nomad.api.acl.Acl` (6:194) +- `nomad.api.acl.Acl:generate_bootstrap` (27:38) +- `nomad.api.acl.Acl:get_tokens` (40:52) +- `nomad.api.acl.Acl:get_token` (54:65) +- `nomad.api.acl.Acl:get_self_token` (67:78) +- `nomad.api.acl.Acl:create_token` (80:93) +- `nomad.api.acl.Acl:delete_token` (95:106) +- `nomad.api.acl.Acl:update_token` (108:122) +- `nomad.api.acl.Acl:get_policies` (124:135) +- `nomad.api.acl.Acl:create_policy` (137:150) +- `nomad.api.acl.Acl:get_policy` (152:163) +- `nomad.api.acl.Acl:update_policy` (165:179) +- `nomad.api.acl.Acl:delete_policy` (181:194) +- `nomad.api.nodes.Nodes` (10:95) +- `nomad.api.nodes.Nodes:get_nodes` (67:95) +- `nomad.api.deployment.Deployment` (8:172) +- `nomad.api.deployment.Deployment:get_deployment` (46:58) +- `nomad.api.deployment.Deployment:get_deployment_allocations` (60:72) +- `nomad.api.deployment.Deployment:fail_deployment` (74:88) +- `nomad.api.deployment.Deployment:pause_deployment` (90:105) +- `nomad.api.deployment.Deployment:promote_deployment_all` (107:122) +- `nomad.api.deployment.Deployment:promote_deployment_groups` (124:141) +- `nomad.api.deployment.Deployment:deployment_allocation_health` (143:172) +- `nomad.api.variables.Variables` (6:66) +- `nomad.api.variables.Variables:get_variables` (47:66) +- `nomad.api.evaluations.Evaluations` (8:75) +- `nomad.api.evaluations.Evaluations:get_evaluations` (62:75) +- `nomad.api.search.Search` (8:98) +- `nomad.api.search.Search:search` (33:66) +- `nomad.api.search.Search:fuzzy_search` (68:98) +- `nomad.api.allocation.Allocation` (8:73) +- `nomad.api.allocation.Allocation:get_allocation` (51:61) +- `nomad.api.allocation.Allocation:stop_allocation` (63:73) +- `nomad.api.event.stream` (31:133) +- `nomad.api.event.stream:_get_stream` (43:68) + + +### API Exception Handling +This component defines and manages custom exceptions that can occur during interactions with the Nomad API. These exceptions provide specific error contexts for different types of API failures. + + +**Related Classes/Methods**: + +- `nomad.api.exceptions.InvalidParameters` (35:36) +- `nomad.api.exceptions.BadRequestNomadException` (27:28) +- `nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24) +- `nomad.api.exceptions.URLNotFoundNomadException` (19:20) +- `nomad.api.exceptions.VariableConflict` (31:32) +- `nomad.api.exceptions.BaseNomadException` (6:16) +- `nomad.api.exceptions.TimeoutNomadException` (39:40) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Cluster Management.md b/.codeboarding/Cluster Management.md new file mode 100644 index 0000000..6092efc --- /dev/null +++ b/.codeboarding/Cluster Management.md @@ -0,0 +1,190 @@ +```mermaid +graph LR + NomadClient["NomadClient"] + APIRequester["APIRequester"] + AgentAPI["AgentAPI"] + NodeAPI["NodeAPI"] + NodesAPI["NodesAPI"] + StatusAPI["StatusAPI"] + SystemAPI["SystemAPI"] + OperatorAPI["OperatorAPI"] + MetricsAPI["MetricsAPI"] + RegionsAPI["RegionsAPI"] + APIExceptions["APIExceptions"] + NomadClient -- "initializes" --> AgentAPI + NomadClient -- "initializes" --> NodeAPI + NomadClient -- "initializes" --> NodesAPI + NomadClient -- "initializes" --> OperatorAPI + NomadClient -- "initializes" --> MetricsAPI + NomadClient -- "initializes" --> StatusAPI + NomadClient -- "initializes" --> SystemAPI + NomadClient -- "initializes" --> RegionsAPI + AgentAPI -- "inherits from" --> APIRequester + NodeAPI -- "inherits from" --> APIRequester + NodesAPI -- "inherits from" --> APIRequester + OperatorAPI -- "inherits from" --> APIRequester + MetricsAPI -- "inherits from" --> APIRequester + StatusAPI -- "inherits from" --> APIRequester + SystemAPI -- "inherits from" --> APIRequester + RegionsAPI -- "inherits from" --> APIRequester + APIRequester -- "raises" --> APIExceptions +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This component overview describes the `Cluster Management` subsystem of Nomad, which provides functionalities for monitoring and controlling the Nomad cluster's infrastructure. It encompasses managing agents and nodes, retrieving cluster status and metrics, performing operator-level actions, and interacting with multi-region deployments. The core interaction flow involves the `NomadClient` initializing various API-specific components, all of which inherit from `APIRequester` to handle HTTP communication with the Nomad API. Error handling is managed by `APIExceptions`. + +### NomadClient +The main client component for interacting with the Nomad API. It initializes and provides access to various API-specific client components such as Agent, Node, Status, System, Operator, Metrics, Regions, and Nodes. + + +**Related Classes/Methods**: + +- `nomad.Nomad:__init__` (full file reference) + + +### APIRequester +A foundational component that serves as the base class for all specific Nomad API client components. It encapsulates the core logic for making HTTP requests to the Nomad API, handling URL building, query string parameters, and common exception handling. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester:__init__` (17:43) +- `nomad.api.base.Requester:request` (103:120) +- `nomad.api.base.Requester:_query_string_builder` (86:101) +- `nomad.api.base.Requester:_request` (122:220) +- `nomad.api.base.Requester:_endpoint_builder` (45:50) +- `nomad.api.base.Requester:_url_builder` (77:84) +- `nomad.api.base.Requester:_required_namespace` (52:75) + + +### AgentAPI +This component provides methods for interacting with the Nomad agent API, allowing operations such as retrieving agent information, managing members, updating servers, and forcing agents to leave the cluster. + + +**Related Classes/Methods**: + +- `nomad.api.agent.Agent:__init__` (11:12) +- `nomad.api.agent.Agent:get_agent` (24:34) +- `nomad.api.agent.Agent:get_members` (36:46) +- `nomad.api.agent.Agent:get_servers` (48:58) +- `nomad.api.agent.Agent:join_agent` (60:71) +- `nomad.api.agent.Agent:update_servers` (73:85) +- `nomad.api.agent.Agent:force_leave` (87:98) + + +### NodeAPI +This component manages interactions with individual Nomad nodes, enabling retrieval of node details, listing allocations on a node, evaluating, draining, and purging nodes. + + +**Related Classes/Methods**: + +- `nomad.api.node.Node:__init__` (19:20) +- `nomad.api.node.Node:__contains__` (32:37) +- `nomad.api.node.Node:__getitem__` (39:50) +- `nomad.api.node.Node:get_node` (52:62) +- `nomad.api.node.Node:get_allocations` (64:74) +- `nomad.api.node.Node:evaluate_node` (76:88) +- `nomad.api.node.Node:drain_node` (90:106) +- `nomad.api.node.Node:drain_node_with_spec` (108:144) +- `nomad.api.node.Node:eligible_node` (146:181) +- `nomad.api.node.Node:purge_node` (183:193) + + +### NodesAPI +This component provides functionality to interact with collections of Nomad nodes, allowing for listing and querying multiple nodes. + + +**Related Classes/Methods**: + +- `nomad.api.nodes.Nodes:__init__` (20:21) +- `nomad.api.nodes.Nodes:__contains__` (33:44) +- `nomad.api.nodes.Nodes:__len__` (46:48) +- `nomad.api.nodes.Nodes:__getitem__` (50:61) +- `nomad.api.nodes.Nodes:__iter__` (63:65) +- `nomad.api.nodes.Nodes:get_nodes` (67:95) + + +### StatusAPI +This component is responsible for retrieving the status of the Nomad cluster, including information about the leader and peers. + + +**Related Classes/Methods**: + +- `nomad.api.status.Status:__init__` (15:17) +- `nomad.api.status.Leader` (30:60) +- `nomad.api.status.Leader:__contains__` (35:44) +- `nomad.api.status.Leader:__len__` (46:48) +- `nomad.api.status.Leader:get_leader` (50:60) +- `nomad.api.status.Peers` (63:108) +- `nomad.api.status.Peers:__contains__` (68:77) +- `nomad.api.status.Peers:__len__` (79:81) +- `nomad.api.status.Peers:__getitem__` (83:92) +- `nomad.api.status.Peers:__iter__` (94:96) +- `nomad.api.status.Peers:get_peers` (98:108) + + +### SystemAPI +This component provides methods for system-wide operations within Nomad, such as initiating garbage collection and reconciling summaries. + + +**Related Classes/Methods**: + +- `nomad.api.system.System:__init__` (17:18) +- `nomad.api.system.System:initiate_garbage_collection` (30:40) +- `nomad.api.system.System:reconcile_summaries` (42:52) + + +### OperatorAPI +This component allows interaction with Nomad's operator endpoints, providing functionalities like retrieving cluster configuration and deleting peers. + + +**Related Classes/Methods**: + +- `nomad.api.operator.Operator:__init__` (16:17) +- `nomad.api.operator.Operator:get_configuration` (29:44) +- `nomad.api.operator.Operator:delete_peer` (46:64) + + +### MetricsAPI +This component is dedicated to retrieving metrics from the Nomad cluster. + + +**Related Classes/Methods**: + +- `nomad.api.metrics.Metrics:__init__` (19:20) +- `nomad.api.metrics.Metrics:get_metrics` (32:42) + + +### RegionsAPI +This component provides methods for interacting with Nomad regions, allowing for listing and querying available regions. + + +**Related Classes/Methods**: + +- `nomad.api.regions.Regions:__init__` (15:16) +- `nomad.api.regions.Regions:__contains__` (28:37) +- `nomad.api.regions.Regions:__len__` (39:41) +- `nomad.api.regions.Regions:__getitem__` (43:52) +- `nomad.api.regions.Regions:__iter__` (54:56) +- `nomad.api.regions.Regions:get_regions` (58:68) + + +### APIExceptions +This component defines various custom exception classes used throughout the Nomad API client to handle specific error conditions returned by the Nomad server, such as bad requests, unauthorized access, not found errors, and timeouts. + + +**Related Classes/Methods**: + +- `nomad.api.exceptions.BadRequestNomadException` (27:28) +- `nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24) +- `nomad.api.exceptions.URLNotFoundNomadException` (19:20) +- `nomad.api.exceptions.VariableConflict` (31:32) +- `nomad.api.exceptions.BaseNomadException` (6:16) +- `nomad.api.exceptions.TimeoutNomadException` (39:40) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Event Stream.md b/.codeboarding/Event Stream.md new file mode 100644 index 0000000..10dab9c --- /dev/null +++ b/.codeboarding/Event Stream.md @@ -0,0 +1,51 @@ +```mermaid +graph LR + Event_API["Event API"] + Event_Stream_Handler["Event Stream Handler"] + API_Requester["API Requester"] + Event_API -- "provides" --> Event_Stream_Handler + Event_Stream_Handler -- "uses" --> API_Requester +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components involved in establishing and managing real-time event streams from the Nomad server. The `Event API` acts as the entry point, providing access to the `Event Stream Handler`. The `Event Stream Handler` is responsible for the actual streaming process, leveraging the `API Requester` for underlying HTTP communication with the Nomad server. + +### Event API +This component serves as the primary interface for accessing Nomad event-related functionalities. It initializes and provides access to event streaming capabilities. + + +**Related Classes/Methods**: + +- `nomad.api.event.Event` (12:27) +- `nomad.api.event.Event:__init__` (26:27) + + +### Event Stream Handler +This component is responsible for establishing and maintaining a continuous stream of events from the Nomad API. It handles the underlying network communication, processes incoming event data, and manages the stream lifecycle using a separate thread. + + +**Related Classes/Methods**: + +- `nomad.api.event.stream` (31:133) +- `nomad.api.event.stream:__init__` (40:41) +- `nomad.api.event.stream:_get_stream` (43:68) +- `nomad.api.event.stream:get_stream` (70:133) + + +### API Requester +This foundational component provides the core functionality for making HTTP requests to the Nomad API. It manages connection parameters, authentication tokens, and handles various aspects of the request lifecycle, including error handling and response processing. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester` (10:220) +- `nomad.api.base.Requester:__init__` (17:43) +- `nomad.api.base.Requester:request` (103:120) +- `nomad.api.base.Requester:_request` (122:220) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Exception Handling.md b/.codeboarding/Exception Handling.md new file mode 100644 index 0000000..8ed59c1 --- /dev/null +++ b/.codeboarding/Exception Handling.md @@ -0,0 +1,70 @@ +```mermaid +graph LR + Request_Handling["Request Handling"] + Scaling_Policy_Management["Scaling Policy Management"] + Search_Operations["Search Operations"] + Nomad_API_Exception_Handling["Nomad API Exception Handling"] + Scaling_Policy_Management -- "initiates API requests" --> Request_Handling + Scaling_Policy_Management -- "validates input and raises exceptions" --> Nomad_API_Exception_Handling + Search_Operations -- "initiates API requests" --> Request_Handling + Search_Operations -- "validates input and raises exceptions" --> Nomad_API_Exception_Handling + Request_Handling -- "propagates API errors as exceptions" --> Nomad_API_Exception_Handling +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components of the Nomad API client library, focusing on how requests are handled, specific API functionalities are managed (scaling and search), and how errors are uniformly managed through a dedicated exception handling system. The Request Handling component is central to all API interactions, while Scaling Policy Management and Search Operations represent specific API domains. The Nomad API Exception Handling component provides a robust error reporting mechanism across the client library. + +### Request Handling +This component is responsible for constructing and sending HTTP requests to the Nomad API. It handles URL and query string building, adds authentication tokens and user agents, processes HTTP responses, and raises specific Nomad API exceptions for different error codes. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester` (10:220) +- `nomad.api.base.Requester:_request` (122:220) +- `nomad.api.base.Requester._url_builder` (77:84) +- `nomad.api.base.Requester._query_string_builder` (86:101) +- `nomad.api.base.Requester.request` (103:120) + + +### Scaling Policy Management +This component provides an interface to interact with the Nomad API for managing scaling policies. It allows fetching scaling policies and handles invalid parameters specific to scaling policy requests. + + +**Related Classes/Methods**: + +- `nomad.api.scaling.Scaling` (8:74) +- `nomad.api.scaling.Scaling:get_scaling_policies` (31:59) + + +### Search Operations +This component facilitates searching within the Nomad API, supporting both exact and fuzzy searches across various contexts like jobs, allocations, and nodes. It validates search parameters before making requests. + + +**Related Classes/Methods**: + +- `nomad.api.search.Search` (8:98) +- `nomad.api.search.Search:search` (33:66) +- `nomad.api.search.Search:fuzzy_search` (68:98) + + +### Nomad API Exception Handling +This component defines a hierarchy of custom exceptions that are raised in response to various error conditions encountered during interactions with the Nomad API, such as bad requests, unauthorized access, not found URLs, and conflicts. It provides specific error information for granular error management and debugging. + + +**Related Classes/Methods**: + +- `nomad.api.exceptions.BaseNomadException` (6:16) +- `nomad.api.exceptions.InvalidParameters` (35:36) +- `nomad.api.exceptions.BadRequestNomadException` (27:28) +- `nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24) +- `nomad.api.exceptions.URLNotFoundNomadException` (19:20) +- `nomad.api.exceptions.VariableConflict` (31:32) +- `nomad.api.exceptions.TimeoutNomadException` (39:40) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Nomad Client Core.md b/.codeboarding/Nomad Client Core.md new file mode 100644 index 0000000..80e0686 --- /dev/null +++ b/.codeboarding/Nomad Client Core.md @@ -0,0 +1,62 @@ +```mermaid +graph LR + Nomad_Client_Core["Nomad Client Core"] + Nomad_API_Endpoints["Nomad API Endpoints"] + Nomad_Client_Core -- "initializes and provides access to" --> Nomad_API_Endpoints +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components of the python-nomad library, focusing on the central `Nomad Client Core` which serves as the entry point for interacting with the Nomad cluster. It details how the client initializes connections and provides access to various `Nomad API Endpoints`, each responsible for managing specific Nomad resources. The primary flow involves the client initializing and then utilizing these API endpoint modules to perform operations on the Nomad cluster. + +### Nomad Client Core +The primary entry point for the python-nomad library, responsible for initializing the connection to the Nomad cluster and providing access to all other API-specific client modules. It acts as the central interface for users to interact with the Nomad cluster. + + +**Related Classes/Methods**: + +- `nomad.Nomad` (full file reference) +- `nomad.Nomad:__init__` (30:60) +- `nomad.Nomad.get_uri` (62:65) + + +### Nomad API Endpoints +This component encompasses a collection of modules, each dedicated to managing a specific resource or functionality within the Nomad API, such as ACLs, agents, allocations, jobs, and nodes. These modules are instantiated by the Nomad Client to facilitate interactions with the respective Nomad services, often inheriting from a common `Requester` base class for API communication. + + +**Related Classes/Methods**: + +- `nomad.api.acl.Acl` (6:194) +- `nomad.api.agent.Agent` (6:98) +- `nomad.api.allocation.Allocation` (8:73) +- `nomad.api.allocations.Allocations` (8:83) +- `nomad.api.client.Client` (7:32) +- `nomad.api.deployment.Deployment` (8:172) +- `nomad.api.deployments.Deployments` (8:78) +- `nomad.api.evaluation.Evaluation` (8:74) +- `nomad.api.evaluations.Evaluations` (8:75) +- `nomad.api.event.Event` (12:27) +- `nomad.api.job.Job` (9:363) +- `nomad.api.jobs.Jobs` (9:127) +- `nomad.api.metrics.Metrics` (6:42) +- `nomad.api.namespace.Namespace` (8:107) +- `nomad.api.namespaces.Namespaces` (8:75) +- `nomad.api.node.Node` (9:193) +- `nomad.api.nodes.Nodes` (10:95) +- `nomad.api.operator.Operator` (6:64) +- `nomad.api.regions.Regions` (8:68) +- `nomad.api.scaling.Scaling` (8:74) +- `nomad.api.search.Search` (8:98) +- `nomad.api.sentinel.Sentinel` (6:98) +- `nomad.api.status.Status` (8:27) +- `nomad.api.system.System` (6:52) +- `nomad.api.validate.Validate` (6:44) +- `nomad.api.variable.Variable` (8:111) +- `nomad.api.variables.Variables` (6:66) +- `nomad.api.base.Requester` (10:220) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Security & Configuration.md b/.codeboarding/Security & Configuration.md new file mode 100644 index 0000000..00d355c --- /dev/null +++ b/.codeboarding/Security & Configuration.md @@ -0,0 +1,217 @@ +```mermaid +graph LR + Nomad_Client["Nomad Client"] + API_Requester_Base["API Requester Base"] + Scaling_API["Scaling API"] + Namespaces_API["Namespaces API"] + Variable_API["Variable API"] + Single_Namespace_API["Single Namespace API"] + Sentinel_API["Sentinel API"] + Validation_API["Validation API"] + ACL_API["ACL API"] + API_Exceptions["API Exceptions"] + Search_API["Search API"] + Security_Configuration["Security & Configuration"] + Nomad_Client -- "initializes and uses" --> Scaling_API + Nomad_Client -- "initializes and uses" --> Namespaces_API + Nomad_Client -- "initializes and uses" --> Variable_API + Nomad_Client -- "initializes and uses" --> Single_Namespace_API + Nomad_Client -- "initializes and uses" --> Sentinel_API + Nomad_Client -- "initializes and uses" --> Validation_API + Nomad_Client -- "initializes and uses" --> ACL_API + Nomad_Client -- "initializes and uses" --> Search_API + Scaling_API -- "inherits from" --> API_Requester_Base + Namespaces_API -- "inherits from" --> API_Requester_Base + Variable_API -- "inherits from" --> API_Requester_Base + Single_Namespace_API -- "inherits from" --> API_Requester_Base + Sentinel_API -- "inherits from" --> API_Requester_Base + Validation_API -- "inherits from" --> API_Requester_Base + ACL_API -- "inherits from" --> API_Requester_Base + Search_API -- "inherits from" --> API_Requester_Base + API_Requester_Base -- "raises" --> API_Exceptions + API_Requester_Base -- "handles" --> API_Exceptions + Security_Configuration -- "comprises" --> ACL_API + Security_Configuration -- "comprises" --> Namespaces_API + Security_Configuration -- "comprises" --> Single_Namespace_API + Security_Configuration -- "comprises" --> Variable_API + Security_Configuration -- "comprises" --> Scaling_API + Security_Configuration -- "comprises" --> Search_API + Security_Configuration -- "comprises" --> Sentinel_API + Security_Configuration -- "comprises" --> Validation_API +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the Nomad client's interaction with the Nomad API, focusing on security and configuration aspects. The `Nomad Client` acts as the primary interface, initializing and utilizing various API components such as `ACL API`, `Namespaces API`, `Variable API`, `Scaling API`, `Search API`, `Sentinel API`, and `Validation API`. All these specific API components inherit from the `API Requester Base`, which handles the fundamental HTTP request logic and error management, including raising and handling `API Exceptions`. The `Security & Configuration` meta-component encapsulates these individual API functionalities, providing a comprehensive view of how access control, organizational structures, dynamic data, and policy enforcement are managed within the Nomad ecosystem. + +### Nomad Client +The main client interface for interacting with the Nomad API. It initializes and provides access to various API categories like ACL, Namespaces, Scaling, etc. This component acts as the entry point for users to interact with the Nomad cluster. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.Nomad:__init__` (1:1000) +- `python-nomad.nomad.Nomad.get_uri` (1:1000) + + +### API Requester Base +This is the foundational component for all Nomad API interactions. It handles the core logic for making HTTP requests to the Nomad server, building endpoints and query strings, and managing common exceptions. All specific API client classes inherit from this base class. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester.__init__` (17:43) +- `nomad.api.base.Requester:_query_string_builder` (86:101) +- `nomad.api.base.Requester:request` (103:120) +- `nomad.api.base.Requester:_request` (122:220) +- `nomad.api.base.Requester._endpoint_builder` (45:50) +- `nomad.api.base.Requester._url_builder` (77:84) +- `nomad.api.base.Requester._required_namespace` (52:75) + + +### Scaling API +This component provides methods for interacting with Nomad's scaling policies. It allows users to retrieve and manage scaling policies within the Nomad cluster. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.scaling.Scaling:__init__` (17:18) +- `python-nomad.nomad.api.scaling.Scaling:get_scaling_policies` (31:59) +- `python-nomad.nomad.api.scaling.Scaling:get_scaling_policy` (61:74) + + +### Namespaces API +This component manages operations related to Nomad namespaces. It enables listing, retrieving, and iterating over namespaces, providing a way to organize resources within the Nomad cluster. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.namespaces.Namespaces:__init__` (17:18) +- `python-nomad.nomad.api.namespaces.Namespaces:__contains__` (30:40) +- `python-nomad.nomad.api.namespaces.Namespaces:__len__` (42:44) +- `python-nomad.nomad.api.namespaces.Namespaces:__getitem__` (46:56) +- `python-nomad.nomad.api.namespaces.Namespaces:__iter__` (58:60) +- `python-nomad.nomad.api.namespaces.Namespaces:get_namespaces` (62:75) + + +### Variable API +This component handles interactions with Nomad variables. It supports operations like retrieving, creating, and deleting variables, which are used for storing sensitive or configuration data. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.variable.Variable:__init__` (16:17) +- `python-nomad.nomad.api.variable.Variable:__contains__` (29:34) +- `python-nomad.nomad.api.variable.Variable:__getitem__` (36:40) +- `python-nomad.nomad.api.variable.Variable:get_variable` (42:58) +- `python-nomad.nomad.api.variable.Variable:create_variable` (60:85) +- `python-nomad.nomad.api.variable.Variable:delete_variable` (87:111) + + +### Single Namespace API +This component provides methods for managing a single Nomad namespace. It allows for creation, retrieval, updating, and deletion of individual namespaces. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.namespace.Namespace:__init__` (18:19) +- `python-nomad.nomad.api.namespace.Namespace:__contains__` (31:36) +- `python-nomad.nomad.api.namespace.Namespace:__getitem__` (38:49) +- `python-nomad.nomad.api.namespace.Namespace:get_namespace` (51:63) +- `python-nomad.nomad.api.namespace.Namespace:create_namespace` (65:78) +- `python-nomad.nomad.api.namespace.Namespace:update_namespace` (80:93) +- `python-nomad.nomad.api.namespace.Namespace:delete_namespace` (95:107) + + +### Sentinel API +This component is responsible for managing Sentinel policies within Nomad. It provides functionalities to get, create, update, and delete Sentinel policies, which are used for fine-grained access control. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.sentinel.Sentinel:__init__` (15:16) +- `python-nomad.nomad.api.sentinel.Sentinel:get_policies` (28:39) +- `python-nomad.nomad.api.sentinel.Sentinel:create_policy` (41:54) +- `python-nomad.nomad.api.sentinel.Sentinel:get_policy` (56:67) +- `python-nomad.nomad.api.sentinel.Sentinel:update_policy` (69:83) +- `python-nomad.nomad.api.sentinel.Sentinel:delete_policy` (85:98) + + +### Validation API +This component offers methods for validating Nomad job specifications. It allows users to check the syntax and structure of job definitions before submission to the Nomad cluster. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.validate.Validate:__init__` (17:18) +- `python-nomad.nomad.api.validate.Validate:validate_job` (30:44) + + +### ACL API +This component manages Access Control Lists (ACLs) in Nomad. It provides comprehensive functionalities for generating bootstrap tokens, managing tokens (get, create, delete, update), and managing policies (get, create, update, delete). + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.acl.Acl:__init__` (15:16) +- `python-nomad.nomad.api.acl.Acl:generate_bootstrap` (27:38) +- `python-nomad.nomad.api.acl.Acl:get_tokens` (40:52) +- `python-nomad.nomad.api.acl.Acl:get_token` (54:65) +- `python-nomad.nomad.api.acl.Acl:get_self_token` (67:78) +- `python-nomad.nomad.api.acl.Acl:create_token` (80:93) +- `python-nomad.nomad.api.acl.Acl:delete_token` (95:106) +- `python-nomad.nomad.api.acl.Acl:update_token` (108:122) +- `python-nomad.nomad.api.acl.Acl:get_policies` (124:135) +- `python-nomad.nomad.api.acl.Acl:create_policy` (137:150) +- `python-nomad.nomad.api.acl.Acl:get_policy` (152:163) +- `python-nomad.nomad.api.acl.Acl:update_policy` (165:179) +- `python-nomad.nomad.api.acl.Acl:delete_policy` (181:194) + + +### API Exceptions +This component defines custom exception classes specific to the Nomad API. These exceptions are raised by the API Requester Base component to indicate various error conditions encountered during API interactions, such as bad requests, unauthorized access, or timeouts. + + +**Related Classes/Methods**: + +- `nomad.api.exceptions.InvalidParameters` (35:36) +- `nomad.api.exceptions.BadRequestNomadException` (27:28) +- `nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24) +- `nomad.api.exceptions.URLNotFoundNomadException` (19:20) +- `nomad.api.exceptions.VariableConflict` (31:32) +- `nomad.api.exceptions.BaseNomadException` (6:16) +- `nomad.api.exceptions.TimeoutNomadException` (39:40) + + +### Search API +This component provides methods for searching various Nomad resources like jobs, allocations, nodes, and plugins, supporting both exact prefix matches and fuzzy searching. + + +**Related Classes/Methods**: + +- `python-nomad.nomad.api.search.Search:__init__` (20:21) +- `python-nomad.nomad.api.search.Search:search` (33:66) +- `python-nomad.nomad.api.search.Search:fuzzy_search` (68:98) + + +### Security & Configuration +This meta-component encapsulates the functionalities related to access control, organizational structures, dynamic data management, and policy enforcement within Nomad. It provides a unified view of how security, configuration, and operational policies are managed and applied across the Nomad cluster. + + +**Related Classes/Methods**: + +- `nomad.api.acl.Acl` (6:194) +- `nomad.api.namespace.Namespace` (8:107) +- `nomad.api.namespaces.Namespaces` (8:75) +- `nomad.api.variable.Variable` (8:111) +- `nomad.api.variables.Variables` (6:66) +- `nomad.api.scaling.Scaling` (8:74) +- `nomad.api.search.Search` (8:98) +- `nomad.api.sentinel.Sentinel` (6:98) +- `nomad.api.validate.Validate` (6:44) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Workload Orchestration.md b/.codeboarding/Workload Orchestration.md new file mode 100644 index 0000000..22a172d --- /dev/null +++ b/.codeboarding/Workload Orchestration.md @@ -0,0 +1,235 @@ +```mermaid +graph LR + NomadClient["NomadClient"] + APIRequester["APIRequester"] + JobsAPI["JobsAPI"] + DeploymentsAPI["DeploymentsAPI"] + EvaluationsAPI["EvaluationsAPI"] + AllocationsAPI["AllocationsAPI"] + ClientAPI["ClientAPI"] + ClientFileAndStreamOperations["ClientFileAndStreamOperations"] + ClientAllocationOperations["ClientAllocationOperations"] + APIExceptionHandling["APIExceptionHandling"] + NomadClient -- "initializes" --> JobsAPI + NomadClient -- "initializes" --> DeploymentsAPI + NomadClient -- "initializes" --> EvaluationsAPI + NomadClient -- "initializes" --> AllocationsAPI + NomadClient -- "initializes" --> ClientAPI + ClientAPI -- "aggregates" --> ClientFileAndStreamOperations + ClientAPI -- "aggregates" --> ClientAllocationOperations + JobsAPI -- "makes requests via" --> APIRequester + DeploymentsAPI -- "makes requests via" --> APIRequester + EvaluationsAPI -- "makes requests via" --> APIRequester + AllocationsAPI -- "makes requests via" --> APIRequester + ClientFileAndStreamOperations -- "makes requests via" --> APIRequester + ClientAllocationOperations -- "makes requests via" --> APIRequester + APIRequester -- "raises" --> APIExceptionHandling +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the Workload Orchestration subsystem within Nomad, focusing on how the `NomadClient` acts as the central entry point to various API components like `JobsAPI`, `DeploymentsAPI`, `EvaluationsAPI`, and `AllocationsAPI`. These API components, along with `ClientFileAndStreamOperations` and `ClientAllocationOperations` (aggregated by `ClientAPI`), all rely on the `APIRequester` for handling HTTP requests and error management, which in turn raises specific `APIExceptionHandling` exceptions for different failure scenarios. The main flow involves the `NomadClient` initializing and providing access to these specialized API interfaces for managing the lifecycle of applications and services in Nomad. + +### NomadClient +This is the main entry point for interacting with the Nomad API. It initializes various API client objects for different Nomad resources like jobs, allocations, deployments, evaluations, and client-side operations. + + +**Related Classes/Methods**: + +- `nomad.Nomad` (7:32) +- `nomad.Nomad.get_uri` (full file reference) + + +### APIRequester +This component provides the fundamental request-making capabilities for all Nomad API interactions. It handles URL building, query string parameters, and is responsible for executing HTTP requests and handling common API errors. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester` (10:220) +- `nomad.api.base.Requester._query_string_builder` (86:101) +- `nomad.api.base.Requester._required_namespace` (52:75) +- `nomad.api.base.Requester.request` (103:120) +- `nomad.api.base.Requester._request` (122:220) +- `nomad.api.base.Requester._endpoint_builder` (45:50) +- `nomad.api.base.Requester._url_builder` (77:84) + + +### JobsAPI +This component provides methods for managing Nomad jobs, including listing all jobs, retrieving details of a specific job, registering new jobs, and performing various job-related actions like planning, evaluating, and deregistering. + + +**Related Classes/Methods**: + +- `nomad.api.jobs.Jobs` (9:127) +- `nomad.api.jobs.Jobs.__init__` (20:21) +- `nomad.api.jobs.Jobs.__contains__` (33:44) +- `nomad.api.jobs.Jobs.__len__` (46:48) +- `nomad.api.jobs.Jobs.__getitem__` (50:61) +- `nomad.api.jobs.Jobs.__iter__` (63:65) +- `nomad.api.jobs.Jobs.get_jobs` (67:97) +- `nomad.api.jobs.Jobs.register_job` (99:109) +- `nomad.api.jobs.Jobs.parse` (111:127) +- `nomad.api.job.Job` (9:363) +- `nomad.api.job.Job.__init__` (19:20) +- `nomad.api.job.Job.__contains__` (32:37) +- `nomad.api.job.Job.__getitem__` (39:49) +- `nomad.api.job.Job.get_job` (51:70) +- `nomad.api.job.Job.get_versions` (72:84) +- `nomad.api.job.Job.get_allocations` (86:112) +- `nomad.api.job.Job.get_evaluations` (114:137) +- `nomad.api.job.Job.get_deployments` (139:151) +- `nomad.api.job.Job.get_deployment` (153:165) +- `nomad.api.job.Job.get_summary` (167:179) +- `nomad.api.job.Job.register_job` (181:193) +- `nomad.api.job.Job.evaluate_job` (195:208) +- `nomad.api.job.Job.plan_job` (210:229) +- `nomad.api.job.Job.periodic_job` (231:246) +- `nomad.api.job.Job.dispatch_job` (248:277) +- `nomad.api.job.Job.revert_job` (279:301) +- `nomad.api.job.Job.stable_job` (303:318) +- `nomad.api.job.Job.deregister_job` (320:363) + + +### DeploymentsAPI +This component handles interactions with Nomad deployments, allowing listing all deployments, retrieving details of a specific deployment, and managing deployment lifecycle actions such as pausing, promoting, and failing. + + +**Related Classes/Methods**: + +- `nomad.api.deployments.Deployments` (8:78) +- `nomad.api.deployments.Deployments.__init__` (17:18) +- `nomad.api.deployments.Deployments.__len__` (29:31) +- `nomad.api.deployments.Deployments.__iter__` (33:35) +- `nomad.api.deployments.Deployments.__contains__` (37:46) +- `nomad.api.deployments.Deployments.__getitem__` (48:56) +- `nomad.api.deployments.Deployments.get_deployments` (58:78) +- `nomad.api.deployment.Deployment` (8:172) +- `nomad.api.deployment.Deployment.__init__` (17:18) +- `nomad.api.deployment.Deployment.__contains__` (30:35) +- `nomad.api.deployment.Deployment.__getitem__` (37:44) +- `nomad.api.deployment.Deployment.get_deployment` (46:58) +- `nomad.api.deployment.Deployment.get_deployment_allocations` (60:72) +- `nomad.api.deployment.Deployment.fail_deployment` (74:88) +- `nomad.api.deployment.Deployment.pause_deployment` (90:105) +- `nomad.api.deployment.Deployment.promote_deployment_all` (107:122) +- `nomad.api.deployment.Deployment.promote_deployment_groups` (124:141) +- `nomad.api.deployment.Deployment.deployment_allocation_health` (143:172) + + +### EvaluationsAPI +This component provides an interface for querying and managing Nomad evaluations, which represent the outcome of job submissions and updates. It allows listing all evaluations and retrieving details for a specific evaluation. + + +**Related Classes/Methods**: + +- `nomad.api.evaluations.Evaluations` (8:75) +- `nomad.api.evaluations.Evaluations.__init__` (19:20) +- `nomad.api.evaluations.Evaluations.__contains__` (31:41) +- `nomad.api.evaluations.Evaluations.__len__` (43:45) +- `nomad.api.evaluations.Evaluations.__getitem__` (47:56) +- `nomad.api.evaluations.Evaluations.__iter__` (58:60) +- `nomad.api.evaluations.Evaluations.get_evaluations` (62:75) +- `nomad.api.evaluation.Evaluation` (8:74) +- `nomad.api.evaluation.Evaluation.__init__` (19:20) +- `nomad.api.evaluation.Evaluation.__contains__` (32:37) +- `nomad.api.evaluation.Evaluation.__getitem__` (39:46) +- `nomad.api.evaluation.Evaluation.get_evaluation` (48:60) +- `nomad.api.evaluation.Evaluation.get_allocations` (62:74) + + +### AllocationsAPI +This component manages Nomad allocations, which are the actual instances of tasks running on client nodes. It allows listing all allocations, retrieving details about a specific allocation, and stopping allocations. + + +**Related Classes/Methods**: + +- `nomad.api.allocations.Allocations` (8:83) +- `nomad.api.allocations.Allocations.__init__` (19:20) +- `nomad.api.allocations.Allocations.__len__` (31:33) +- `nomad.api.allocations.Allocations.__iter__` (35:37) +- `nomad.api.allocations.Allocations.get_allocations` (39:83) +- `nomad.api.allocation.Allocation` (8:73) +- `nomad.api.allocation.Allocation.__init__` (19:20) +- `nomad.api.allocation.Allocation.__contains__` (31:39) +- `nomad.api.allocation.Allocation.__getitem__` (41:49) +- `nomad.api.allocation.Allocation.get_allocation` (51:61) +- `nomad.api.allocation.Allocation.stop_allocation` (63:73) + + +### ClientAPI +This component acts as a facade for various client-side operations within Nomad, aggregating functionalities related to file system interactions, streaming data, and specific allocation management on client nodes. + + +**Related Classes/Methods**: + +- `nomad.api.client.Client` (7:32) +- `nomad.api.client.Client.__init__` (12:22) + + +### ClientFileAndStreamOperations +This component provides functionalities for interacting with the file system on Nomad client nodes, including listing files, reading file content, and streaming logs or file data from allocations. + + +**Related Classes/Methods**: + +- `nomad.api.client.ls` (35:65) +- `nomad.api.client.ls.__init__` (46:47) +- `nomad.api.client.ls.list_files` (49:65) +- `nomad.api.client.cat` (68:99) +- `nomad.api.client.cat.__init__` (80:81) +- `nomad.api.client.cat.read_file` (83:99) +- `nomad.api.client.stat` (205:235) +- `nomad.api.client.stat.__init__` (216:217) +- `nomad.api.client.stat.stat_file` (219:235) +- `nomad.api.client.read_at` (102:130) +- `nomad.api.client.read_at.__init__` (111:112) +- `nomad.api.client.read_at.read_file_offset` (114:130) +- `nomad.api.client.stream_file` (133:161) +- `nomad.api.client.stream_file.__init__` (142:143) +- `nomad.api.client.stream_file.stream` (145:161) +- `nomad.api.client.stream_logs` (164:202) +- `nomad.api.client.stream_logs.__init__` (173:174) +- `nomad.api.client.stream_logs.stream` (176:202) + + +### ClientAllocationOperations +This component manages specific allocation-related operations on Nomad client nodes, such as reading allocation statistics, restarting or signaling allocations, and performing garbage collection on allocations. + + +**Related Classes/Methods**: + +- `nomad.api.client.allocation` (267:321) +- `nomad.api.client.allocation.__init__` (279:280) +- `nomad.api.client.allocation.read_allocation_stats` (282:293) +- `nomad.api.client.allocation.restart_allocation` (295:305) +- `nomad.api.client.allocation.signal_allocation` (307:321) +- `nomad.api.client.stats` (238:264) +- `nomad.api.client.stats.__init__` (249:250) +- `nomad.api.client.stats.read_stats` (252:264) +- `nomad.api.client.gc_allocation` (324:347) +- `nomad.api.client.gc_allocation.__init__` (333:334) +- `nomad.api.client.gc_allocation.garbage_collect` (336:347) +- `nomad.api.client.gc_all_allocations` (350:372) +- `nomad.api.client.gc_all_allocations.__init__` (359:360) +- `nomad.api.client.gc_all_allocations.garbage_collect` (362:372) + + +### APIExceptionHandling +This component defines and encapsulates various custom exception types that can be raised during interactions with the Nomad API, providing specific error handling for different failure scenarios like bad requests, unauthorized access, or timeouts. + + +**Related Classes/Methods**: + +- `nomad.api.exceptions.BadRequestNomadException` (27:28) +- `nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24) +- `nomad.api.exceptions.URLNotFoundNomadException` (19:20) +- `nomad.api.exceptions.VariableConflict` (31:32) +- `nomad.api.exceptions.BaseNomadException` (6:16) +- `nomad.api.exceptions.TimeoutNomadException` (39:40) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 0000000..023a3c3 --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,136 @@ +```mermaid +graph LR + Nomad_Client_Core["Nomad Client Core"] + API_Request_Layer["API Request Layer"] + Workload_Orchestration["Workload Orchestration"] + Cluster_Management["Cluster Management"] + Security_Configuration["Security & Configuration"] + Event_Stream["Event Stream"] + Exception_Handling["Exception Handling"] + Nomad_Client_Core -- "Initializes" --> Workload_Orchestration + Nomad_Client_Core -- "Initializes" --> Cluster_Management + Nomad_Client_Core -- "Initializes" --> Security_Configuration + Nomad_Client_Core -- "Initializes" --> Event_Stream + Workload_Orchestration -- "Utilizes" --> API_Request_Layer + Cluster_Management -- "Utilizes" --> API_Request_Layer + Security_Configuration -- "Utilizes" --> API_Request_Layer + Event_Stream -- "Utilizes" --> API_Request_Layer + API_Request_Layer -- "Raises" --> Exception_Handling + Workload_Orchestration -- "Raises" --> Exception_Handling + Cluster_Management -- "Raises" --> Exception_Handling + Security_Configuration -- "Raises" --> Exception_Handling + Event_Stream -- "Raises" --> Exception_Handling + click Nomad_Client_Core href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/Nomad Client Core.md" "Details" + click API_Request_Layer href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/API Request Layer.md" "Details" + click Workload_Orchestration href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/Workload Orchestration.md" "Details" + click Cluster_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/Cluster Management.md" "Details" + click Security_Configuration href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/Security & Configuration.md" "Details" + click Event_Stream href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/Event Stream.md" "Details" + click Exception_Handling href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/python-nomad/Exception Handling.md" "Details" +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The `python-nomad` library provides a comprehensive Python client for interacting with the Nomad cluster. Its architecture is designed with a clear separation of concerns, where a central client core initializes and orchestrates various API-specific modules. All interactions with the Nomad API are channeled through a dedicated request layer, which handles the underlying HTTP communication and robust error management. This design ensures modularity, maintainability, and efficient interaction with the Nomad cluster's diverse functionalities, from workload orchestration to cluster management and security configurations. + +### Nomad Client Core +The primary entry point for the python-nomad library, responsible for initializing the connection to the Nomad cluster and providing access to all other API-specific client modules. It acts as the central interface for users to interact with the Nomad cluster. + + +**Related Classes/Methods**: + +- `nomad.Nomad:__init__` (30:60) +- `nomad.Nomad.get_uri` (62:65) + + +### API Request Layer +A foundational component that abstracts the complexities of making HTTP requests to the Nomad API. It handles URL construction, query parameter building, request execution, and robust error handling, serving as the underlying communication mechanism for all other API client modules. + + +**Related Classes/Methods**: + +- `nomad.api.base.Requester:__init__` (17:43) +- `nomad.api.base.Requester:request` (103:120) +- `nomad.api.base.Requester:_request` (122:220) +- `nomad.api.base.Requester._url_builder` (77:84) + + +### Workload Orchestration +Manages the lifecycle of applications and services within Nomad, encompassing operations related to jobs (definition, registration, evaluation), deployments (tracking, promotion, failure), and allocations (listing, stopping, client-side file system interactions and statistics). + + +**Related Classes/Methods**: + +- `nomad.api.job.Job` (9:363) +- `nomad.api.jobs.Jobs` (9:127) +- `nomad.api.deployment.Deployment` (8:172) +- `nomad.api.deployments.Deployments` (8:78) +- `nomad.api.allocation.Allocation` (8:73) +- `nomad.api.allocations.Allocations` (8:83) +- `nomad.api.client.Client` (7:32) +- `nomad.api.evaluation.Evaluation` (8:74) +- `nomad.api.evaluations.Evaluations` (8:75) + + +### Cluster Management +Provides functionalities for monitoring and controlling the Nomad cluster's infrastructure. This includes managing agents and nodes, retrieving cluster status and metrics, performing operator-level actions, and interacting with multi-region deployments. + + +**Related Classes/Methods**: + +- `nomad.api.agent.Agent` (6:98) +- `nomad.api.node.Node` (9:193) +- `nomad.api.nodes.Nodes` (10:95) +- `nomad.api.operator.Operator` (6:64) +- `nomad.api.system.System` (6:52) +- `nomad.api.status.Status` (8:27) +- `nomad.api.metrics.Metrics` (6:42) +- `nomad.api.regions.Regions` (8:68) + + +### Security & Configuration +Handles access control, organizational structures, and dynamic data within Nomad. This includes managing ACL tokens and policies, creating and managing namespaces, interacting with Nomad variables, and utilities for scaling policies, search, Sentinel policies, and job validation. + + +**Related Classes/Methods**: + +- `nomad.api.acl.Acl` (6:194) +- `nomad.api.namespace.Namespace` (8:107) +- `nomad.api.namespaces.Namespaces` (8:75) +- `nomad.api.variable.Variable` (8:111) +- `nomad.api.variables.Variables` (6:66) +- `nomad.api.scaling.Scaling` (8:74) +- `nomad.api.search.Search` (8:98) +- `nomad.api.sentinel.Sentinel` (6:98) +- `nomad.api.validate.Validate` (6:44) + + +### Event Stream +Dedicated component for establishing and managing real-time event streams from the Nomad server, allowing for continuous monitoring of cluster activities and changes. + + +**Related Classes/Methods**: + +- `nomad.api.event.Event` (12:27) +- `nomad.api.event.stream` (31:133) + + +### Exception Handling +A collection of custom exception classes designed to provide specific error information when interactions with the Nomad API fail, enabling more granular error management and debugging within the client library. + + +**Related Classes/Methods**: + +- `nomad.api.exceptions.BaseNomadException` (6:16) +- `nomad.api.exceptions.InvalidParameters` (35:36) +- `nomad.api.exceptions.BadRequestNomadException` (27:28) +- `nomad.api.exceptions.URLNotAuthorizedNomadException` (23:24) +- `nomad.api.exceptions.URLNotFoundNomadException` (19:20) +- `nomad.api.exceptions.VariableConflict` (31:32) +- `nomad.api.exceptions.TimeoutNomadException` (39:40) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file