diff --git a/.gitignore b/.gitignore index b3daeb9ed5b9d79815148b964666f69143c84222..9b97af98b4089f37d538f868f2ae0dcfd8e0d744 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ site doc/testing/postman/Responses doc/testing/postman/node_modules doc/testing/postman/package-lock.json -.DS_Store \ No newline at end of file +.DS_Store +.python-version diff --git a/doc/deployment_guide.md b/doc/deployment_guide.md index de42157d763879443ab1b24e5ec5ce326b881caa..78dafba0659044212d4b4624bfaa9b0730b5baa2 100644 --- a/doc/deployment_guide.md +++ b/doc/deployment_guide.md @@ -11,11 +11,16 @@ In this section, we describe how to configure a machine (physical or virtual) to Virtualization platforms tested are: -- [Physical Server](#111-physical-server) -- [Oracle Virtual Box](#112-oracle-virtual-box) -- [VMWare Fusion](#113-vmware-fusion) -- [OpenStack](#114-openstack) -- [Vagrant Box](#115-vagrant-box) +- [1.1. Configure your Machine](#11-configure-your-machine) + - [1.1.1. Physical Server](#111-physical-server) + - [1.1.2. Oracle Virtual Box](#112-oracle-virtual-box) + - [1.1.3. VMWare Fusion](#113-vmware-fusion) + - [1.1.4. OpenStack](#114-openstack) + - [1.1.5. Vagrant Box](#115-vagrant-box) +- [1.2. Install MicroK8s](#12-install-microk8s) +- [**1.3. Deploy TeraFlowSDN**](#13-deploy-teraflowsdn) +- [**1.4. WebUI and Grafana Dashboards**](#14-webui-and-grafana-dashboards) +- [**1.5. Show Deployment and Logs**](#15-show-deployment-and-logs) ### 1.1.1. Physical Server This section describes how to configure a physical server for running ETSI TeraFlowSDN(TFS) controller. @@ -782,19 +787,38 @@ First, we need to enable the community plugins (maintained by third parties): microk8s.enable community ``` -The Addons to be enabled are: +__Note__: In some cases, enabling `community` add-on might raise an error stating +`fatal: detected dubious ownership in repository at '/snap/microk8s/current/addons/community/.git'` +and proposing to run command: +`git config --global --add safe.directory /snap/microk8s/current/addons/community/.git`. +If so, execute it and retry enabling `community` addon. + +The __mandatory__ addons to be enabled are: - `dns`: enables resolving the pods and services by name - `helm3`: required to install NATS - `hostpath-storage`: enables providing storage for the pods (required by `registry`) - `ingress`: deploys an ingress controller to expose the microservices outside Kubernetes - `registry`: deploys a private registry for the TFS controller images + +```bash +microk8s.enable dns +microk8s.enable helm3 +microk8s.enable hostpath-storage +microk8s.enable ingress +microk8s.enable registry +``` + +For __scalable production__ deployments consider enabling addons: + - `linkerd`: deploys the [linkerd service mesh](https://linkerd.io) used for load balancing among replicas - `prometheus`: set of tools that enable TFS observability through per-component instrumentation - `metrics-server`: deploys the [Kubernetes metrics server](https://github.com/kubernetes-sigs/metrics-server) for API access to service metrics ```bash -microk8s.enable dns helm3 hostpath-storage ingress registry prometheus metrics-server linkerd +microk8s.enable prometheus +microk8s.enable metrics-server +microk8s.enable linkerd ``` __Important__: Enabling some of the addons might take few minutes. Do not proceed with next steps until the addons are ready. Otherwise, the deployment might fail. @@ -812,22 +836,22 @@ Then, create aliases to make the commands easier to access: ```bash sudo snap alias microk8s.helm3 helm3 -sudo snap alias microk8s.linkerd linkerd ``` -To validate that `linkerd` is working correctly, run: +If `linkerd` is enabled, run the following commands to add the alias to the command, and validate it is working correctly: ```bash +sudo snap alias microk8s.linkerd linkerd linkerd check ``` -To validate that the `metrics-server` is working correctly, run: +If `metrics-server` is enabled, run the following command to validate it is working correctly: ```bash kubectl top pods --all-namespaces ``` and you should see a screen similar to the `top` command in Linux, showing the columns *namespace*, *pod name*, *CPU (cores)*, and *MEMORY (bytes)*. -In case pods are not starting, check information from pods logs. For example, linkerd is sensitive for proper /etc/resolv.conf syntax. +In case pods are not starting, check information from pods logs. For example, `linkerd` is sensitive for proper /etc/resolv.conf syntax. ```bash kubectl logs <podname> --namespace <namespace> ```