Update docs

## Prerequisites

### Control Node (Your Laptop)

- **OS**: Linux (tested on Ubuntu/Debian) or macOS

- **Python**: Version 3.8 or higher

- **Python venv**: Support for virtual environments

- **SSH Client**: To connect to the target machine

### Managed Node (Target VM)

- **OS**: Linux (Ubuntu 20.04/22.04 recommended)

- **SSH Server**: Running and accessible from the Control Node

- **User Access**: Sudo privileges for the connection user

# Quick Start Guide

## Prepare The Inventory

This guide covers deployment options for the Operator Platform.

This quick start guide will guide you through the initial steps to deploy and manage the Operator Platform using the provided Ansible automation framework.

## "Single OOP Deployment (Kind)"

First is recommended to start with a clean VM running Ubuntu 24.04. Then, add the VM details to the inventory file and configure SSH access. So in the `inventory/hosts.yml` file, add your VM's IP address and SSH user credentials:

This is the fastest way to get a full-ish Operator Platform environment running. It deploys a lightweight Kubernetes cluster (using [Kind](https://kind.sigs.k8s.io/)) on a single machine and installs all components automatically. It is ideal for quickly testing the OOP.

### 1. Prepare The Inventory

Add your target machine (e.g., a fresh Ubuntu VM) to `ansible/inventory/hosts.yml`, or even your laptop for a quick test.

```yaml

    all:

          ansible_host: your_vm_ip

          ansible_user: your_ssh_user

          ansible_ssh_private_key_file: /path/to/your/private/key

```

Also, make sure the host `your_vm_name` is included in the appropriate group or children section:

```yaml

      children:

        kind_cluster:

          hosts:

            your_vm_name:

```

Then, you can proceed with running the Ansible playbooks to deploy and manage the Operator Platform on your VM.

### 2. Deploy Everything

## Install Dependencies

Run the "Single OOP" scenario playbook. This handles the needded python dependencies, installs docker if not installed already, creates a kubernetes cluster, and installs a minimal number of OOP components. Specifically, this playbook install the following modules:

* Federation Manager

* "Remote" Federation Manager (this acts as it was the Federation Manager of another OP)

* Artefact Manager

* Artefact Registry (Harbor as the artefact registry)

* A Dashboard. The dashboard is very convenient to just access the services with a single click, removing the need to manually enter the IPs into the browser:

* Edge Cloud Platfom: Installs lite2edge, a lightweight orchestrator as edge cloud platform.

!!! note

    Make sure you are in the `ansible` directory. And virtual env is activated: 

    ```bash

    cd ansible

    source venv/bin/activate

    ansible-playbook playbooks/scenarios/deploy_quick_single_oop.yml

    ```

Now, let's install all the necessary dependencies on your VM by running the following playbook:

    !!! info "What this installs"

        - **Prerequisites:** Python deps, Docker, Kubectl.

        - **Infrastructure:** Kind Cluster, Prometheus, Node Feature Discovery.

        - **Services:** Harbor, Artefact Manager, Federation Manager (x2), Homer Dashboard, Lite2Edge.

```bash

ansible-playbook playbooks/00-install-python-deps.yml

ansible-playbook playbooks/00-setup-docker.yml

ansible-playbook playbooks/00-setup-kubectl.yml

ansible-playbook playbooks/00-setup-python-libs.yml

```

### 3. Access the Platform

!!! note

    You might need a sudo password to install deps.

Once the playbook finishes, access the **Dashboard** to see all services:

Once dependencies are installed, then we can deploy the cluster.

* **URL:** `http://<VM_IP>:30088`

## Deploy The Cluster

![dashboard](./images/dashboard_screenshot.png)

Now let's deploy the kind cluster with 3 nodes: 1 control plane and 2 workers.

=== "Prod-ready / Custom Deployment"

!!! info

    This is the default configuration with 1 control plane and 2 worker nodes. You can customize the number of nodes in the `group_vars/all.yml` file by modifying the `worker_nodes` variable:

    For production environments or custom setups, you should execute the deployment steps individually. This allows for greater control over each component and is suitable for multi-node clusters or integrating with existing infrastructure.

    ```yaml

    # Cluster nodes configuration

    control_plane_nodes: 1

    worker_nodes: 2

    ```

```bash

ansible-playbook playbooks/01-deploy-kind-cluster.yml

```

    ## 1. Prepare The Inventory

Once the cluster is deployed, you can access it from anywhere by using the generated kubeconfig:

    Configure your `ansible/inventory/hosts.yml` as described in the [Getting Started](getting-started.md) guide.

```bash

venv) ➜  ansible git:(master) ✗ export KUBECONFIG=/path_to_project/OperatorPlatform/OP_Automation/automation/1-kind-cluster/operator-platform-external-kubeconfig.yaml

(venv) ➜  ansible git:(master) ✗ kubectl get nodes -o wide

NAME                              STATUS   ROLES           AGE   VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                         KERNEL-VERSION     CONTAINER-RUNTIME

operator-platform-control-plane   Ready    control-plane   90s   v1.33.1   172.18.0.2    <none>        Debian GNU/Linux 12 (bookworm)   6.8.0-49-generic   containerd://2.1.1

operator-platform-worker          Ready    <none>          79s   v1.33.1   172.18.0.4    <none>        Debian GNU/Linux 12 (bookworm)   6.8.0-49-generic   containerd://2.1.1

operator-platform-worker2         Ready    <none>          79s   v1.33.1   172.18.0.3    <none>        Debian GNU/Linux 12 (bookworm)   6.8.0-49-generic   containerd://2.1.1

```

    ## 2. Install Dependencies

## Deploy i2edge

To deploy i2edge we first need to install its dependencies in the cluster.

!!! info

    This playbook does not yet provides support for installing GPU drivers

    Ensure you are in the `ansible` directory with your virtual environment activated:

    ```bash

ansible-playbook playbooks/02-install-i2edge-dependencies.yml

    source venv/bin/activate

    ```

Then, install i2ede

!!! warning

    This is playbook does many workarounds to be able to deploy i2edge on the cluster such as rsync the code to the VM and build the image and then add it to the cluster. This is ugly and needs to be fixed, but works for now.

    Install node dependencies:

    ```bash

ansible-playbook playbooks/02-deploy-i2edge.yml

    ansible-playbook playbooks/tools/prerequisites/install-python-deps.yml

    ansible-playbook playbooks/tools/prerequisites/setup-docker.yml

    ansible-playbook playbooks/tools/prerequisites/setup-kubectl.yml

    ansible-playbook playbooks/tools/prerequisites/setup-python-libs.yml

    ```

!!! success

    If everything went fine,  i2edge should be accessible directly in http://VM_IP:30769/docs

    ## 3. Deploy Infrastructure

## Deploy lite2edge

To deploy lite2edge, which is the Kubernetes adapter for the Operator Platform:

    Deploy the Kubernetes cluster (Kind) or configure your existing cluster connection.

    ```bash

ansible-playbook playbooks/tools/lite2edge/deploy.yml

    # Deploys a Kind cluster (skip if using existing K8s)

    ansible-playbook playbooks/infrastructure/kind-cluster/deploy.yml

    ```

If you need to pull the image from a private registry (like GitLab), you can provide credentials:

    Once the cluster is ready, you can export the kubeconfig:

    ```bash

ansible-playbook playbooks/tools/lite2edge/deploy.yml \

  -e "lite2edge_registry_username=your_username" \

  -e "lite2edge_registry_password=your_password"

    export KUBECONFIG=$(pwd)/automation/1-kind-cluster/operator-platform-external-kubeconfig.yaml

    kubectl get nodes

    ```

## Deploy Artifact Registry (Harbor)

    ## 4. Deploy Components

We provide a playbook to deploy a Harbor instance to work as the artefact registry for the operator platform. To deploy Harbor run the following playbook:

    Install components individually as needed:

    **Harbor (Artefact Registry):**

    ```bash

ansible-playbook playbooks/02-deploy-harbor.yml

    ansible-playbook playbooks/tools/harbor/deploy.yml

    # Access: http://VM_IP:30002 (admin/Harbor12345)

    ```

!!! success

    If everything went fine, harbor should be accessible directly in http://VM_IP:30002.

!!! info

    Default Harbor credentials are: `admin` / `Harbor12345`. However those can be changed before the playbook run  in the `ansible/roles/harbor/defaults/main.yml` file.

## Deploy Artefact Manager

To deploy the artefact manager:

```

ansible-playbook playbooks/03-deploy-artefact-manager.yml

    **Artefact Manager:**

    ```bash

    ansible-playbook playbooks/tools/artefact-manager/deploy.yml

    # Access: http://VM_IP:30080

    ```

!!! success

    If everything went fine, artefact manager API should be accessible directly in http://VM_IP:30080.

## Deploy Federation Manager

To deploy the federation manager:

    **Federation Manager:**

    ```bash

ansible-playbook playbooks/04-deploy-federation-manager.yml

    ansible-playbook playbooks/tools/federation-manager/deploy.yml

    ansible-playbook playbooks/tools/federation-manager/deploy-remote.yml # Optional second instance

    # Access: http://VM_IP:30989 and http://VM_IP:30990

    ```

!!! success

    If everything went fine, federation manager API should be accessible directly in http://VM_IP:30989.

## Deploy a Second Federation Manager

Federation Manager needs another federation manager for almost all the operations, so it makes sense to deploy a second federation manager:

    **Lite2Edge (K8s Adapter):**

    ```bash

ansible-playbook playbooks/04-deploy-federation-manager.yml

    ansible-playbook playbooks/tools/lite2edge/deploy.yml

    ```

!!! success

    If everything went fine, federation manager API should be accessible directly in http://VM_IP:30990.

## Deploy a Dashboard

Since we are deploying many services, it comes very handy to have a dashboard to monitor them all in one place. So we provide a playbook to deploy the Operator Platform Dashboard. It will be deployed using Homer, a static homepage for your server. The dashboard will be accessible in http://VM_IP:30088.

    **Dashboard:**

    ```bash

ansible-playbook playbooks/05-deploy-homer.yml

    ansible-playbook playbooks/tools/homer/deploy.yml

    # Access: http://VM_IP:30088

    ```

# Ansible Directory Restructuring Proposal

## 1. Proposed Directory Structure

We propose reorganizing the `ansible/` directory to clearly separate **atomic component deployments** from **high-level recipes/scenarios**.

```text

ansible/

├── inventory/

│   ├── local/           # For local Kind development

│   │   └── hosts.yml

│   └── production/      # For real environments

│       └── hosts.yml

├── roles/               # Atomic, reusable logic (unchanged)

│   ├── harbor/

│   ├── i2edge/

│   ├── artefact-manager/

│   └── ...

├── playbooks/

│   ├── setup/           # 0. Prerequisites & Infrastructure

│   │   ├── install-python-deps.yml

│   │   ├── setup-docker.yml

│   │   └── deploy-kind-cluster.yml

│   ├── components/      # 1. Atomic Component Deployments

│   │   ├── harbor.yml

│   │   ├── jfrog.yml    # (Future)

│   │   ├── i2edge.yml

│   │   └── federation-manager.yml

│   └── recipes/         # 2. Scenarios & Workflows (Combinations)

│       ├── dev-local-full.yml      # Deploys Kind + Harbor + i2edge

│       ├── test-federation.yml     # Deploys 2x Federation Managers

│       └── prod-deployment.yml     # Production recipe

└── group_vars/

    └── all.yml

```

## 2. Addressing "Artifact Manager" Polymorphism

To handle the requirement that "Artifact Manager" could be Harbor, JFrog, or a custom tool, we can use a **Recipe** that selects the component based on a variable.

**File:** `playbooks/recipes/deploy-artifact-registry.yml`

```yaml

- name: Deploy Artifact Registry

  hosts: all

  tasks:

    - name: Deploy Harbor

      ansible.builtin.include_role:

        name: harbor

      when: registry_type == 'harbor'

    - name: Deploy JFrog

      ansible.builtin.include_role:

        name: jfrog

      when: registry_type == 'jfrog'

```

*Usage:* `ansible-playbook playbooks/recipes/deploy-artifact-registry.yml -e registry_type=harbor`

## 3. Addressing "Two Instances for Testing"

For the Federation Manager (or any component) where you might want one instance in production but two in testing (in the same cluster), we can design the role to accept a `namespace` and `release_name` parameter.

**Scenario: Testing Federation**

**File:** `playbooks/recipes/test-federation-scenario.yml`

```yaml

- name: Deploy Federation Manager Instance A

  hosts: kind_cluster

  roles:

    - role: federation-manager

      vars:

        instance_name: "fed-man-a"

        namespace: "federation-a"

- name: Deploy Federation Manager Instance B

  hosts: kind_cluster

  roles:

    - role: federation-manager

      vars:

        instance_name: "fed-man-b"

        namespace: "federation-b"

```

This allows you to reuse the same `federation-manager` role multiple times within a single test cluster.