Skip to content

edits to agents and app orch #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
swpng merged 4 commits into from
May 5, 2025
Merged

edits to agents and app orch #13

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ffba98b
edits to agents and app orch
adreanneb Apr 29, 2025
d7f7cc2
Merge branch 'main' into dev-guide-edits
adreanneb Apr 29, 2025
bee1970
comments addressed
adreanneb Apr 30, 2025
a59e1e6
Merge branch 'main' into dev-guide-edits
swpng May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 21 additions & 22 deletions docs/developer_guide/agents/arch/cluster.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Background
----------

This document provides high-level design and implementation guidelines. Refer
to `Cluster Agent <https://github.com/open-edge-platform/edge-node-agents/tree/main/cluster-agent>`_ in Edge Node Agents' GitHub repository for implementation
to `Cluster Agent <https://github.com/open-edge-platform/edge-node-agents/tree/main/cluster-agent>`_ in the Edge Node Agents' GitHub\* repository for implementation
details.

Target Audience
Expand All @@ -24,12 +24,12 @@ Overview

Cluster Agent is part of the Open Edge Platform's Edge Node Zero Touch
Provisioning. It is installed, configured and automatically executed at
Provisioning time. It registers itself in Edge Cluster Manager of the Edge
Provisioning time. It registers itself in Edge Cluster Manager of the Edge
Orchestrator service and bootstrap/uninstall the Kubernetes Engine on the Edge
Node on which it is executing.

Architecture Diagram
-----------------------
--------------------

The Cluster Agents follows the architecture and design principles set out in
:doc:`hl_architecture`
Expand All @@ -40,7 +40,7 @@ The Cluster Agents follows the architecture and design principles set out in
Figure 1: High-Level Architecture of Cluster Agent

Key Components
----------------
--------------

1. The Cluster Agent is a system daemon packaged as a `.deb` or `.rpm` package
(depending on target Operating System).
Expand All @@ -53,7 +53,7 @@ Data Flow
---------

The data flow of the Cluster Agent can be broken down into multiple concepts
called out in `Workflow Stages` section.
called out in the `Workflow Stages` section.

Workflow Stages
~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -83,7 +83,7 @@ Figure 2: Cluster Agent state machine

Configuration consists of:

- The config file which is part of cluster-agent Debian/RPM package and
- The config file, which is part of cluster-agent Debian/RPM package and
installed at ``/etc/edge-node/node/confs/cluster-agent.yaml``

- The JWT token at /etc/intel_edge_node/tokens/cluster-agent
Expand Down Expand Up @@ -130,8 +130,7 @@ Figure 3: Cluster Agent configuration

1. **Cluster Agent status update**:

Cluster Agent sends it's current status to *Edge Cluster Manager* in the
Edge Orchestrator on regular intervals. In response, it can receive request
Cluster Agent sends its current status to Edge Cluster Manager in |software_prod_name| on regular intervals. In response, it can receive a request
to transition to a new state.

.. mermaid::
Expand All @@ -154,7 +153,7 @@ Figure 4: Cluster Agent status update

1. **Kubernetes Engine Installation flow**:

While in **registering** state Cluster Agent request Kubernetes Engine
While in **registering** state Cluster Agent, request Kubernetes Engine
installation command via RPC from **Edge Cluster Manager**.

.. mermaid::
Expand Down Expand Up @@ -185,7 +184,7 @@ Figure 5: Cluster Agent Kubernetes Engine installation

4. **Kubernetes Engine Uninstallation flow**:

While in **deregistering** state Cluster Agent request Kubernetes Engine
While in **deregistering** state Cluster Agent, request Kubernetes Engine
uninstallation command via RPC from **Edge Cluster Manager**.

.. mermaid::
Expand Down Expand Up @@ -219,7 +218,7 @@ The Cluster Agent receives and runs installation and uninstallation
commands/scripts to be executed on the Edge Node from the **Edge Cluster
Manager**.

To extend the support for bootstrapping new Kubernetes Engines an appropriate
To extend the support for bootstrapping new Kubernetes Engines, an appropriate
set of commands should be send from **ECM** to the Cluster Agent.

Deployment
Expand All @@ -237,24 +236,24 @@ Agent's technology stack.
Implementation
~~~~~~~~~~~~~~

