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

• Overview
• System Compatibility
• Prerequisites
  • WSL2 and Ubuntu Setup
  • Install Docker
  • Install kind
  • Install kubectl
  • Install Helm
• Deployment Steps
  • 1. Build the Custom KIND Image
  • 2. (Optional) Push the Image to Dockerhub
  • 3. Create a kind Kubernetes Cluster
• Troubleshooting
• Conclusion

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.

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
   

Ensure that WSL2 is enabled on Windows and Ubuntu is installed. Follow the official Microsoft WSL guide.

Docker is required to run Kubernetes and containers. Install Docker Desktop for WSL2 if using WSL2 Ubuntu, follow the official Docker WSL documentation.

For native Ubuntu, install Docker using the following commands, follow the official Docker installation guide.

Install kind (Kubernetes IN Docker) to create a local Kubernetes cluster:

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.

Install kubectl to interact with Kubernetes clusters:

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.

Install Helm to manage Kubernetes applications:

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.

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

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:

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.

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

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.

• 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:

  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.

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. 🚀