dasomel
한국어
All systems
WORK / ACTIVE SYSTEM

NFS Quota Agent

Kubernetes agent that enforces filesystem Project Quotas for NFS PersistentVolumes

Kubernetes · Go · Storage · NFS · XFS · ext4 · Btrfs · Quota · Prometheus
Source
01 / Problem02 / Architecture03 / Development04 / Proof05 / Knowledge06 / Record
01 / PROBLEM

Kubernetes NFS PersistentVolumes can expose requested capacity without enforcing an equivalent filesystem-level limit on the shared NFS storage

RESPONSE

A node-local agent that watches NFS PVs and applies filesystem Project Quotas on the actual NFS server using XFS, ext4, or Btrfs quota mechanisms

02 / ARCHITECTURE

Read the boundaries before the features.

Identity, delivery, network, storage and workload integration are shown as operational seams rather than a feature inventory.

NFS Quota Agent flow from PVC and PV through agent DaemonSet and quota adapter to filesystem and metrics
NFS Quota Agent turns Kubernetes storage requests into enforceable filesystem quotas.
ARCHITECTURE / HOW IT WORKS

NFS Quota Enforcement Flow

01
PVC / PV
Requested storage capacity
02
Agent DaemonSet
Watches NFS PersistentVolumes
03
Quota Adapter
XFS · ext4 · Btrfs
04
Filesystem
Project / qgroup quota enforced
05
Metrics / UI
Annotations · Prometheus · dashboard
PVC capacity becomes a real filesystem quota by watching NFS PersistentVolumes and applying the appropriate quota mechanism on the NFS server node.
02A / OPERATOR VIEW

The dashboard makes enforcement visible.

Five built-in views connect quota state, cleanup, growth, policy and audit evidence.

Read the Web UI guide ↗
Quotas dashboard screenshot
Quotas dashboard
전체 PV 쿼터와 사용량 상태
Orphans screenshot
Orphans
고아 디렉터리와 정리 유예 상태
Trends screenshot
Trends
사용량 증가 추이
Policies screenshot
Policies
네임스페이스별 정책 적용 결과
Audit logs screenshot
Audit logs
쿼터 변경 감사 로그
03 / DEVELOPMENT OVER TIME

Evolution is part of the evidence.

First commit, cumulative commits, releases and recent activity show whether the system is still being engineered.

DEVELOPMENT OBSERVATORY
dasomel/nfs-quota-agent

Observe a system evolving over time, not a repository frozen at one release.

Contributors: 3
First commit
Jan 24, 2026
Commits
602
Releases
15
Latest release
v0.4.3
Last push
Sep 19, 2026
Active for
8 months
Recent development activity
381 commits / 20 weeks
PAST → NOW
Language: GoLicense: Apache-2.0Stars: 4Forks: 0Open issues: 1Latest release
04 / PROOF, NOT BADGES
9
technology / domain signals

Declared scope and technical context

6
connected docs

Operational or implementation documentation

4
engineering notes

Knowledge produced by the project

0
digest links

External signals explicitly connected

05 / CONNECTED KNOWLEDGE

What this system produced beyond code

06 / ENGINEERING RECORD

Implementation details, operating notes and project-specific context.

Project Overview

NFS Quota Agent closes the gap between Kubernetes storage objects and the filesystem that actually stores NFS data.

A PVC may request 10Gi, but a normal NFS provisioner does not automatically turn that request into a hard limit on the NFS server directory. The agent watches NFS PersistentVolumes, maps them to their local export paths, and applies the appropriate filesystem quota.

This makes it a Kubernetes + Linux filesystem enforcement component, not merely another storage controller.

Core Flow

The agent supports native NFS PVs and CSI NFS PVs, including path mapping based on NFS share/subdirectory metadata.

Filesystem Support

FilesystemMechanismNotes
XFSxfs_quota / project quotaPrimary use case
ext4setquota + project attributeLinux project quota support
Btrfsqgroup quotaTarget directories must be subvolumes

Kubernetes Deployment Model

The agent runs as a DaemonSet on the NFS server node because quota operations must target the local filesystem rather than an NFS client mount.

This creates a larger privilege boundary than a normal Kubernetes controller, so node placement and hostPath scope are part of the security design.

Operational Features

The project includes optional operational capabilities around the core enforcement engine:

  • Prometheus metrics / ServiceMonitor
  • PrometheusRule alerts
  • audit logging
  • usage history
  • orphan cleanup with dry-run support
  • namespace quota policy
  • optional web UI
  • configurable sync interval
  • Helm-based deployment and rolling upgrades

Storage Policy

When policy support is enabled, Kubernetes-native resources can be used to express quota defaults and limits. This keeps storage governance close to the existing Kubernetes resource model instead of inventing a completely separate configuration language.

Safety Boundaries

Because the agent changes real filesystem state:

  1. schedule only on intended NFS server nodes
  2. restrict hostPath to the actual export
  3. keep destructive cleanup disabled or dry-run by default
  4. expose quota state through annotations and metrics
  5. review host access changes during Helm upgrades

Getting Started

git clone https://github.com/dasomel/nfs-quota-agent.git
cd nfs-quota-agent
make build

Deploy to Kubernetes:

kubectl label node <nfs-server-node> nfs-server=true
helm install nfs-quota-agent ./charts/nfs-quota-agent \
  --namespace nfs-quota-agent --create-namespace

Documentation Index

TopicDocumentPurpose
OverviewAgent OverviewProblem and enforcement model
ArchitectureStorage ArchitecturePV mapping and quota execution
Feature GuideFeaturesFilesystems, policies, metrics
Getting StartedInstallation & SetupHelm and host preparation
FeaturesFeature DetailsOptional operational features
OperationsOperations & MonitoringMonitoring, cleanup, troubleshooting
Web UIWeb UIStorage administration surface

Project Relationship