diff --git a/README.md b/README.md index 3c9558e..f6dfac0 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,52 @@ following objectives in mind: - `Kubernetes` >= 1.8.0 - `kubectl` configured for the Kubernetes cluster - `Helm` version 3 (for the Evaluation Metrics Extraction subsystem) -- `nfs-commons` installed in the nodes of the cluster. If in Debian or - Ubuntu you can install it using `apt-get install nfs-common` +- `nfs-commons` installed in the nodes of the cluster -### Installation of the Kubernetes operator +**Note:** The following instructions were tested on Debian 12. Minor adjustments may be necessary for installation on other Linux distributions or operating systems. + +### Get Kubernetes +```sh +curl -LO "https://dl.k8s.io/release/v1.20.7/bin/linux/amd64/kubectl" +curl -LO "https://dl.k8s.io/release/v1.20.7/bin/linux/amd64/kubectl.sha256" +sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl +``` + +### Use Minikube [Optional] + +If you are not using an existing Kubernetes cluster, you can quickly set up a local environment for testing and development using Minikube: + +Download and install Minikube on your system: +```sh +curl -LO https://storage.googleapis.com/minikube/releases/v1.21.0/minikube-linux-amd64 +sudo install minikube-linux-amd64 /usr/local/bin/minikube +``` +Prepare Docker installation and setup: +```sh +sudo apt-get update +sudo apt-get install ca-certificates curl +sudo install -m 0755 -d /etc/apt/keyrings +sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc +sudo chmod a+r /etc/apt/keyrings/docker.asc +echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +sudo usermod -aG docker $USER +newgrp docker +``` + +Start Minikube with Docker driver: +```sh +minikube start --driver=docker +kubectl cluster-info +``` + +### Enable NFS Support +```sh +sudo apt-get install nfs-common +``` + +### Install the Kubernetes operator KOBE needs the Kubernetes operator that needs to be installed in the Kubernetes cluster. To quickly install the KOBE operator in a @@ -76,10 +118,10 @@ successfully been created. This will set the operator running in your Kubernetes cluster and needs to be done only once. -### Installation of Networking subsystem +### Install the Networking subsystem KOBE uses [Istio](https://istio.io/) to support network delays between the different -deployments. To install Istio first define the version (KOBE was tested with version 1.11.3) +deployments. To install Istio first define the version: ``` export ISTIO_VERSION=1.11.3 @@ -98,7 +140,17 @@ curl -L https://istio.io/downloadIstio | sh - ./istio-*/bin/istioctl manifest apply --set profile=default ``` -### Installation of the Evaluation Metrics Extraction subsystem +### Install Helm + +KOBE uses Helm to simplify the management of dependencies within Kubernetes environments. To install Helm on your system, run: + +``` +curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3. +chmod 700 get_helm.sh. +./get_helm.sh. +``` + +### Install the Evaluation Metrics Extraction subsystem To enable the evaluation metrics extraction subsystem, run ``` @@ -109,7 +161,7 @@ or alternatively the following helm repo add elastic https://helm.elastic.co helm repo add kiwigrid https://kiwigrid.github.io helm install elasticsearch elastic/elasticsearch --set persistence.enabled=false --set replicas=1 --version 7.6.2 -helm install elasticsearch elastic/elasticsearch --set persistence.enabled=false --set replicas=1 --version 7.6.2 +helm install kibana elastic/kibana --set service.type=NodePort --version 7.6.2 helm install fluentd kiwigrid/fluentd-elasticsearch -f operator/deploy/efk-config/fluentd-values.yaml --version 8.0.1 kubectl apply -f operator/deploy/efk-config/kobe-kibana-configuration.yaml ``` @@ -135,6 +187,19 @@ The setup can be customized by changing the configuration parameters of each helm chart. Please check the corresponding documentation of each chart for more info. +### Recommended Versions + +To ensure compatibility, we recommend using the following versions of the dependencies: +- `Kubernetes` = v1.20.7 +- `Minikube` = v1.21.0 (if used) +- `Istio` = v1.11.3 +- `Helm` = v3 +- `Elasticsearch` = 7.6.2 +- `Kibana` = 7.6.2 +- `Fluentd` = 8.0.1 + +These versions have been tested and verified to work together. + ## Example The typical workflow of defining a KOBE experiment is the following. @@ -221,9 +286,9 @@ kubectl delete namespace istio-system ``` To remove the evaluation metrics extraction subsystem manually, run ``` -helm delete --purge elasticsearch -helm delete --purge kibana -helm delete --purge fluentd +helm uninstall elasticsearch +helm uninstall kibana +helm uninstall fluentd helm repo remove elastic helm repo remove kiwigrid kubectl delete jobs.batch kobe-kibana-configuration @@ -233,5 +298,4 @@ and then in each Kubernetes node ``` rm -rf /var/log/fluentd-buffers/ rm /var/log/containers.log.pos -``` - +``` \ No newline at end of file