The Cluster Agent is written in Go programming language, it is implemented as a
The Cluster Agent is written in Go programming language and is implemented as a
state machine. Cluster Agent does not persist any data on disk nor in database
as all state is in memory. Previous state is re-created after reboot by
as all state is in memory. Previous state is re-created after reboot by
following state machine from the beginning (each state just finishes early if
it was already executed). This implementation allows for crash recovery and
updates to not require special attention.
it was already executed). This implementation allows for crash recovery and
updates do not require special attention.

The Cluster agent is agnostic of the Open Edge Platform's Kubernetes
Engine implementation used. The scripts/commands provided to the Cluster Agent
by the **Edge Cluster Manager** should be idempotent. Cluster Agent performs
by the **Edge Cluster Manager** should be idempotent. Cluster Agent performs
both Kubernetes Engine installation & uninstallation via abstraction of a shell
scripts. Edge Cluster Manager should store multiple pairs of shell scripts for
script. Edge Cluster Manager should store multiple pairs of shell scripts for
different Kubernetes Engine implementations and return appropriate pair to the
Cluster Agent for execution. Both scripts are assumed to be idempotent. This
means they could be executed multiple times safely. Subsequent executions of
Cluster Agent for execution. Both scripts are assumed to be idempotent. This
means they could be executed multiple times safely. Subsequent executions of
the same script either progresses overall execution (if it was not completed)
or exits early (if previously completed), which is an important property in the
context of crash recovery. Cluster Agent should be able to execute the same
context of crash recovery. Cluster Agent should be able to execute the same
command again after intermediate failure and progress.

System Diagram
Expand All @@ -278,11 +277,11 @@ Cluster Agent does not expose any API. It consumes APIs from both Edge Cluster
Manager and Node Agent.

- Edge Cluster Manager - Communication with Edge Cluster Manager is implemented
via gRPC protocol. Edge Cluster Manager acts as a server, Cluster Agent acts
via gRPC protocol. Edge Cluster Manager acts as a server; Cluster Agent acts
as a client.

- Node Agent - Communication with Node Agent is implemented via a text file
stored on a host filesystem. When
stored on a host filesystem. When
``/etc/intel_edge_node/tokens/cluster-agent/access_token`` is created it is
interpreted as signal to start communication with Edge Cluster Manager.

Expand Down
32 changes: 15 additions & 17 deletions docs/developer_guide/agents/arch/edge_node.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ Edge Node Agent
Background
----------

This document provides high level design and implementation guidelines. Refer
to `Node Agent <https://github.com/open-edge-platform/edge-node-agents/tree/main/node-agent>`_ in Edge Node Agents' GitHub repository for implementation
This document provides high-level design and implementation guidelines. Refer
to `Node Agent <https://github.com/open-edge-platform/edge-node-agents/tree/main/node-agent>`_ in the Edge Node Agents' GitHub\* repository for implementation
details.

Target Audience
Expand All @@ -29,21 +29,19 @@ Node Agent interacts with Host Manager to send heartbeats from the node as it
runs indefinitely.

The second responsibility of the Node Agent is to obtain JWT tokens for all
other agents running on the Edge Node.

For this, the agent uses OAuth 2.0 Client Credential Grant which requires a
other agents running on the Edge Node. For this, the agent uses OAuth 2.0 Client Credential Grant, which requires a
pair of credentials on the Edge Node.

The Node Agent makes API calls to Keycloak IDP Service to obtain fresh and
renewed JWT tokens. It authenticates to the Keycloak IDP Service using the
The Node Agent makes API calls to Keycloak\* IDP Service to obtain fresh and
renewed JWT tokens. It authenticates to the Keycloak IDP Service using the
credentials provisioned on the Edge Node during provisioning.

Node Agent is also responsible for the setting up of Caddy proxy.

Caddy is a third party proxy server being used as a forward proxy on the Edge
Node. This serves as a forward proxy for containerd and apt client that runs
on Edge Node. It appends JWT token to requests from either of the clients.
Node Agent installs Caddy as a dependency in the Debian/RPM package.
Node. This serves as a forward proxy for containerd and apt client that runs
on Edge Node. It appends JWT token to requests from either of the clients.
Node Agent installs Caddy as a dependency in the Debian\* and RPM package.

