Operations Guide

Referenced documentation

Introduction

The Kroki component is part of Software Factory as a Package (SWaaP).

With the GitLab - Kroki integration, you can create diagrams-as-code within AsciiDoc, Markdown, reStructuredText, and Textile.

Learn more about it in LLD-Kroki and in TASD .

Billing and onboarding

This section aims at describing how billing related to the component is managed and at specifying offers including access to the component.

Component deployment and configuration

Requirements & Pre-requisite

See LLD-Kroki §4.2 prerequisites

Configuration

Setting Helm values

Kroki doesn’t require mandatory helm values for a default deployment.

Some optional values can be adjusted based on your specific requirements. We recommend the following settings injected via SWAP:

• Some diagrams, like Excalidraw, have verbose textual descriptions that will produce long URI. If the URI requested by the client is longer than the server is willing to interpret, the server will return a 414 (Request-URI Too Long) response status code. The default max URI length in Vert.x is 4096. Most modern browsers support a URI length greater than 64000 on <img> tags but this value is probably a bit excessive. We recommend to use a maximum length that’s not greater than 8192:

extraEnvVars:
- name: KROKI_MAX_URI_LENGTH
  value: "8192"

• Security recommends keeping the platform level to WARN:

loglevel: WARN

![WARNING] INFO is considered too verbose for production environments.

Configuring Kubernetes secrets

No specific Kubernetes secrets are required for Kroki.

Deployment & update procedure

The deployment and update procedures are described in the SWaaP Readme - Quick start section .

Settings

Kroki is a opensource tool and it can run standalone, without any dependencies.

Functional Configuration

GitLab recommends Kroki as the preferred diagram rendering tool for integrating diagrams-as-code within their platform. More on how to configure Kroki with GitLab can be found in the Enable Kroki section of the GitLab operations guide.

Logging

Kroki runs as one or more containers within Kubernetes Pods. As with most containerized applications, Kroki outputs its logs to stdout and stderr, which are automatically captured by Kubernetes.

Kubernetes stores container logs on each node in the following locations:

• /var/log/containers/ - Contains symlinked log files for each container, named using the format <pod>_<namespace>_<container>-<container-id>.log.
• /var/log/pods/<namespace>_<pod>_<uid>/ - Contains per-container directories with:
  • *-stdout.log for standard output
  • *-stderr.log for standard error

These logs ultimately map back to container runtime storage (e.g., Docker) under /var/lib/docker/containers/.

Kroki does not implement its own file-based logging system; it relies entirely on standard container and Kubernetes logging mechanisms.

Accessing Kroki Logs Inside the Cluster

Logs can be retrieved using standard Kubernetes CLI commands.

1. List Kroki Pods : kubectl get pods -n <namespace>
2. View Logs for a Specific Kroki Pod: kubectl logs <pod-name> -n <namespace>
3. Stream Logs in Real Time: kubectl logs -f <pod-name> -n <namespace>
4. View Logs from a Previous Pod Instance (After Restarts): kubectl logs <pod-name> --previous -n <namespace>

Recommendation: Use a Centralized Logging System

While node-level logs and kubectl logs provide basic retrieval capabilities, production environments benefit significantly from a centralized logging system. Centralized logging offers:

• Improved reliability by preventing log loss during Pod rescheduling or node replacements.
• Advanced capabilities such as full-text search, retention policies, auditing, and alerting.
• Consolidated observability across the entire cluster.

Common centralized logging solutions include:

• ELK / OpenSearch Stack (Elasticsearch, Logstash/Fluentd, Kibana)
• Loki with Promtail and Grafana
• Fluent Bit / Fluentd with cloud-native logging services (e.g., Azure Monitor, AWS CloudWatch, GCP Cloud Logging)

Monitoring Kroki

Monitoring Kroki ensures that the service remains healthy, responsive, and capable of rendering diagrams efficiently. Kroki exposes built-in health endpoints suitable for Kubernetes probes and monitoring systems.

Health Endpoints

Kroki provides the following endpoints:

• /health - Primary health check endpoint
• /v1/health - Versioned alias
• /healthz - Kubernetes-friendly alias commonly used for liveness probes

These endpoints return JSON responses containing service status and version information for Kroki and all configured diagram engines.

Using Kubernetes Probes

You can integrate Kroki health endpoints into your Pod specification:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

Observability and Metrics

While Kroki does not provide a built-in metrics endpoint, you can monitor:

• Pod-level CPU/memory usage
• Request volume and latency
• Diagram rendering failures