Gitaly on Kubernetes Is Now Generally Available
GitLab has made Gitaly on Kubernetes generally available with the release of GitLab 18.11. This is a significant shift for teams who have long managed a hybrid setup, running most GitLab components in Kubernetes while keeping Gitaly on separate virtual machines.
That split architecture added unnecessary complexity. Now, with Gitaly on Kubernetes fully supported, teams can consolidate the entire GitLab stack under one environment.
Getting Gitaly to run natively on Kubernetes was not straightforward. Git operations are memory-intensive and hard to predict. To prevent out-of-memory (OOM) events from crashing the main Gitaly process, Gitaly can be configured to run each Git process in a dedicated cgroup. This isolates individual Git processes so that if one exceeds its memory limit, the main Gitaly process stays unaffected.
Making cgroups work inside a Kubernetes pod required extra engineering. Most Kubernetes clusters use containerd as their runtime. Until recently, containerd only allowed containers to write to cgroupfs in privileged mode. GitLab solved this by mounting /sys/fs/cgroup through an init container and making the path writable.
Pod restarts also posed a challenge. On a virtual machine, Gitaly can reload gracefully by keeping the socket open. On Kubernetes, however, a StatefulSet pod stops hard when replaced. There is no graceful handoff. To address this, GitLab made client retries configurable, so clients like Rails can retry requests long enough for Gitaly to restart. Users may see slightly higher latency, but requests succeed and downtime is avoided.
GitLab ran benchmarks to confirm this approach works. They tested common Git operations against two instances, one on VMs, one on Kubernetes, then triggered an upgrade mid-test. The results were nearly identical across both environments, with git clone achieving 100% success on both, git pull at 99.16% on Kubernetes, and git push at 100% on Kubernetes. Full 100% success across every operation would require Gitaly Cluster (Praefect), the high-availability solution. Kubernetes support for Praefect is actively in development.
For teams already running GitLab in hybrid mode, Gitaly on Kubernetes now makes full consolidation possible. There is no longer a need to maintain a separate VM fleet alongside Kubernetes nodes. New GitLab adopters who already operate on Kubernetes also benefit, since they can now run a fully Kubernetes-native deployment from day one using the GitLab Helm chart.
The recommended way to deploy Gitaly on Kubernetes is through the GitLab Helm chart. Before starting, it is worth reviewing the Gitaly on Kubernetes documentation, which covers key configuration steps and common pitfalls. Gitaly can also be deployed as an external component, and the documentation covers both scenarios.
