CT-147: updated project README.md file. (2914e6ed) · Commits · Gianluca Marotta / csp-lmc-old

README.md

+184 −20

Original line number	Diff line number	Diff line
		@@ -10,8 +10,8 @@ CPS.LMC project
		* [Repository](#repository)
		* [CSP.LMC Common Package](#csp-lmc-common)
		* [Create the CSP.LMC Common Software python package](#python-package)
		* [CSP_Mid LMC](#mid-csp-mid-lmc)
		* [Running tests](#running-tests)
		* [CSP_Mid LMC](#CSP_Mid.LMC)
		* [CSP_Mid LMC Deployment in Kubernetes](#Mid-CSP.LMC-Kubernetes-Deployment-via-Helm-Charts)
		* [CSP_Low LMC](#csp-low-lmc)
		* [Run in containers](#how-to-run-in-docker-containers)
		* [Known bugs](#known-bugs)
		@@ -39,8 +39,10 @@ the same organization:

		* project source: contains the specific project TANGO Device Class files
		* pogo: contains the POGO files of the TANGO Device Classes of the project
		* docker: containes the `docker`, `docker-compose` and `dsconfig` configuration files as well as the Makefile to generate the docker image and run the tests.
		* tests: contains the test
		* charts: stored the HEML charts to deploy the Mid CSP.LMC system under kubernets environment.
		* docker: containes the `docker`, `docker-compose` and `dsconfig` configuration files as well as
		the Makefile to generate the docker image and run the tests.

		To get a local copy of the repository:

		@@ -52,18 +54,192 @@ git clone https://gitlab.com/ska-telescope/csp-lmc.git
		* A TANGO development environment properly configured, as described in [SKA developer portal](https://developer.skatelescope.org/en/latest/tools/tango-devenv-setup.html)

		* [SKA Base classes](https://gitlab.com/ska-telescope/lmc-base-classes)
		*
		## CSP_Mid.LMC
		* access to a K8s/minikube cluster.

		# CSP_Mid.LMC

		The TANGO devices of the CSP_Mid.LMC prototype run in a containerised environment.
		Currently only a limitated number of CSP_Mid.LMC and CBF_Mid.LMC devices are run in Docker containers:

		* the MidCspMaster and MID CbfMaster
		* the MidCspCapabilityMonitor devices
		* two instances of the CSP_Mid and CBF_Mid subarrays
		* three instances of the CSP_Mid and CBF_Mid subarrays
		* four instances of the Very Coarse Channelizer (VCC) devices
		* four instance of the Frequency Slice Processor (FPS) devices
		* two instances of the TM TelState Simulator devices
		* one instance of the TANGO database

		## Containerised Mid CSP.LMC in Kubernetes

		The Mid CSP.LMC containerised TANGO servers are managed via Kubernetes.
		The system is setup so that each k8s Pod has only one Docker container that in turn
		runs only one Tango Device Server application.<br/>
		Mid CSP.LMC TANGO Servers rely on two different Docker images: `mid-csplmc` and `mid-cbf-mcs`. <br/>
		The first one runs the CSP.LMC TANGO devices and the sencond those of the Mid CBF.LMC prototype.

		### Mid CSP.LMC Kubernetes Deployment via Helm Charts

		The deployment of the system is handled by the Helm tool, via the Helm Charts, a set of YAML files describing
		how the Kubernetes resources are related.<br/>
		The Mid CSP.LMC Helm Charts are stored in the `charts` directory, organized in two sub-folders: <br/>

		* csp-proto with the Helm chart to deploy only the CSP.LMC devices (MidCspCapabilityMonitor, MidcSpMaster nad MidCspSubarray)
		* mid-csp with the Helm chart to deploy the whole Mid CSP.LMC system, including the TANGO Database and the Mid CSF.LMC devices.
		In particular, the `mid-csp` chart depends on the CSP.LMC, CBF.LMC and Tango DB charts and these dependecies are
		dynamically linked specifying the `dependencies` field in the Chart.yaml.<br/>

		The `Makefile` in the csp-lmc-mid root directory provides the targets to deploy the system, stop the running services and run
		the tests locally, on a k8s/minikube machine.

		To deploy the whole Mid CSP.LMC system run:

		``` bash
		make deploy
		```
		that installs the mid-csp helm chart specifying `test` as relase name and assigns it to the `csp-proto` namespace.

		Running the command:
		```bash
		helm list -n csp-proto
		```
		an output like the one below is shown:
		```
		NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
		test csp-proto 1 2020-09-21 10:07:19.308839059 +0200 CEST deployed mid-csp-0.1.0 0.6.8
		```

		To list all the pods and service in the csp-proto namespace, issue the command:

		```bash
		kubectl get all -n csp-proto
		```

		that provides the following output lines:

		```
		NAME READY STATUS RESTARTS AGE
		pod/databaseds-tango-base-test-0 1/1 Running 0 2m48s
		pod/mid-cbf-cbf-proto-cbfmaster-test-0 1/1 Running 0 2m50s
		pod/mid-cbf-cbf-proto-cbfsubarray01-test-0 1/1 Running 1 2m50s
		pod/mid-cbf-cbf-proto-cbfsubarray02-test-0 1/1 Running 1 2m48s
		pod/mid-cbf-cbf-proto-cbfsubarray03-test-0 1/1 Running 1 2m48s
		pod/mid-cbf-cbf-proto-fsp01-test-0 1/1 Running 0 2m49s
		pod/mid-cbf-cbf-proto-fsp02-test-0 1/1 Running 0 2m49s
		pod/mid-cbf-cbf-proto-fsp03-test-0 1/1 Running 0 2m50s
		pod/mid-cbf-cbf-proto-fsp04-test-0 1/1 Running 0 2m50s
		pod/mid-cbf-cbf-proto-tmcspsubarrayleafnodetest-test-0 1/1 Running 0 2m49s
		pod/mid-cbf-cbf-proto-tmcspsubarrayleafnodetest2-test-0 1/1 Running 0 2m48s
		pod/mid-cbf-cbf-proto-vcc001-test-0 1/1 Running 3 2m47s
		pod/mid-cbf-cbf-proto-vcc002-test-0 1/1 Running 3 2m50s
		pod/mid-cbf-cbf-proto-vcc003-test-0 1/1 Running 3 2m50s
		pod/mid-cbf-cbf-proto-vcc004-test-0 1/1 Running 3 2m49s
		pod/mid-cbf-configurator-cbf-proto-test-m6j2p 0/1 Error 0 2m50s
		pod/mid-cbf-configurator-cbf-proto-test-qm8xg 0/1 Completed 0 2m15s
		pod/midcsplmc-configurator-csp-proto-test-d7hmp 0/1 Completed 0 2m15s
		pod/midcsplmc-configurator-csp-proto-test-qnks4 0/1 Error 0 2m50s
		pod/midcsplmc-csp-proto-midcapabilitymonitor-test-0 1/1 Running 3 2m48s
		pod/midcsplmc-csp-proto-midcspmaster-test-0 1/1 Running 0 2m50s
		pod/midcsplmc-csp-proto-midcspsubarray01-test-0 1/1 Running 1 2m50s
		pod/midcsplmc-csp-proto-midcspsubarray02-test-0 1/1 Running 1 2m50s
		pod/midcsplmc-csp-proto-midcspsubarray03-test-0 1/1 Running 1 2m50s
		pod/tango-base-tangodb-0


		NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
		service/databaseds-tango-base-test NodePort 10.103.37.75 <none> 10000:31664/TCP 2m50s
		service/mid-cbf-cbf-proto-cbfmaster-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-cbfsubarray01-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-cbfsubarray02-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-cbfsubarray03-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-fsp01-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-fsp02-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-fsp03-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-fsp04-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-tmcspsubarrayleafnodetest-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-tmcspsubarrayleafnodetest2-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-vcc001-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-vcc002-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-vcc003-test ClusterIP None <none> 1234/TCP 2m50s
		service/mid-cbf-cbf-proto-vcc004-test ClusterIP None <none> 1234/TCP 2m50s
		service/midcsplmc-csp-proto-midcapabilitymonitor-test ClusterIP None <none> 1234/TCP 2m50s
		service/midcsplmc-csp-proto-midcspmaster-test ClusterIP None <none> 1234/TCP 2m50s
		service/midcsplmc-csp-proto-midcspsubarray01-test ClusterIP None <none> 1234/TCP 2m50s
		service/midcsplmc-csp-proto-midcspsubarray02-test ClusterIP None <none> 1234/TCP 2m50s
		service/midcsplmc-csp-proto-midcspsubarray03-test ClusterIP None <none> 1234/TCP 2m50s
		service/tango-base-tangodb NodePort 10.102.174.225 <none> 3306:30633/TCP 2m50s

		NAME READY AGE
		statefulset.apps/databaseds-tango-base-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-cbfmaster-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-cbfsubarray01-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-cbfsubarray02-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-cbfsubarray03-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-fsp01-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-fsp02-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-fsp03-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-fsp04-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-tmcspsubarrayleafnodetest-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-tmcspsubarrayleafnodetest2-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-vcc001-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-vcc002-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-vcc003-test 1/1 2m50s
		statefulset.apps/mid-cbf-cbf-proto-vcc004-test 1/1 2m50s
		statefulset.apps/midcsplmc-csp-proto-midcapabilitymonitor-test 1/1 2m50s
		statefulset.apps/midcsplmc-csp-proto-midcspmaster-test 1/1 2m50s
		statefulset.apps/midcsplmc-csp-proto-midcspsubarray01-test 1/1 2m50s
		statefulset.apps/midcsplmc-csp-proto-midcspsubarray02-test 1/1 2m50s
		statefulset.apps/midcsplmc-csp-proto-midcspsubarray03-test 1/1 2m50s
		statefulset.apps/tango-base-tangodb 1/1 2m50s

		NAME COMPLETIONS DURATION AGE
		job.batch/mid-cbf-configurator-cbf-proto-test 1/1 61s 2m50s
		job.batch/midcsplmc-configurator-csp-proto-test 1/1 59s 2m50s
		```
		The helm release can be deleted and the application stopped using the command:
		```bash
		make delete
		```
		that unistalls the `mid-csp` chart and delete the `test` release in the `csp-proto` namespace.

		Other Makefile targets, such as `describe` and `logs`, provide some useful information when the system has been properly deployed.

		## Run integration tests on a local k8s/minikube cluster

		The project includes a set of tests for the `MidCspMaster` and `MidCspSubarray` TANGO Devices
		that can be found in the project `tests` folder.<br/>
		To run the tests on the local k8s cluster, issue the command

		<code><pre>make k8s_test</pre></code>
		from the root project directory.<br/>

		This command first deploys the system and then executes the integration tests.

		After tests end, run the command:

		<code><pre>make delete</pre></code>

		to uninstall the HELM charts of the `test` release.

		## Gitlab continuos integration tests

		Continuos integration tests in Gitlab rely on the `.gitlab-ci.yml` configuration file that provides al the scripts to build, test and deploy the application. <br/>
		This file has been updated to run test in K8s environment and any reference to the use of `docker-compose` as containers manager, has been removed <br/>.
		A new job has been added in the pipline `publish` stage to release the the `csp-proto` helm chart in the SKA Helm charts repositoryhostes under `nexus`.

		## Docker-compose support

		Support to `docker-compose` has not been completely removed even if all the main operations are
		performed in kubernetes environment.<br/>
		Use of `docker-compose` has been maintened only to simplify the development on machines that
		are not capable to run minikube in a virtual machine.<br/>
		The docker folder of the project contains all the files required to run the system via the
		docker-compose tool.
		From the docker folder of the project, one can still:
		• build the image running <code><pre> make build </pre></code>
		• start the system dockers with docker-compose executing
		make up
		• run the test on the local machine calling:
		make test

		The Docker containers running the CBF_Mid devices are instantiated pulling the `mid-cbf-mcs:test` project image from the [Nexus repository](https://nexus.engageska-portugal.pt). <br/>
		The CSP_Mid.LMC project provides a [Makefile](Makefile) to start the system containers and the tests.<br/>
		@@ -79,9 +255,6 @@ instances, that is, to run the whole `CSP_Mid.LMC` prototype.>br\>
		In this way, it's possible to execute some preliminary integration tests, as for example the assignment/release of receptors to a `CSP_Mid Subarray` and its configuration to execute a scan in Imaging mode.<br/>
		The `CSP_Mid.LMC` and `Mid-CBF.LMC TANGO` Devices are registered with the same TANGO DB, and its
		configuration is performed via the `dsconfig` TANGO Device provided by the [dsconfig project](https://gitlab.com/MaxIV-KitsControls/lib-maxiv-dsconfig). <br />
		This device use a JSON file to configure the TANGO DB. <br/>
		The `CSP_Mid.LMC` and `Mid-CBF.LMC` projects provide its own JSON file:
		[midcsplmc\_dsconfig.json](csp-lmc/csp-lmc-mid/csp-lmc-mid/docker/config/midcsplmc_dsconfig.json) and [midcbf\_dsconfig.json](sp-lmc/csp-lmc-mid/csp-lmc-mid/docker/config/midcbf_dsconfig.json)

		To run the `CSP_Mid.LMC` prototype inside Docker containers,issue the command:

		@@ -99,11 +272,11 @@ mid-csp-lmc-cbf_dsconfig: the dsconfig container to configure CBF.LMC devi
		mid-csp-lmc-cbf_dsconfig: the dsconfig container to configure CSP.LMC devices in the TANGO DB
		mid-csp-lmc-midcspmaster: the CspMaster TANGO device
		mid-csp-lmc-midcapabilitymonitor: the monitor devices of the CSP_Mid.LMC Capabilities
		mid-csp-lmc-midcspsubarray[01-02]: two instances of the CspSubarray TANGO device
		mid-csp-lmc-midcspsubarray[01-023: two instances of the CspSubarray TANGO device
		mid-csp-lmc-rsyslog-csplmc: the rsyslog container for the CSP.LMC devices
		mid-csp-lmc-rsyslog-cbf : the rsyslog container for the CBF.LMC devices
		mid-csp-lmc-cbfmaster: the CbfMaster TANGO device
		mid-csp-lmc-cbfsubarray[01-02]: two instances of the CbfSubarray TANGO device
		mid-csp-lmc-cbfsubarray[01-03]: two instances of the CbfSubarray TANGO device
		mid-csp-lmc-vcc[001-004]: four instances of the Mid-CBF VCC TANGO device
		mid-csp-lmc-fsp[01-04]: four instances of the Mid-CBF FSP TANGO device
		mid-csp-lmc-tmcspsubarrayleafnodetest/2: two instances of the TelState TANGO Device
		@@ -121,15 +294,6 @@ This means that the TANGO DB running in the container is available on port 10000
		Running `jive` on the local host, the `CSP.LMC` and `Mid-CBF.LMC` TANGO Devices registered with the TANGO DB (running in a docker container)
		can be visualized and explored.

		## Running tests

		The project includes a set of tests for the `MidCspMaster` and `MidCspSubarray` TANGO Devices that can be found in the project `tests` folder.<br/>
		To run the test on the local host issue the command

		<code><pre>make test</pre></code>
		from the `docker` project directory.<br/>
		The test are run in docker containers providing the proper environment setup and isolation.

		## Known bugs

csp-lmc-mid/.make/k8s.mk

+7 −4

Original line number	Diff line number	Diff line
		@@ -53,11 +53,14 @@ show: mkcerts ## show the helm chart
		--set ingress.hostname=$(INGRESS_HOST)

		chart_lint: ## lint check the helm chart
		@helm lint charts/$(HELM_CHART)/ \
		@for i in `ls charts/`; \
		do echo " char dir$${i}"; \
		helm lint charts/$${i}/ \
		--namespace $(KUBE_NAMESPACE) \
		--set ingress.hostname=$(INGRESS_HOST) \
		--set xauthority="$(XAUTHORITYx)" \
		--set display="$(DISPLAY)" \
		--set display="$(DISPLAY)";\
		done

		helm_delete: ## delete the helm chart release (with Tiller)
		@helm delete $(HELM_RELEASE) --purge \
		@@ -83,7 +86,7 @@ delete_traefik: ## delete the helm chart for traefik. @param: EXTERNAL_IP
		rm -rf $$TMP

		describe: ## describe Pods executed from Helm chart
		@for i in `kubectl -n $(KUBE_NAMESPACE) get pods -l app.kubernetes.io/instance=$(HELM_RELEASE) -o=name`; \
		@for i in `kubectl -n $(KUBE_NAMESPACE) get pods -l release=$(HELM_RELEASE) -o=name`; \
		do echo "---------------------------------------------------"; \
		echo "Describe for $${i}"; \
		echo kubectl -n $(KUBE_NAMESPACE) describe $${i}; \
		@@ -94,7 +97,7 @@ describe: ## describe Pods executed from Helm chart
		done

		logs: ## show Helm chart POD logs
		@for i in `kubectl -n $(KUBE_NAMESPACE) get pods -l app.kubernetes.io/instance=$(HELM_RELEASE) -o=name`; \
		@for i in `kubectl -n $(KUBE_NAMESPACE) get pods -l release=$(HELM_RELEASE) -o=name`; \
		do \
		echo "---------------------------------------------------"; \
		echo "Logs for $${i}"; \

csp-lmc-mid/charts/mid-csp/Chart.yaml

+2 −2

Original line number	Diff line number	Diff line
		apiVersion: v1
		appVersion: 0.6.8
		apiVersion: v2
		appVersion: 0.6.9
		description: A Helm chart for deploying the whole Mid_CSP prototype on Kubernetes
		name: mid-csp
		version: 0.1.0

csp-lmc-mid/charts/mid-csp/templates/_helpers.tpl

0 → 100644

+62 −0

Original line number	Diff line number	Diff line
		{{/*
		Expand the name of the chart.
		*/}}
		{{- define "mid-csp.name" -}}
		{{- default .Chart.Name .Values.nameOverride \| trunc 63 \| trimSuffix "-" }}
		{{- end }}

		{{/*
		Create a default fully qualified app name.
		We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
		If release name contains chart name it will be used as a full name.
		*/}}
		{{- define "mid-csp.fullname" -}}
		{{- if .Values.fullnameOverride }}
		{{- .Values.fullnameOverride \| trunc 63 \| trimSuffix "-" }}
		{{- else }}
		{{- $name := default .Chart.Name .Values.nameOverride }}
		{{- if contains $name .Release.Name }}
		{{- .Release.Name \| trunc 63 \| trimSuffix "-" }}
		{{- else }}
		{{- printf "%s-%s" .Release.Name $name \| trunc 63 \| trimSuffix "-" }}
		{{- end }}
		{{- end }}
		{{- end }}

		{{/*
		Create chart name and version as used by the chart label.
		*/}}
		{{- define "mid-csp.chart" -}}
		{{- printf "%s-%s" .Chart.Name .Chart.Version \| replace "+" "_" \| trunc 63 \| trimSuffix "-" }}
		{{- end }}

		{{/*
		Common labels
		*/}}
		{{- define "mid-csp.labels" -}}
		helm.sh/chart: {{ include "mid-csp.chart" . }}
		{{ include "mid-csp.selectorLabels" . }}
		{{- if .Chart.AppVersion }}
		app.kubernetes.io/version: {{ .Chart.AppVersion \| quote }}
		{{- end }}
		app.kubernetes.io/managed-by: {{ .Release.Service }}
		{{- end }}

		{{/*
		Selector labels
		*/}}
		{{- define "mid-csp.selectorLabels" -}}
		app.kubernetes.io/name: {{ include "mid-csp.name" . }}
		app.kubernetes.io/instance: {{ .Release.Name }}
		{{- end }}

		{{/*
		Create the name of the service account to use
		*/}}
		{{- define "mid-csp.serviceAccountName" -}}
		{{- if .Values.serviceAccount.create }}
		{{- default (include "mid-csp.fullname" .) .Values.serviceAccount.name }}
		{{- else }}
		{{- default "default" .Values.serviceAccount.name }}
		{{- end }}
		{{- end }}

csp-lmc-mid/charts/mid-csp/values.yaml

0 → 100644

+11 −0

Original line number	Diff line number	Diff line
		# Default values for mid-csp.
		csp-proto:
		csplmc:
		enabled: true
		cbf-proto:
		midcbfmcs:
		enabled: true
		tango-base:
		tangodb:
		enabled: true
		use_pv: false