Korthweb project provides two approaches to automatically deploy Orthanc on Kubernetes. Orthanc is an open-source application to ingest, store, display and distribute medical images. Korthweb is a sister project of Orthweb, an deployment automation project for Orthanc on AWS EC2.
Users of this project may come from various backgrounds. The business requirement of this project is to deploy Orthanc (stateless app + database) on Kubernetes, to securely host DICOM and web workloads. To automate this effort, I have to incorporate the following configurations:
- Ingress (Istio or Traefik) TLS termination on HTTP and TCP ports
- Use Cert Manager to provision self-signed certificate
- Traffic routing with Istio (Gateway, Virtual Serivce)
- Istio Installation (using Helm charts or Istioctl)
- Security with Istio (Peer Authentication/mTLS, Authorization Policy)
- Deploy observability addons (Prometheus, Grafana) for Istio
- Use bitnami Helm chart to deploy PostgreSQL
- Build your own Helm Chart to deploy apps
- GitOps with FluxCD for Continuous Deployment
To get started, you need a Kubernetes cluster. My real-quicK-cluster project has guidance to provision a demo cluster real quick (with a couple commands). Apart from a cluster, you will also need the following tools on the client side:
- kubectl: connect to API server to manage the Kubernetes cluster. With multiple clusters, you need to switch context.
- helm: helm is package manager for Kubernetes. It is used in all three approaches to install third party charts such as PostgreSQL
- istioctl: istioctl is an alternative to helm to install istio manually.
- flux: FluxCD is a GitOps tool to keep target Kubernetes cluster in sync with the source of configuration in the GitOps directory. The name of FluxCD's CLI tool is flux.
I started this project by manually applying a few manifests. For templating capability, I then baked them into a Helm chart. For faster iteration, I then added a GitOps approach. As a result, the project today consists of three automation levels: manual, Helm Chart, and GitOps. The table below summarizes the differences among these automation levels:
| Automation Approach | Components Installed | Highlights |
|---|---|---|
| GitOps | - Istio Ingress - Other Istio Features - PostgreSQL - Cert-Manager - Multi-tenancy - Observability |
- Includes YAML manifests required for GitOps-based automated deployment using FluxCD. - Take this approach for best practices with continuous deployment. - Two instances (for two fictional healthcare facilities named BHC and MHR) are deployed. |
| Helm Chart | - Traefik Ingress - PostgreSQL |
- Includes the Helm chart to configure Orthanc and its dependencies with a single command. - Take this approach to quickly install Orthanc on Kubernetes. |
| Manual | - Istio Ingress - Other Istio Features - PostgreSQL - Cert-Manager - Observability (Lite) |
- Includes YAML manifests for all required resources for users to manually apply. - Take this approach ONLY for troubleshooting or learning. |
The artifacts of each automation approach are kept in their eponymous sub-directories. As the table above suggests, go with the GitOps approach for deployment capability. Go with the Helm Chart approach for quick installation.
Orthanc with its dependencies in production must be configured with scalability, resiliency and high availability. Even though Korthweb is a starting point with minimum configuration, there is no one-size-fit-all solution design, I included a separate guideline for database and image storage. The rest of this section discusses networking, security and deployment automation.
At container level, Orthanc uses TCP port 8042 for web traffic, and TCP port 4242 for DICOM traffic. On Kubernetes, we use ingress to expose both ports (443 for web and 11112 for DICOM). The ingress controller also does TLS termination and load balancing.
In the Helm approach, we use Traefik CRD for Ingress. In GitOps and Manual approaches where we install Istio, we use Istio Gateway as Ingress.
Service mesh acts as an intermediary layer between the application workload and the underlying platform. This layer commoditizes a variety of common features, such as tracing, mTLS, traffic routing and management. While an application may choose build these features natively in its own code, the idea of service mesh is to allow application developer to focus on the business logic and push networking concerns to this intermediary layer.
Istio is a service mesh product. We use it for Ingress, TLS termination, mTLS, authorization and observability. Once deployed, service-to-service connections (e.g. application to database) automatically take place in mTLS and there is no need to explicitly configure TLS on database connection, as is done in the Helm Chart approach.
Applications today are released as container images and are hosted as microservices, which brings new challenges to observability. Istio supports observability add-ons, such as Prometheus to expose envoy (Istio sidecar) metrics and Grafana and Kiali for dashboard display. In manual or GitOps approaches, Kiali is neither exposed on Ingress gateway, or integrated with any IAM system. To access Kiali, we can use port-forwarding. Refer to the instruction in each approach.
We play with Helm in two ways: reusing other's Chart and building our own. Bitnami publishes Helm Charts for common applications (e.g. PostgreSQL) and we simply piggyback on their great work wherever applicable, by deploying their Charts in our platform.. In addition, with the Helm Chart approach, we also build our own Helm Chart (named orthanc) to package Orthanc workload along with dependencies. Our Helm chart makes Orthanc deployment a single command. We did not include Istio in this approach for simplicity. Instead of Istio as Gateway, we use Traefik CRD for Ingress.
FluxCD is a tool to drive GitOps-based deployment. GitOps is a relatively new deployment approach. With GitOps, source of truth about the deployment is declared in the GitOps directory of this repository or your fork. FluxCD is installed in the target cluster, which watches the source and keeps the target kubernetes cluster state in sync. The GitOps directory serves as the source for deployment. Read the instruction in the directory for more details.
The GitOps approach is more flexible than the Helm approach and can accomodate many deployment techniques. However it is more complicated to use than the Helm approach.
This project is developed with security in mind. We create self-signed certificate to secure both DICOM and web traffic. In the Helm approach, we use Helm template to create self-signed certificate. In Gitops and manual approaches, we use cert manager. Certificate and Secrets are stored as Kubernetes secret object.