Merge new documentation updates

LorenzoTettamanti · LorenzoTettamanti · commit 90e752c0b479 · 2025-09-02T21:51:32.000+02:00
diff --git a/Doc/docs/cfcli/Agent-API-Overview.md b/Doc/docs/cfcli/Agent-API-Overview.md
@@ -0,0 +1,2 @@
+!!! warning
+    This part is work in progress
diff --git a/Doc/docs/cfcli/overview.md b/Doc/docs/cfcli/overview.md
@@ -0,0 +1,78 @@
+# CortexFlow CLI
+
+CortexFlow provides a command-line interface to interact with the **CortexBrain** core components via a gRPC API.  
+
+The tool is called **`cfcli`**.  
+
+This document describes the available commands and provides a quick reference table.
+
+
+## 📦 Setup Commands
+
+- **`cfcli install cortexflow`**  
+  Installs **all** CortexBrain core components.  
+
+- **`cfcli install simple-example`**  
+  Installs a demo example defined in [deploy-test-pod.yaml](https://github.com/CortexFlow/CortexBrain/blob/main/core/src/testing/deploy-test-pod.yaml).  
+
+- **`cfcli uninstall`** 
+  Uninstalls **all** CortexBrain components.  
+
+
+## ⚙️ CLI Management Commands
+
+- **`cfcli update`**  
+  Checks if the current `cfcli` version is up to date.  
+
+- **`cfcli info`**  
+  Displays CLI metadata, including:  
+    - version  
+    - authors  
+    - description  
+    - installation environment (Kubernetes, Docker, etc.)  
+
+
+## 📝 Logging Commands
+
+- **`cfcli logs`**  
+  Retrieves logs for a specified pod.  
+
+
+## 📊 Monitoring and Status Commands
+
+- **`cfcli status`**  
+  Performs a health check of the CortexBrain core:  
+    - Validates if the `cortexflow` namespace exists.  
+    - Returns the status of all core components.  
+
+- **`cfcli monitoring list`**  
+  Lists available CortexFlow agent endpoints.  
+    - Useful for checking supported agent API functionalities.  
+    - Returns an error if the agent is not running.  
+
+- **`cfcli monitoring connections`**  
+  Displays currently logged connections from the **Identity** service.  
+    - Reads data from `events_map`.  
+    - Shows the most recent detected events.  
+
+
+## 📑 Command Reference Table
+
+| Command                        | Category             | Description                                                                 |
+|--------------------------------|----------------------|-----------------------------------------------------------------------------|
+| `cfcli install cortexflow`     | Installation         | Installs all CortexBrain core components                                    |
+| `cfcli install simple-example` | Installation         | Installs a demo example from `deploy-test-pod.yaml`                         |
+| `cfcli uninstall`              | Installation         | Uninstalls all CortexBrain components                                       |
+| `cfcli update`                 | CLI Management       | Checks if the CLI version is up to date                                     |
+| `cfcli info`                   | CLI Management       | Displays version, authors, description, and environment metadata            |
+| `cfcli logs`                   | Logging              | Retrieves logs for a specified pod                                          |
+| `cfcli status`                 | Monitoring / Status  | Runs a health check and validates the `cortexflow` namespace                |
+| `cfcli monitoring list`        | Monitoring / Status  | Lists CortexFlow agent endpoints                                            |
+| `cfcli monitoring connections` | Monitoring / Status  | Displays logged connections from the Identity service                       |
+
+---
+
+## Examples
+### How to interact with the cortexflow agent
+!!! warning
+    This part is work in progress
diff --git a/Doc/docs/getting-started/installation.md b/Doc/docs/getting-started/installation.md
@@ -17,7 +17,7 @@ CortexFlow CLI is hosted using cargo package manager. The current vesion is **0.
 ### **Components Installation**
 Once you have installed the CLI you can run the following command to install **all** the CortexBrain components  
 ``` bash
-   cfcli install
+   cfcli install cortexflow
 ```
 cfcli stores relevant information to interoperates with your cluster environment, up to now these information are limited to the cluster environment. 
 
diff --git a/Doc/docs/index.md b/Doc/docs/index.md
@@ -17,13 +17,28 @@ You can see the development stage of every component here:
 
 A **service mesh** is a specialized infrastructure layer embedded within a software application that manages communication between services. It handles critical functions such as traffic routing, security, observability, and resiliency, while shielding individual services from these complexities.
 
-In modern applications, functionality is often divided into a network of specialized services, each performing a specific task. To fulfill its role, a service may need to request data from multiple other services. However, issues arise when certain services, like a retailer’s inventory database, become overwhelmed with requests. This is where a service mesh proves invaluable it orchestrates and optimizes communication between services, ensuring all components work seamlessly together.
+In modern applications, functionality is often divided into a network of specialized services, each performing a specific task. To fulfill its role, a service may need to request data from multiple other services. However, issues arise when certain services, like a retailer’s inventory database, become overwhelmed with requests. This is where a service mesh proves invaluable. It orchestrates and optimizes the communication between services, ensuring all components work seamlessly together.
+
+## **Challenges of Traditional Service Mesh**
+While service meshes have proven beneficial for managing microservices, they come with inherent challenges. The traditional sidecar model introduces additional components and complexity, requiring teams to acquire new skills for effective management. A traditional "sidecar-based" service mesh has potential drawbacks that can impact directly the performances and the average costs of your clusters. Running sidecar containers alongside your containerized application directly impacts the CPU consumptions and the memory that your workloads consume. Due to its nature sidecar containers also have to work harder to collect data because they run in user space, and therefore don’t have direct access to kernel-level resources and the same reasoning can be applied to all the other service mesh features such as observability and security. The main drawbacks of a sidecar based service mesh can be resumed in the following chart:
+
+| **Service mesh features**                         | **Drawbacks / Related issues**  |
+|-----------------------------------|-----------------------------------------------------|
+| **Overhead**    | Traditional sidecar approach introduce high overhead and resource consumption due to the attachment of a sidecar container. The sidecar is pretty expensive also in latency terms because every communication between pods are managed by the sidecar container|
+| **Granularity**    | A sidecar approach is less customizable because has limited access to lower level insights    |
+
+
+## **Service Mesh Optimization with eBPF**
+eBPF is a powerful technology that allows for high-performance networking and security enhancements by executing code directly in the Linux kernel without changing the kernel source code or requiring a reboot. By leveraging eBPF, developers can attach programs to various network events, enabling efficient management of communication between microservices, enhanced metrics and observability and enhanced security features.
 
 # **Architecture**
 The CortexFlow architecture is designed to ensure a robust, scalable, and fault-tolerant system that can operate seamlessly without interruptions. It is composed of several key components that work together to provide a continuous and reliable infrastructure. These components are orchestrated within a Kubernetes cluster, ensuring efficient resource management, high availability, and scalability. Below is a GIF that visually represents the architecture and illustrates how the components interact within the cluster.
 
 ![Architecture](./cf_architecture.svg "Cortexflow architecture")
 
+## What's eBPF?
+Extended Berkeley Packet Filter (eBPF) presents a transformative approach to building service meshes by eliminating the need for the traditional sidecar model, which often introduces significant complexity and overhead in microservices architecture. eBPF allows for the implementation of service mesh functionalities directly in the kernel, resulting in a more efficient and streamlined data plane. This native integration minimizes the number of proxies required, reduces additional network connections, and simplifies redirection logic for network traffic, thereby enhancing performance.
+
 ## **User space vs kernel space**
 In the Linux kernel the **user space** is the environment where user-facing applications run. This includes applications such as web servers, Chrome, text editors, and command utilities. User space applications are also known as userland applications.
 
@@ -50,7 +65,7 @@ Cortexflow core components, also referred to as CortexBrain components, are comp
 ## **CLI**
 The command line interface, also known as CLI, is an essential part of the CortexFlow User Experience. It allows users and developers to interact with all the core components without directly managing the manifests' YAML files. The CLI stores the relevant information, such as the underlying cluster environment (e.g., Kubernetes, Docker Swarm, etc), to support multiple environments without changing the user experience. Right now, the CLI only supports **Kubernetes** as an orchestrator.
 
- The CLI is available to install with the cargo package manager; we have carefully documented the installation in this [page](./tools/tools.md).
+ The CLI is available to install with the cargo package manager; we have carefully documented the installation in this [page](./cfcli/overview.md).
 
 !!! warning
     Right now, the identity service, metrics, and dashboard are under development until 2026. We will release the first documentation snippet soon
diff --git a/Doc/docs/tools/tools.md b/Doc/docs/tools/tools.md
diff --git a/Doc/mkdocs.yml b/Doc/mkdocs.yml
@@ -89,8 +89,10 @@ plugins:
 
 nav:
   - Home: index.md
-  - Getting Started: installation/installation.md
-  - Tools: tools/tools.md
+  - Getting Started: getting-started/installation.md
+  - CLI: 
+    - cfcli/overview.md
+    - cfcli/Agent-API-Overview.md
   - Test Report: 
     - test-report/test-report.md
     - Reports:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+!!! warning`
	`2`	`+ This part is work in progress`