doc: add design proposal for SA based volume access restriction

Signed-off-by: Rakshith R <rar@redhat.com>

Author: Rakshith-R

docs/design/proposals/sa-based-volume-access-restriction.md

@@ -0,0 +1,145 @@
+# Service Account Based Volume Access Restriction
+
+## Introduction
+
+This proposal introduces an optional mechanism to restrict volume access based
+on the Kubernetes service account of the pod mounting the volume. When
+configured, only pods running with the specified service account are allowed to
+mount the volume. All other mount attempts are rejected with a
+`PermissionDenied` error.
+
+The restriction is stored as metadata on the backend Ceph object (RBD image
+metadata or CephFS subvolume metadata) and is enforced at mount time through
+the CSI `podInfoOnMount` mechanism.
+
+## Motivation
+
+Ceph-CSI volumes are accessible to any pod that has a valid PVC reference and
+the necessary RBAC to use the StorageClass. In multi-tenant and data pipeline
+environments, this is insufficient. There are scenarios where a volume should
+be exclusively accessible to a specific workload identity even when other pods
+in the same namespace can reference the PVC.
+
+### Use Case: Ceph VolSync Plugin Replication Destination PVC Protection
+
+A primary motivator for this feature is the custom
+[Ceph VolSync Plugin](https://github.com/RamenDR/ceph-volsync-plugin) that
+performs incremental data replication across clusters. In a disaster recovery
+or migration workflow:
+
+1. A `ReplicationDestination` controller creates a PVC on the destination
+   cluster to receive replicated data.
+1. A replication worker pod, running under a dedicated service account (e.g.
+   `volsync-worker-sa`), incrementally syncs data from the source cluster into
+   this destination PVC.
+1. The destination PVC must remain writable only by the replication worker
+   until the replication is complete and a failover is triggered.
+
+Without service account based restriction, any pod in the namespace with a
+reference to the destination PVC could write to it, potentially corrupting the
+replicated data or breaking the incremental sync state. By binding the
+destination volume to the replication worker's service account, the volume is
+protected from unintended writes throughout the replication lifecycle. On
+failover, the restriction is removed so the application workload can mount
+the volume.
+
+### Other Potential Use Cases
+
+- **Sensitive data volumes**: Restrict access to volumes containing regulated
+  data to only the service account authorized to process them.
+- **Custom usecases**: Similar usecases where a workload identity needs exclusive
+  access to a volume for data integrity or security reasons.
+
+## Dependency
+
+- The `podInfoOnMount` field must be set to `true` in the CSIDriver
+  specification. This causes Kubelet to inject pod information (including the
+  service account name) into the volume context during `NodePublishVolume`.
+  Without this, the restriction cannot be enforced.
+  Since this parameter is a mutable field in the CSIDriver spec, it will be enabled
+  by default going forward(cephcsi v3.17.0+).
+
+## Design
+
+### Metadata Keys
+
+Each driver type uses a driver-specific metadata key to store the allowed
+service account name:
+
+| Driver | Metadata Key | Storage |
+|--------|-------------|---------|
+| RBD | `.rbd.csi.ceph.com/serviceaccount` | RBD image metadata |
+| CephFS | `.cephfs.csi.ceph.com/serviceaccount` | CephFS subvolume metadata |
+| NVMe-oF | `.rbd.csi.ceph.com/serviceaccount` | RBD image metadata (via RBD backend) |
+| NFS | `.cephfs.csi.ceph.com/serviceaccount` | CephFS subvolume metadata (via CephFS backend) |
+
+Only a single service account can be specified per volume.
+
+### CSI Flow
+
+The restriction is enforced across two CSI RPCs:
+
+1. **ControllerPublishVolume**: The controller reads the service account
+   metadata from the Ceph backend. If present, it is included in the publish
+   context passed to the node.
+
+1. **NodePublishVolume**: The node plugin compares the publish context value
+   against the pod's service account (provided by Kubelet via
+   `csi.storage.k8s.io/serviceAccount.name` in the volume context). A mismatch
+   results in a `PermissionDenied` error. If no restriction is set, or if
+   `podInfoOnMount` is not enabled, the mount is allowed (with a warning log
+   in the latter case).
+
+### Implementation
+
+A shared validation function `ValidateServiceAccountRestriction` in
+`internal/util/validate.go` is called at the beginning of `NodePublishVolume`
+in all four drivers (RBD, CephFS, NFS, NVMe-oF), ensuring consistent
+enforcement.
+
+Each driver reads the restriction metadata in `ControllerPublishVolume` using
+its backend:
+
+- **RBD**: reads via `GetMetadata` in `internal/rbd/controllerserver.go`.
+- **CephFS**: reads via `ListMetadata` in `internal/cephfs/controllerserver.go`.
+- **NVMe-oF**: delegates to the RBD backend and propagates the publish context
+  in `internal/nvmeof/controller/controllerserver.go`.
+- **NFS**: delegates to the CephFS backend in
+  `internal/nfs/controller/controllerserver.go`.
+
+## Setting and Removing the Restriction
+
+The restriction is managed through Ceph CLI commands. Refer to the
+"Service Account Based Volume Access Restriction" sections in
+[RBD deploy.md](../../rbd/deploy.md) and [CephFS deploy.md](../../cephfs/deploy.md)
+for usage instructions and examples.
+
+## Ceph VolSync Plugin Integration Example
+
+1. The replication destination worker sets the service account restriction on the backing Ceph
+   object(RBD image or cephFS subvolume) to the replication worker's service account (e.g.
+   `volsync-worker-sa`) on first use.
+1. Only the worker pod mounts the destination PVC successfully because its service 
+   account matches. Any other pod attempting to mount the same PVC is rejected with
+   `PermissionDenied` during NodePublish call, protecting data integrity during incremental sync.
+1. On replication destination deletion, the controller spins up a cleanup job
+   that removes the service account restriction metadata, allowing the application
+   workload to mount the volume.
+
+## Limitations
+
+- Only a single service account can be specified per volume.
+- Enforced at CSI mount time only; does not prevent direct access to the
+  underlying Ceph storage from outside Kubernetes.
+- If `podInfoOnMount` is not enabled, the restriction is silently unenforced.
+- Changing the restriction on an already-mounted volume does not affect
+  existing mounts. The volume must be unmounted and remounted.
+- Managed through Ceph CLI commands, not Kubernetes-native APIs.
+
+## Future Enhancements
+
+- Support restriction based on other attributes (e.g. name, namespace) in
+  addition to service account.
+- Provide more flexible configuration key value options (e.g. receiving both
+  expected key-value pairs in the volume context instead of a single service
+  account name).