techlist.io
KREN
gitlab

Consolidate your GitLab stack with Gitaly on Kubernetes (opens in new tab)

k8sgitlabgitgitopshelmcontainerdcgroupsgitaly

Gitaly on Kubernetes is now generally available with GitLab 18.11, allowing teams to run their entire GitLab stack in Kubernetes instead of maintaining Gitaly on separate virtual machines. GitLab addressed Kubernetes-specific challenges involving cgroup isolation, pod restarts, and request reliability. The result is a more unified deployment model, though full high availability still depends on Gitaly Cluster support for Kubernetes.

Challenges of Running Gitaly on Kubernetes

  • Git operations can consume unpredictable amounts of memory.
  • Gitaly isolates individual Git processes in dedicated cgroups so an out-of-memory failure does not bring down the main Gitaly process.
  • Kubernetes deployments required special handling because containerd traditionally restricted cgroupfs writes to privileged containers.
  • GitLab solved this by using an init container to mount /sys/fs/cgroup and make it writable.

Handling Pod Restarts

  • Virtual-machine deployments can upgrade Gitaly in place and reload gracefully while preserving the socket.
  • Kubernetes StatefulSet replacements cause pods to stop and restart abruptly during upgrades, node drains, or configuration changes.
  • This could cause downtime, particularly for Gitaly Sharded deployments without built-in high availability.
  • GitLab made Gitaly client retries configurable, allowing clients such as Rails to retry requests until Gitaly becomes available again.
  • Users may experience slightly higher latency during restarts, but requests generally succeed without visible downtime.

Benchmark Results and High Availability

  • GitLab tested common Git operations against VM-based and Kubernetes-based Gitaly installations during upgrades.
  • Success rates were nearly identical in both environments despite Kubernetes abruptly terminating pods and closing sockets.
  • Achieving complete success across every operation still requires Gitaly Cluster with Praefect.
  • Praefect does not yet support Kubernetes, but Kubernetes support is being developed.

Benefits for GitLab Deployments

  • Teams with hybrid infrastructure can move Gitaly from virtual machines into their existing Kubernetes cluster.
  • This removes the need to maintain and monitor a separate VM fleet.
  • Organizations adopting GitLab on Kubernetes can use a fully Kubernetes-native deployment through the official Helm chart.
  • Gitaly can run as part of a complete GitLab installation or as an external component.

Installation

  • The recommended deployment method is the GitLab Helm chart.
  • Users should review the Gitaly on Kubernetes documentation before installation.
  • The documentation covers configuration guidance, common pitfalls, full installations, and external Gitaly deployments.

Gitaly on Kubernetes is a practical option for consolidating GitLab infrastructure and simplifying operations. Teams should use the Helm chart and configure client retries carefully, while recognizing that Kubernetes-based high availability through Praefect is still forthcoming.