DC

Field notes • Kubernetes

All field notes

001 / Kubernetes

Introducing Git Content CSI Driver

David Collom

5 min read

Git-backed runtime content still has a place in Kubernetes. The question is how to make it safer, more governed and easier for platform teams to operate.

I’ve open-sourced gitrepo-csi-driver, a Kubernetes CSI driver for mounting Git repository content into Pods as read-only ephemeral volumes.

The short version: it gives platform teams a safer and more governed way to provide Git-backed runtime content without asking every workload to carry its own clone logic, credentials, retries, cache handling and policy checks.

The project was prompted by the removal of the in-tree Kubernetes gitRepo volume driver in Kubernetes 1.36. That old feature was convenient, but it also put Git clone behaviour inside kubelet and carried real security problems, including Git hook execution and node-local repository access risks.

I did not want to recreate gitRepo as a drop-in replacement. The more useful problem is not, “how do we get the old thing back?” It is, “how should a platform expose Git-hosted content now that we understand the operational and security trade-offs better?”

gitrepo-csi-driver takes a platform-owned approach.

A workload requests approved Git content through an inline CSI volume. The node plugin evaluates policy, clones the repository, checks out the requested branch, tag or commit, writes provenance metadata, and publishes only the materialised content into the Pod. The mounted content is read-only, .git internals are kept out of the workload-visible filesystem, and repository access is controlled centrally.

What is in the MVP

The first MVP includes:

  • a real CSI node service over gRPC;
  • inline ephemeral CSI volume support;
  • Helm installation;
  • branch, tag and pinned commit refs;
  • repository, host, revision, path, depth, submodule and LFS policy controls;
  • read-only content publishing;
  • .gitcontent metadata with the resolved commit;
  • Prometheus metrics;
  • an admission webhook for early validation;
  • kind-based E2E tests across Kubernetes 1.33 to 1.36.

This is aimed at cases where Git semantics are still useful at Pod start: static site content, documentation, policy bundles, templates, shared read-only scripts, generated reports, dashboards and other content where repo, path and revision matter.

It is not intended to replace proper application artefact release flows. If something should be built, scanned, signed and shipped as an image or OCI artefact, that is still usually the right answer. This driver is for the narrower class of workloads where mounting approved Git content is the platform capability people actually need.

Why not just use an init container?

Init containers are still a valid answer for some workloads.

The problem is what happens when the pattern spreads. Credentials end up repeated across namespaces. Clone behaviour differs from team to team. Branch and tag usage becomes inconsistent. Failures are hidden inside application startup. Security teams have no single place to enforce what can be mounted.

That is exactly the kind of friction a platform should remove.

Application teams should be able to describe the content they need. Platform teams should be able to decide which repositories, refs, paths and features are allowed. Operators should have metrics and events that show what is happening when content fails to mount.

Security shape

The security model is deliberately conservative.

Local filesystem paths and file:// repositories are rejected. Git hooks are disabled. Submodules and Git LFS are off unless policy allows them. Workloads do not need privileged mode, hostPath mounts, runtime sockets or elevated Linux capabilities.

The workload does not receive the internal Git repository. It receives a separate content tree plus .gitcontent metadata, including the resolved commit. That provenance matters when a branch or tag has moved and somebody needs to understand what was actually mounted.

There is still more hardening I want to do, especially around separating materialisation into a dedicated non-root helper. The current project is already at the point where it installs into kind and passes an E2E suite that exercises real CSI volume publishing for branch, tag and commit refs.

Where I land

For me, this is a good example of the kind of platform engineering I enjoy: taking a repeated workflow, removing the sharp edges, and giving teams a path that is easier to operate and easier to reason about.

Git-backed runtime content is not the answer to every packaging problem. It is useful often enough that it deserves a safer platform-owned pattern.

The repository is here: github.com/davidcollom/gitrepo-csi-driver