Use Kubernetes

This section describes how to install Kroki on Kubernetes using the default namespace.

On this page you will find how to:

  • Use Ingress to expose the service on port 8000.

  • Download and extract the example Kroki Kubernetes definition files

  • Install the Kubernetes objects as a batch or one by one.

  • Validate the installation

  • Delete the Kroki installation

  • Use Helm Chart to install/uninstall Kroki

Providing external access to Kroki

To allow external access to your Kroki internal service, you publish the service using ClusterIP, NodePort, LoadBalancer or ExternalName.

This example uses Ingress to expose the service on port 8000.

Read more about how to publish a service on the Kubernetes documentation website.

Deploy using Kubernetes object definition files

Extract the definition files

Prepare the definition files by doing the following:

  1. Download the example bundle kroki-k8s-multipod.zip that contains all the required Deployment, Service and Ingress definition files to deploy Kroki on Kubernetes.

    Example command with wget installed
    wget http://docs.kroki.io/kroki/setup/_attachments/kroki-k8s-multipod.zip -O kroki-k8s-multipod.zip

  2. Extract the contents of the above zip file into a folder named kroki-k8s.

    Example command with unzip installed
    unzip kroki-k8s-multipod.zip -d kroki-k8s

In the next steps you use the *.yaml files beneath the directory kroki-k8s and apply them in batch or individually, to create the Kubernetes objects.

Create objects as a batch

To install (create) all the Kubernetes objects in a batch, do the following:

Use the command kubectl apply to create all the required Kubernetes objects, replacing /path/to/kroki-k8s with the path to the folder containing the *.yaml definition files.

Example command with kubectl installed
kubectl apply -f /path/to/kroki-k8s

Your next step is to Validate that Kroki is running.

Read more about working with Kubernetes objects on the Kubernetes website.

Create objects individually

Alternatively they can be applied individually.

To install them individually from GitHub, open a terminal and type commands indicated for each service:

Add Mermaid service
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/mermaid-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/mermaid-service.yaml
Add BPMN service
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/bpmn-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/bpmn-service.yaml
Add Excalidraw service
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/excalidraw-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/excalidraw-service.yaml
Add Kroki service
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/kroki-deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/kroki-service.yaml
Add Ingress
kubectl apply -f https://raw.githubusercontent.com/yuzutech/kroki/refs/heads/main/docs/modules/setup/examples/k8s-multi-pod/kroki-ingress.yaml

Your next step is to Validate that Kroki is running.

Validate that Kroki is running

After installing the Kroki Kubernetes objects you verify that Kroki is running.

To verify that the Kroki service is running, do the following:

  1. Run the kubectl get pod command:

    kubectl get pod

    If the installation is successful, a list of running pods is shown that includes the following:

    NAME                          READY   STATUS    RESTARTS   AGE
bpmn-6cfccf9bc4-6w4px         1/1     Running   0          24s
excalidraw-5b84995fcb-dh57t   1/1     Running   0          24s
kroki-6b49bcb7c4-x2ksc        1/1     Running   0          23s
mermaid-7bff5c9959-hkrxx      1/1     Running   0          22s

  2. To make sure that Kroki is working, open a terminal and type:

    kubectl port-forward service/kroki 8000:8000

    The above command forwards local port 8000 to port 8000 on the service/kroki Pod. In other words, Kroki is accessible on localhost:8000.

  3. Open a second terminal and type:

    curl http://localhost:8000/seqdiag/svg/eNorTi1MyUxMV6jmUlBIKsovL04tUtC1UyhPTQKyyoCc6JzEpNQcBVsFJXfXEAX9zLyU1Aq9jJLcHKVYayQ9Nrq6CE3WhA0L8A8GmpaUk5-un5yfm5uaVwIxD6EWqDElsSQxKbE4FUmfp1-wa1CIAg49IFfANOFxXS0A68hQUg==

    If successful, a diagram is shown.

Uninstall Kroki

If you installed Kroki using the downloaded and unpacked *.yaml files, Kroki can be deleted using those same files.

To uninstall Kroki, use the command kubectl delete as follows:

kubectl delete -f /path/to/kroki-k8s

Use a Single Pod Consisting of Multiple Containers

As a much simpler (but less-flexible) configuration, it is possible to run all containers inside of a single Kubernetes pod.

  1. Download the example bundle kroki-k8s-singlepod.zip that contains all the required Deployment, Service and Ingress definition files to deploy Kroki on Kubernetes.

    Example command with wget installed
    wget http://docs.kroki.io/kroki/setup/_attachments/kroki-k8s-singlepod.zip -O kroki-k8s-singlepod.zip

  2. Extract the contents of the above zip file into a folder named kroki-k8s.

    Example command with unzip installed
    unzip kroki-k8s-singlepod.zip -d kroki-k8s

You can then create the Kubernetes objects as a batch or individually, similar to what was shown previously.

Validation and uninstall/removal of Kubernetes objects can be followed using the exact same commands as shown previously too.

Deploy using Helm Charts

You can alternatively deploy Kroki using Helm Charts. It’s much easier to deploy Kroki with charts, since all object definition files are managed by Helm.

This is an unofficial chart maintained by cowboysysop.

To install Kroki using the name my-kroki, use the following command:

Example command with helm installed
helm repo add cowboysysop https://cowboysysop.github.io/charts/
helm install my-kroki cowboysysop/kroki

Use the following helm command to verify the installation:

Example command with helm installed
helm status my-kroki --show-resources --show-desc

If the installation is successful, the following status is shown:

NAME: my-kroki
LAST DEPLOYED: Mon Oct  7 17:06:09 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
RESOURCES:
==> v1/Pod(related)
NAME                     READY   STATUS        RESTARTS   AGE
kroki-6db8878b8f-zn8kz   5/5     Running       0          13d

==> v1/ServiceAccount
NAME    SECRETS   AGE
kroki   0         14d

==> v1/Service
NAME    TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
kroki   ClusterIP   10.43.100.80   <none>        8000/TCP   14d

==> v1/Deployment
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
kroki   1/1     1            1           14d


NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=kroki,app.kubernetes.io/instance=kroki" -o jsonpath="{.items[0].metadata.name}")
  echo "Visit http://127.0.0.1:8000/ to use your application"
  kubectl --namespace default port-forward $POD_NAME 8000:8000

You can use the exact same commands as shown in Validate that Kroki is running to make sure that Kroki is running fine.

To uninstall Kroki, use the command helm uninstall as follows:

Example command with helm installed
helm uninstall my-kroki