Add docs via mkdocs

image: python:3.9-alpine

pages:

  stage: deploy

  script:

    - pip install mkdocs-material mkdocs-build-plantuml-plugin

    - mkdocs build

  artifacts:

    paths:

      - public

  rules:

    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# Architecture

## Directory Structure

The project follows a standard Ansible directory structure:

```

ansible/

├── ansible.cfg                 # Ansible configuration

├── requirements.yml            # Required Ansible collections

├── inventory/

│   └── hosts.yml              # Inventory for localhost

├── group_vars/

│   └── all.yml                # Global variables

├── playbooks/

│   ├── 01-deploy-kind-cluster.yml        # Create Kind cluster

│   ├── 02-install-dependencies.yml       # Install Prometheus, NFD

│   ├── 03-deploy-i2edge.yml              # Deploy i2edge

│   └── 99-undeploy-kind-cluster.yml      # Delete cluster

└── roles/

    ├── helm/                  # Helm installation

    ├── i2edge/                # i2edge deployment

    ├── kind-cluster/          # Kind cluster management

    ├── node-feature-discovery/# NFD installation

    └── prometheus/            # Prometheus stack

```

## Configuration

### Global Variables (`group_vars/all.yml`)

Key variables you can customize:

```yaml

# Cluster settings

kind_cluster_name: operator-platform

kind_version: v0.29.0

worker_nodes: 2

# Network settings

kubeconfig_server_url: "https://localhost:6443"

# Port mappings

port_mappings:

  - name: kubernetes-api

    container_port: 6443

    host_port: 6443

  - name: prometheus

    container_port: 30090

    host_port: 30090

  - name: i2edge-service

    container_port: 30769

    host_port: 30769

```

### Override Variables

You can override variables at runtime using the `-e` flag:

```bash

# Change cluster name

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

  -e "kind_cluster_name=test-cluster"

# Change number of workers

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

  -e "worker_nodes=3"

```

# Getting Started

## Deployment Architecture

This automation framework follows a standard Ansible architecture:

1.  **Control Node (Ansible Runner)**: This is your local machine (laptop or workstation). It runs the Ansible playbooks.

2.  **Managed Node (Target System)**: This is the remote system (e.g., a Virtual Machine or bare metal server) where the Operator Platform will be deployed.

You will run commands on your **Control Node**, which connects to the **Managed Node** via SSH to perform the installation.

```text

+------------------------+                    +------------------------+

|      Control Node      |                    |      Managed Node      |

|     (Your Laptop)      |                    |      (Target VM)       |

|                        |        SSH         |                        |

|   +----------------+   |   ------------->   |   +----------------+   |

|   |    Ansible     |   |                    |   |     Docker     |   |

|   |   Playbooks    |   |                    |   |     Engine     |   |

|   +----------------+   |                    |   +--------+-------+   |

|                        |                    |            |           |

|   - inventory/         |                    |   +--------v-------+   |

|   - playbooks/         |                    |   |  Kind Cluster  |   |

|   - roles/             |                    |   | (Op. Platform) |   |

|                        |                    |   +----------------+   |

+------------------------+                    +------------------------+

```

## 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

- **Docker**: Installed and running (can be installed via `playbooks/00-setup-docker.yml`)

## Installation (Control Node)

### 1. Install Ansible and Dependencies

It is recommended to use a Python virtual environment to isolate dependencies.

Install Python virtual environment support (Ubuntu/Debian example):

```bash

sudo apt update

sudo apt install python3-virtualenv python3-pip

```

Create and activate the virtual environment:

```bash

python3 -m venv venv

source venv/bin/activate

```

Install Ansible and required Python libraries:

```bash

pip install ansible kubernetes docker

```

### 2. Install Required Collections

Install the necessary Ansible collections:

```bash

cd ansible

ansible-galaxy collection install -r requirements.yml

```

This installs:

- `kubernetes.core` - Kubernetes resource management

- `community.docker` - Docker operations

- `community.general` - General utilities

# Ansible Automation for Operator Platform

This documentation covers the Ansible automation framework for deploying and managing the Operator Platform with i2edge on Kind (Kubernetes in Docker).

## Overview

This framework automates:

- **Cluster Provisioning**: Setting up a Kind cluster with custom configurations.

- **Dependency Management**: Installing tools like Helm, Prometheus, and Node Feature Discovery.

- **Application Deployment**: Building and deploying the i2edge application.

- **Lifecycle Management**: Clean undeployment and cleanup of resources.

## Getting Started

To start using this automation framework, please follow the [Getting Started](getting-started.md) guide. It covers:

1.  **Prerequisites**: System requirements for both the Control Node and Managed Node.

2.  **Installation**: Setting up Ansible, Python dependencies, and required collections.

3.  **Configuration**: Preparing your environment for deployment.

# Playbooks

## 01-deploy-kind-cluster.yml

**Purpose**: Create and configure Kind cluster

**Variables**:

- `kind_cluster_name` - Cluster name (default: `operator-platform`)

- `kind_version` - Kind binary version (default: `v0.29.0`)

- `worker_nodes` - Number of worker nodes (default: `2`)

- `recreate_cluster` - Force recreate if exists (default: `no`)

**Output**:

- Kubeconfig: `../automation/1-kind-cluster/operator-platform-external-kubeconfig.yaml`

- Config: `../automation/1-kind-cluster/kind-config.yaml`

- Setup script: `../automation/1-kind-cluster/setup-env.sh`

## 02-install-dependencies.yml

**Purpose**: Install cluster dependencies (Prometheus, NFD)

**Tags**:

- `prometheus`: Install Prometheus stack

- `nfd`: Install Node Feature Discovery

## 03-deploy-i2edge.yml

**Purpose**: Deploy the i2edge application

**Actions**:

- Builds i2edge Docker image

- Loads image into Kind

- Creates storage directories

- Deploys via Kustomize

- Waits for pods to be ready

## 99-undeploy-kind-cluster.yml

**Purpose**: Delete Kind cluster and cleanup

**Variables**:

- `kind_cluster_name` - Cluster to delete (default: `operator-platform`)

**Safety**:

- Prompts for confirmation before deletion

- Use `-e "confirm_deletion=yes"` to skip prompt (dangerous!)

## Advanced Usage

### Verbose Output

```bash

# Show detailed task execution

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

# Show even more detail (connection info)

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

```

### Check Mode (Dry Run)

```bash

# See what would be changed without making changes

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

```