Persistent Volumes – Kubernetes

This document describes the projected volumes in Kubernetes. Familiarity with volumes is suggested.


A projected volume maps multiple existing

volume sources in the same directory.

Currently, the following types of volume sources can be projected:

  • secret
  • downwardAPI
  • configMap
  • serviceAccountToken

All sources must be in the same namespace as the Pod. For more information, see the All-in-One Volume Design document.

Example configuration with a secret, a

top-down API, and a configMap Example configuration

: secrets with a non-default permission mode set

Each projected volume source appears in the specification under sources. The parameters are almost the same with two exceptions:

  • For secrets, the secretName field has been changed to name to be consistent with the ConfigMap naming
  • .

  • The defaultMode can only be specified at the projected level and not for each volume source. However, as illustrated above, you can explicitly set the mode for each individual projection.

serviceAccountProjected Token Volumes

You can insert the token for the current service account into a Pod at a specified path. For example:

The example Pod has a projected volume that contains the injected service account token. Containers in this Pod can use that token to access the Kubernetes API server, authenticating with the pod’s ServiceAccount identity. The audience field contains the intended audience of the token. A token recipient must identify themselves with an identifier specified in the token audience, and otherwise must reject the token. This field is optional and the default value is the API server ID.

ExpirationSeconds is the expected duration of validity of the service account token. The default value is 1 hour and must be at least 10 minutes (600 seconds). An administrator can also limit its maximum value by specifying the -service-account-max-token-expiration option for the API server. The path field specifies a path relative to the mount point of the projected volume.

SecurityContext interactions

The proposal for file permission control in the projected service account volume enhancement introduced

projected files with the correct owner permission set. Linux In Linux pods that have a projected volume and RunAsUser set to Pod SecurityContext, the projected files have the correct property set.

including the user’s ownership of the container.

When all containers in a pod have the same runAsUser set to their PodSecurityContext or SecurityContext container, the kubelet ensures that the contents of the serviceAccountToken volume are owned by that user and that the token file has its permission mode set to 0600.


On Windows pods that have a projected volume and RunAsUsername set to Pod SecurityContext, the property is not applied because of the way user accounts are managed in Windows. Windows stores and manages local user and group accounts in a database file named Security Accounts Manager (SAM). Each container maintains its own instance of the SAM database, which the host has no visibility into while the container is running. Windows containers are designed to run the user-mode portion of the operating system in isolation from the host, hence maintaining 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, they should be placed on their own volume mount outside of C:\.

By default, projected files will have

the following property, as shown in a sample projected volume file:

This means that all administrator users, such as ContainerAdministrator, will have read, write, and execute access, while non-administrators will have read/execute access.