This document describes projected volumes in Kubernetes. Familiarity with volumes is suggested.
projected volume maps several existing volume sources into the same directory.
Currently, the following types of volume sources can be projected:
All sources are required to be in the same namespace as the Pod. For more details, see the all-in-one volume design document.
Example configuration with a secret, a downwardAPI, and a configMap
apiVersion: v1 kind: Pod metadata: name: volume-test spec: containers: - name: container-test image: busybox:1.28 volumeMounts: - name: all-in-one mountPath: "/projected-volume" readOnly: true volumes: - name: all-in-one projected: sources: - secret: name: mysecret items: - key: username path: my-group/my-username - downwardAPI: items: - path: "labels" fieldRef: fieldPath: metadata.labels - path: "cpu_limit" resourceFieldRef: containerName: container-test resource: limits.cpu - configMap: name: myconfigmap items: - key: config path: my-group/my-config
Example configuration: secrets with a non-default permission mode set
apiVersion: v1 kind: Pod metadata: name: volume-test spec: containers: - name: container-test image: busybox:1.28 volumeMounts: - name: all-in-one mountPath: "/projected-volume" readOnly: true volumes: - name: all-in-one projected: sources: - secret: name: mysecret items: - key: username path: my-group/my-username - secret: name: mysecret2 items: - key: password path: my-group/my-password mode: 511
Each projected volume source is listed in the spec under
parameters are nearly the same with two exceptions:
- For secrets, the
secretNamefield has been changed to
nameto be consistent with ConfigMap naming.
defaultModecan only be specified at the projected level and not for each volume source. However, as illustrated above, you can explicitly set the
modefor each individual projection.
serviceAccountToken projected volumes
You can inject the token for the current service account into a Pod at a specified path. For example:
apiVersion: v1 kind: Pod metadata: name: sa-token-test spec: containers: - name: container-test image: busybox:1.28 volumeMounts: - name: token-vol mountPath: "/service-account" readOnly: true serviceAccountName: default volumes: - name: token-vol projected: sources: - serviceAccountToken: audience: api expirationSeconds: 3600 path: token
The example Pod has a projected volume containing the injected service account
token. Containers in this Pod can use that token to access the Kubernetes API
server, authenticating with the identity of the pod's ServiceAccount.
audience field contains the intended audience of the
token. A recipient of the token must identify itself with an identifier specified
in the audience of the token, and otherwise should reject the token. This field
is optional and it defaults to the identifier of the API server.
expirationSeconds is the expected duration of validity of the service account
token. It defaults to 1 hour and must be at least 10 minutes (600 seconds). An administrator
can also limit its maximum value by specifying the
option for the API server. The
path field specifies a relative path to the mount point
of the projected volume.
subPathvolume mount will not receive updates for those volume sources.
The proposal for file permission handling in projected service account volume enhancement introduced the projected files having the correct owner permissions set.
In Linux pods that have a projected volume and
RunAsUser set in the Pod
the projected files have the correct ownership set including container user
When all containers in a pod have the same
runAsUser set in their
then the kubelet ensures that the contents of the
serviceAccountToken volume are owned by that user,
and the token file has its permission mode set to
Ephemeral containers added to a Pod after it is created do not change volume permissions that were set when the pod was created.
If a Pod's
serviceAccountToken volume permissions were set to
all other containers in the Pod have the same
containers must use the same
runAsUser to be able to read the token.
In Windows pods that have a projected volume and
RunAsUsername set in the
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
By default, the projected files will have the following ownership as shown for an example projected volume file:
PS C:\> Get-Acl C:\var\run\secrets\kubernetes.io\serviceaccount\..2021_08_31_22_22_18.318230061\ca.crt | Format-List 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
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.