Developer Setup

New developers should first follow the instructions on the SKA developer portal:

• Dev Portal

• FAQs

Git Repository

The MCS Git Repository is available here: ska-mid-cbf-mcs

The README on the repository will guide users through cloning and initializing the repository.

Running the Mid CBF MCS

The ska-mid-cbf-mcs Tango device servers are deployed via Kubernetes/k8s. A single k8s node can be created with minikube using the ska-cicd-deploy-minikube project.

1. Start minikube.

To build a minikube node, from root of ska-cicd-deploy-minikube repository;

make minikube-install DRIVER=docker UPDATE_LOCAL_DNS=false

# The following points the local Docker CLI to the minikube's Docker daemon.
# This step is necessary for deploying locally-built images.
eval $(minikube docker-env)

Additional minikube commands;

minikube stop                        # stop minikube
minikube start                       # restart stopped minikube
eval $(minikube docker-env --unset)  # unset minikube docker environment
minikube status                      # check current status of minikube

The minikube status output should be:

minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

If restarting a stopped minikube, run make minikube-metallb-config from local ska-cicd-deploy-minikube repository to reapply metallb configMap, which is used to determine the pods’ LoadBalancer services’ external IP addresses.

2. Build the MCS application image.

Note: to get around the .make submodule tagging images with -dirty, the VERSION variable can be set to the current version in Makefile or PrivateRules.mk, e.g. VERSION=1.6.0.

From the root of the ska-mid-cbf-mcs repo;

make oci-image-build

make oci-image-build is required only if a local image needs to be built, for example every time the source code has been updated and a developer would like to test their changes.

For development, in order to get local changes to build, run eval $(minikube docker-env) before make build

Note: To check if you are within the minikube’s docker environment, use the minikube status command. It will indicate docker-env: in use if in use as follows:

minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured
docker-env: in-use

3. Install the MCS Helm chart.

make k8s-install-chart       # deploy from Helm charts
make k8s-install-chart-only  # deploy from Helm charts without updating dependencies
make k8s-reinstall-chart     # redeploy from Helm charts
make k8s-uninstall-chart     # uninstall deployment when finished testing
make k8s-watch               # watch k8s resource statuses
make k8s-wait                # wait until all jobs are 'Completed' and pods are in 'Running' state

Note: if the charts fail to install with the following error, delete any Chart.lock files in the charts/ directory and try again.

Error: the lock file (Chart.lock) is out of sync with the dependencies file (Chart.yaml). Please update the dependencies

The amount of each primary Mid.CBF resource to deploy (subarray, VCC and FSP) can be varied using the SUBARRAYS, VCC_UNITS and FSP_UNITS environment variables (default values set in Makefile or PrivateRules.mk). CI/CD pipeline default values are set in the .gitlab-ci.yml file.

4. Create python virtual environment and install project dependencies.

MCS requires Python 3.10 or above. Poetry is used for dependency management.

python3 -m venv <venv path>      # create virtual environment at a given path
source <venv path>/bin/activate  # activate virtual environment
pip install poetry               # install poetry
poetry install                   # install project dependencies

5. Run a test.

make k8s-test       # functional tests; require a running deployment
make python-test    # unit tests; deployment does not need to be running

Note: add -k <matching string> to PYTHON_VARS_AFTER_PYTEST or K8S_VARS_AFTER_PYTEST variables in Makefile or PrivateRules.mk to select particular test cases for functional and unit tests respectively.

Generating Documentation

To re-generate the documentation locally prior to checking in updates to Git:

make docs-build html

To view the generated documentation, open /ska-mid-cbf-mcs/docs/build/html/index.html in a browser – e.g. Firefox;

firefox docs/build/html/index.html &

Releasing

Please see Confluence for directions on creating a new release for MCS: CIPA Release Process

For a new release (i.e. prior to merging a branch into main) update the following files by incrementing version/release/tag number fields to conform to the semantic versioning convention:

• .release: release= and tag=

• pyproject.toml: version=

• src/ska_mid_cbf_mcs/release.py: version =

• charts/ska-mid-cbf/Chart.yaml: version: and appVersion:

• charts/ska-mid-cbf/values.yaml: midcbf:image:tag:

Note: appVersion represents the version of the application running, so it corresponds to the ska-mid-cbf-mcs image version.

Development resources

Other resources

See more tango device guidelines and examples in the ska-tango-examples repository

Useful commands

Kubernetes

For Kubernetes basic kubectl commands see: https://kubernetes.io/docs/reference/kubectl/cheatsheet/

To set up autocomplete for kubectl commands, add the following line to your .bashrc file:

source <(kubectl completion bash)

License

See the LICENSE file for details.