From 4c296c6ad09affef1482063a8df7b5baecf7ba68 Mon Sep 17 00:00:00 2001
From: Aravindh Puthiyaparambil <aravindh@redhat.com>
Date: Thu, 4 Nov 2021 14:46:49 -0700
Subject: [PATCH] storage: document Windows projected volume limitations

xref: https://github.com/kubernetes/kubernetes/issues/102849
---
 .../concepts/storage/projected-volumes.md     | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/content/en/docs/concepts/storage/projected-volumes.md b/content/en/docs/concepts/storage/projected-volumes.md
index eda618e51c3e1..a5914adb6f945 100644
--- a/content/en/docs/concepts/storage/projected-volumes.md
+++ b/content/en/docs/concepts/storage/projected-volumes.md
@@ -68,3 +68,56 @@ of the projected volume.
 A container using a projected volume source as a [`subPath`](/docs/concepts/storage/volumes/#using-subpath)
 volume mount will not receive updates for those volume sources.
 {{< /note >}}
+
+## SecurityContext interactions
+
+The [proposal for file permission handling in projected service account volume](https://github.com/kubernetes/enhancements/pull/1598)
+enhancement introduced the projected files having the the correct owner
+permissions set.
+
+### Linux
+
+In Linux pods that have a projected volume and `RunAsUser` set in the Pod
+[`SecurityContext`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context),
+the projected files have the correct ownership set including container user
+ownership.
+
+### Windows
+
+In Windows pods that have a projected volume and `RunAsUsername` set in the
+Pod `SecurityContext`, the ownership is not enforced due to the way user
+accounts are managed in Windows. Windows stores and manages local user and group
+accounts in a database file called Security Account Manager (SAM). Each
+container maintains its own instance of the SAM database, to which the host has
+no visibility into while the container is running. Windows containers are
+designed to run the user mode portion of the OS in isolation from the host,
+hence the maintenance of a virtual SAM database. As a result, the kubelet running
+on the host does not have the ability to dynamically configure host file
+ownership for virtualized container accounts. It is recommended that if files on
+the host machine are to be shared with the container then they should be placed
+into their own volume mount outside of `C:\`.
+
+By default, the projected files will have the following ownership as shown for
+an example projected volume file:
+```powershell
+Path   : Microsoft.PowerShell.Core\FileSystem::C:\var\run\secrets\kubernetes.io\serviceaccount\..2021_08_31_22_22_18.318230061\ca.crt
+Owner  : BUILTIN\Administrators
+Group  : NT AUTHORITY\SYSTEM
+Access : NT AUTHORITY\SYSTEM Allow  FullControl
+         BUILTIN\Administrators Allow  FullControl
+         BUILTIN\Users Allow  ReadAndExecute, Synchronize
+Audit  :
+Sddl   : O:BAG:SYD:AI(A;ID;FA;;;SY)(A;ID;FA;;;BA)(A;ID;0x1200a9;;;BU)
+```
+This implies all administrator users like `ContainerAdministrator` will have
+read, write and execute access while, non-administrator users will have read and
+execute access.
+
+{{< note >}}
+In general, granting the container access to the host is discouraged as it can
+open the door for potential security exploits.
+
+Creating a Windows Pod with `RunAsUser` in it's `SecurityContext` will result in
+the Pod being stuck at `ContainerCreating` forever. So it is advised to not use
+the Linux only `RunAsUser` option with Windows Pods.
+{{< /note >}}