# Building your own image

This document provides detailed, step-by-step instructions for building your own kind image to deploy SREGym.

---

## Table of Contents

- [Overview](#overview)
- [System Compatibility](#system-compatibility)
- [Prerequisites](#prerequisites)
  - [WSL2 and Ubuntu Setup](#wsl2-and-ubuntu-setup)
  - [Install Docker](#install-docker)
  - [Install kind](#install-kind)
  - [Install kubectl](#install-kubectl)
  - [Install Helm](#install-helm)
- [Deployment Steps](#deployment-steps)
  - [1. Build the Custom KIND Image](#1-build-the-custom-kind-image)
  - [2. (Optional) Push the Image to Dockerhub](#2-optional-push-the-image-to-dockerhub)
  - [3. Create a kind Kubernetes Cluster](#4-create-a-kind-kubernetes-cluster)
- [Troubleshooting](#troubleshooting)
- [Conclusion](#conclusion)

---

## **Overview**
SREGym is deployed using **containerized components** and Kubernetes manifests. This guide provides a step-by-step deployment process, covering:

- Setting up **WSL2 (Windows Subsystem for Linux) or native Ubuntu 24.04**.
- Installing **Docker, kind, kubectl, Helm, Lua, Luarocks, and Luasocket**.
- Building a custom **kind image** and deploying SREGym into a **local Kubernetes cluster**.

---

## **System Compatibility**
This setup has been successfully verified on the following environments:
1. **WSL2 Ubuntu**
   ```
   Linux Warrens-Laptop 5.15.167.4-microsoft-standard-WSL2 #1 SMP Tue Nov 5 00:21:55 UTC 2024 x86_64 GNU/Linux
   ```
2. **Ubuntu 24.04 LTS (Cloud/Local Machine)**
   ```
   Linux ubuntu-s-4vcpu-8gb-sfo3-01 6.8.0-52-generic #53-Ubuntu SMP PREEMPT_DYNAMIC Sat Jan 11 00:06:25 UTC 2025 x86_64 GNU/Linux
   ```

---

## **Prerequisites**

### **WSL2 and Ubuntu Setup**
Ensure that WSL2 is enabled on Windows and Ubuntu is installed. Follow the official [Microsoft WSL guide](https://learn.microsoft.com/en-us/windows/wsl/install).


### **Install Docker**
Docker is required to run Kubernetes and containers. Install Docker Desktop for WSL2 if using WSL2 Ubuntu, follow the [official Docker WSL documentation](https://docs.docker.com/desktop/wsl/).

For native Ubuntu, install Docker using the following commands, follow the [official Docker installation guide](https://docs.docker.com/engine/install/ubuntu/).

### **Install kind**
Install kind (Kubernetes IN Docker) to create a local Kubernetes cluster:
```bash
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.27.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind
```

For more installation options and documentation, see [kind documentation](https://kind.sigs.k8s.io/docs/user/quick-start/).
### **Install kubectl**
Install **kubectl** to interact with Kubernetes clusters:
```bash
sudo apt-get update
# apt-transport-https may be a dummy package; if so, you can skip that package
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg

# If the folder `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
sudo chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg # allow unprivileged APT programs to read this keyring

# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo chmod 644 /etc/apt/sources.list.d/kubernetes.list   # helps tools such as command-not-found to work correctly

sudo apt-get update
sudo apt-get install -y kubectl
```

For further guidance, refer to [kubectl linux installation docs](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/).

### Install Helm

Install Helm to manage Kubernetes applications:

```bash
curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
sudo apt-get install apt-transport-https --yes
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm
```

For more information, see the [Helm installation guide](https://helm.sh/docs/intro/install/).

### Configure Host Kernel Parameters

Kind cluster nodes share the host kernel's inotify limits. The default
`fs.inotify.max_user_instances=128` is insufficient for multi-node clusters and
will cause kube-system pods (kube-proxy, etc.) to crash with "too many open
files". Run this before creating your cluster:

    sudo sysctl -w fs.inotify.max_user_instances=1024
    sudo sysctl -w fs.inotify.max_user_watches=1048576

To make persistent across reboots:

    echo "fs.inotify.max_user_instances=1024" | sudo tee /etc/sysctl.d/99-kind.conf
    echo "fs.inotify.max_user_watches=1048576" | sudo tee -a /etc/sysctl.d/99-kind.conf
    sudo sysctl --system

---

## Deployment Steps

### 1. Build the Custom KIND Image

The Dockerfile in this directory is designed specifically for Ubuntu running under WSL2 (amd64). **Please refer to this Dockerfile** to build an image that is compatible with your own machine

Build the custom image using:

```bash
docker build -t your_dockerhub_username/aiopslab-kind:latest -f kind/Dockerfile .
```
> **Note:** Replace `your_dockerhub_username` with your Docker Hub account if pushing the image.

### 2. (Optional) Push the Image to Dockerhub

If you wish to publish your custom image and have it referenced by the kind configuration file, push it to Docker Hub:

```bash
docker push your_dockerhub_username/aiopslab-kind:latest
```

Remember to update the `kind-config.yaml` file with your image name if you are using your own published image.


After finishing cluster creation, proceed to the next "Update config.yml" step.

---

## **Troubleshooting**

- **Docker Issues:**
  Ensure Docker is running within your WSL2 environment. Verify with `docker ps` to list running containers.

- **Cluster Creation Failures:**
  Check that Docker is correctly installed and that your system has enough resources (CPU, memory). Examine the output of `kind export logs <cluster-name>` for details.

- **Deployment Problems:**
  Use `kubectl logs <pod-name>` to view pod logs and diagnose application issues. Make sure that your `kind-config.yaml` file references the correct image.

- **kube-proxy CrashLoopBackOff / "too many open files":**
  All kind nodes share the host kernel's `fs.inotify.max_user_instances` limit
  (default: 128). When this is exhausted, new pods that need inotify instances
  (like kube-proxy) crash immediately. Fix with:
  `sudo sysctl -w fs.inotify.max_user_instances=1024`

- **Resource Allocation:**
  WSL2 may require additional resources. Adjust the WSL2 settings in your `.wslconfig` file on Windows if you encounter performance issues.

- **Deployment Timeout Issues (Slow Network):**
  If you have a slow local network connection, first-time deployments may timeout while pulling container images. Increase the timeout in your `.env` file:

  ```bash
  WAIT_FOR_POD_READY_TIMEOUT=1800  # 30 minutes (recommended for slow networks)
  ```

  Subsequent deployments are faster since images are cached. Remote clusters typically don't need this adjustment.

---

## **Conclusion**
This guide covers deploying **SREGym** on **both WSL2 and Ubuntu 24.04**, ensuring compatibility across different environments. By following these steps, you can successfully set up **Docker, kind, and Kubernetes** and deploy the SREGym application.

For advanced configurations, refer to the [SREGym documentation](https://github.com/SREGym/SREGym). 🚀
