From ca9e4725d19ac93005bc9804868afee7fe225cba Mon Sep 17 00:00:00 2001
From: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
Date: Fri, 16 Feb 2024 10:23:33 +0900
Subject: [PATCH] KEP-3857: Recursive Read-only (RRO) mounts

Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
---
 content/en/docs/concepts/storage/volumes.md   | 58 +++++++++++++++++++
 .../recursive-read-only-mounts.md             | 14 +++++
 content/en/examples/storage/rro.yaml          | 28 +++++++++
 3 files changed, 100 insertions(+)
 create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/recursive-read-only-mounts.md
 create mode 100644 content/en/examples/storage/rro.yaml

diff --git a/content/en/docs/concepts/storage/volumes.md b/content/en/docs/concepts/storage/volumes.md
index f706f6f384..31c5bb4f9d 100644
--- a/content/en/docs/concepts/storage/volumes.md
+++ b/content/en/docs/concepts/storage/volumes.md
@@ -1213,7 +1213,65 @@ in `containers[*].volumeMounts`. Its values are:
   (unmounted) by the containers on termination.
   {{< /warning >}}
 
+## Read-only mounts
 
+A mount can be made read-only by setting the `.spec.containers[].volumeMounts[].readOnly`
+field to `true`.
+This does not make the volume itself read-only, but that specific container will
+not be able to write to it.
+Other containers in the Pod may mount the same volume as read-write.
+
+On Linux, read-only mounts are not recursively read-only by default.
+For example, consider a Pod which mounts the hosts `/mnt` as a `hostPath` volume.  If
+there is another filesystem mounted read-write on `/mnt/<SUBMOUNT>` (such as tmpfs,
+NFS, or USB storage), the volume mounted into the container(s) will also have a writeable
+`/mnt/<SUBMOUNT>`, even if the mount itself was specified as read-only.
+
+### Recursive read-only mounts
+
+{{< feature-state feature_gate_name="RecursiveReadOnlyMounts" >}}
+
+Recursive read-only mounts can be enabled by setting the
+`RecursiveReadOnlyMounts` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+for kubelet and kube-apiserver, and setting the `.spec.containers[].volumeMounts[].recursiveReadOnly`
+field for a pod.
+
+The allowed values are:
+
+* `Disabled` (default): no effect.
+
+* `Enabled`: makes the mount recursively read-only.
+  Needs all the following requirements to be satisfied:
+  * `readOnly` is set to `true`
+  * `mountPropagation` is unset, or, set to `None`
+  * The host is running with Linux kernel v5.12 or later
+  * The [CRI-level](/docs/concepts/architecture/cri) container runtime supports recursive read-only mounts
+  * The OCI-level container runtime supports recursive read-only mounts.
+  It will fail if any of these is not true.
+
+* `IfPossible`: attempts to apply `Enabled`, and falls back to `Disabled`
+  if the feature is not supported by the kernel or the runtime class.
+
+Example:
+{{% code_sample file="storage/rro.yaml" %}}
+
+When this property is recognized by kubelet and kube-apiserver,
+the `.status.containerStatuses[].volumeMounts[].recursiveReadOnly` field is set to either
+`Enabled` or `Disabled`.
+
+
+#### Implementations {#implementations-rro}
+
+{{% thirdparty-content %}}
+
+The following container runtimes are known to support recursive read-only mounts.
+
+CRI-level:
+- [containerd](https://containerd.io/), since v2.0
+
+OCI-level:
+- [runc](https://runc.io/), since v1.1
+- [crun](https://github.com/containers/crun), since v1.8.6
 
 ## {{% heading "whatsnext" %}}
 
diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/recursive-read-only-mounts.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/recursive-read-only-mounts.md
new file mode 100644
index 0000000000..3ecca217d9
--- /dev/null
+++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/recursive-read-only-mounts.md
@@ -0,0 +1,14 @@
+---
+title: RecursiveReadOnlyMounts
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.30"
+---
+Enables support for recursive read-only mounts.
+For more details, see [read-only mounts](/docs/concepts/storage/volumes/#read-only-mounts).
diff --git a/content/en/examples/storage/rro.yaml b/content/en/examples/storage/rro.yaml
new file mode 100644
index 0000000000..1ffc6b0389
--- /dev/null
+++ b/content/en/examples/storage/rro.yaml
@@ -0,0 +1,28 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: rro
+spec:
+  volumes:
+    - name: mnt
+      hostPath:
+        # tmpfs is mounted on /mnt/tmpfs
+        path: /mnt
+  containers:
+    - name: busybox
+      image: busybox
+      args: ["sleep", "infinity"]
+      volumeMounts:
+        # /mnt-rro/tmpfs is not writable
+        - name: mnt
+          mountPath: /mnt-rro
+          readOnly: true
+          mountPropagation: None
+          recursiveReadOnly: Enabled
+        # /mnt-ro/tmpfs is writable
+        - name: mnt
+          mountPath: /mnt-ro
+          readOnly: true
+        # /mnt-rw/tmpfs is writable
+        - name: mnt
+          mountPath: /mnt-rw