Architecture Diagram
--------------------
Expand All @@ -66,20 +64,20 @@ Key Components

3. The Node Agent requires a designated JWT token.

4. The Node Agent kickstarts deployment of Caddy proxy.
4. The Node Agent kick starts deployment of Caddy proxy.

Data Flow
---------

The data flow of the Node Agent can be broken down into multiple concepts
called out in `Workflow Stages` section.
called out in the `Workflow Stages` section.

Workflow Stages
~~~~~~~~~~~~~~~

1. **Caddy as forward proxy**: Following diagram illustrates how Caddy is
installed and configured during provisioning. It also captures the token
refresh mechanism which ensures Caddy always uses an updated token in the
1. **Caddy as forward proxy**: The following diagram illustrates how Caddy is
installed and configured during provisioning. It also captures the token
refresh mechanism, which ensures Caddy always uses an updated token in the
header of the outgoing request.

.. figure:: ./images/caddy-architecture.png
Expand Down Expand Up @@ -120,9 +118,9 @@ Figure 3: Secrets Provisioning Sequence Flow

3. **Access Token Renewal**:

Refresh token is no used to renew the access token.
Refresh token is not used to renew the access token.

As per the `RFC 6749 <https://datatracker.ietf.org/doc/html/rfc6749>_,` a
As per the `RFC 6749 <https://datatracker.ietf.org/doc/html/rfc6749>`_, a
refresh token is not required to be used for Client Credentials Grant.

Whenever an access token needs to be refreshed, *client_id/client_secret*
Expand Down
14 changes: 7 additions & 7 deletions docs/developer_guide/agents/arch/hardware_discovery.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Background
----------

This document provides high-level design and implementation guidelines. Refer
to `Hardware Discovery Agent <https://github.com/open-edge-platform/edge-node-agents/tree/main/hardware-discovery-agent>`_ in the Edge Node Agents' GitHub repository for
to `Hardware Discovery Agent <https://github.com/open-edge-platform/edge-node-agents/tree/main/hardware-discovery-agent>`_ in the Edge Node Agents' GitHub\* repository for
implementation details.

Target Audience
Expand Down Expand Up @@ -38,7 +38,7 @@ Architecture Diagram
--------------------

The Hardware Discovery Agents follows the architecture and design principles
set out in :doc:`hl_architecture`
set out in :doc:`hl_architecture`.

.. figure:: ./images/hda-architecture.drawio.svg
:alt: High-Level Architecture of the Hardware Discovery Agent
Expand Down Expand Up @@ -67,8 +67,8 @@ Workflow Stages
1. **Hardware Discovery Agent Workflow**:

The Hardware Discovery Agent retrieves its access token on start, gathers
the Edge Node's hardware information and sends the data to the Hardware
Resource Manager on the Edge Orchestrator.
the Edge Node's hardware information, and sends the data to the Hardware
Resource Manager on |software_prod_name|.

It then pauses and repeats the HW information gathering and forwarding
steps.
Expand Down Expand Up @@ -154,7 +154,7 @@ includes tools such as:
- ``lsusb``, which provides information on USB devices connected to the Edge
Node.

- ``lshw`` and ``lspci``, which provides information on GPU devices on the Edge
- ``lshw`` and ``lspci``, which provide information on GPU devices on the Edge
Node.

- ``ip``, which provides information on IP addresses associated with interfaces
Expand All @@ -179,7 +179,7 @@ System Diagram
Hardware Discovery Agent is dependent on DKAM, Node Agent, and Hardware
Resource Manager.

Required OS tools dependencies are listed in the Hardware Discovery Agent's
Required OS tool dependencies are listed in the Hardware Discovery Agent's
Debian Control file in the source repository.

.. mermaid::
Expand All @@ -195,7 +195,7 @@ Integrations
~~~~~~~~~~~~

Hardware Discovery Agent does not expose any API. It consumes APIs from the
Hardware Resource Manager. Communication with Hardware Resource Manager is
Hardware Resource Manager. Communication with Hardware Resource Manager is
implemented using gRPC. Hardware Resource Manager acts as a server, Hardware
Discovery Agent acts as a client.

Expand Down
Loading
Loading