DHIS2 Kubernetes Quick Start

.gitignore

.idea

README.md

DHIS2 Kubernetes Quick Start

This tutorial is intended as a brief introduction to deploying DHIS2 on Kubernetes. It's by no means exhaustive and is simply supposed to get you started.

• Prerequisites
• Kubernetes
  • Distributions
    • Microk8s
    • K3s
  • Connect to Kubernetes
  • Deploying applications
• DHIS2
  • Deploying
  • Cleanup
  • Configuration
• Ready for production... ?
• Feedback, support or whatever :-)

Prerequisites

The commands listed in this tutorial are intended to run in a Bash shell. If you operating system is Windows based you need to use a virtual machine or WSL.

Before you begin, you should have the following command line tools installed

• Kubectl
• helm
• skaffold

Kubernetes

Just like Linux comes in different flavors, so does Kubernetes. For local testing I'd recommend either of the following distributions

• Microk8s
• K3s

Before continuing with this tutorial you should have a working cluster and the environment variable KUBECONFIG configured accordingly.

Warning: Storage and ingress must be enabled otherwise DHIS2 won't start

Please consult the docs but the below commands might help configuring the KUBECONFIG environment variable.

Distributions

Microk8s

sudo microk8s kubectl config view --raw > $HOME/.kube/microk8s.yaml
chmod go-rwx $HOME/.kube/microk8s.yaml
export KUBECONFIG=$HOME/.kube/microk8s.yaml

K3s

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

Connect to Kubernetes

Use the below commands to confirm your cluster is working.

kubectl get pods --all-namespaces
helm ls --all-namespaces

Deploying applications

Note: If your goal simply is to deploy DHIS2 on Kubernetes you can skip this section

Applications can be deployed using various means such as Helm, Kustomize and even raw yaml files. Due to various reasons, beyond the scope of this text, my recommendation is Helm.

The below tutorial provides a good overview of the relationship between deployment, service and ingress.

https://dwdraju.medium.com/how-deployment-service-ingress-are-related-in-their-manifest-a2e553cf0ffb

DHIS2

Deploying

Although not officially released or supported we do have a helm chart for DHIS2 which can be found here. Checkout the project using the below commands.

git clone https://github.com/dhis2-sre/dhis2-core-helm.git
cd dhis2-core-helm/

With a working, cluster DHIS2 can be installed using a single command. Run the following to deploy DHIS2 and an instance of Postgresql seeded with the Sierra Leone database.

skaffold run

It might take some time to download the images and for DHIS2 to start. The progress can be checked using the below command.

kubectl get pods --all-namespaces

Upon successful deployment DHIS2 should be available at http://dhis2-core.127.0.0.1.nip.io

Cleanup

Delete your DHIS2 instance using the below command.

skaffold delete

Configuration

You can configure DHIS2 by changing the values file found here but following best practices you should create a new values file which only contains the changes specific to your needs and reference that from the skaffold.yaml file.

Ready for production... ?

• Log aggregation... Grafana/loki
• Metrics and more... ELK stack
• HTTPS... Let's Encrypt
• Backup... Velero
• ...

Feedback, support or whatever :-)

You guys are welcome to reach out!

Makefile

toc:
	doctoc .

pdf:
	pandoc --from=gfm --to=pdf -V geometry:margin=0.7in README.md -o 'DHIS2 Kubernetes Quick Start.pdf'

Using microk8s I had to enable the following:

microk8s enable hostpath-storage dns ingress