Projected Volumes

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

Introduction

A 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

pods/storage/projected-secret-downwardapi-configmap.yaml Projected Volumes - 图1

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4.   name: volume-test
  5. spec:
  6.   containers:
  7.   - name: container-test
  8.     image: busybox:1.28
  9.     volumeMounts:
  10.     - name: all-in-one
  11.       mountPath: "/projected-volume"
  12.       readOnly: true
  13.   volumes:
  14.   - name: all-in-one
  15.     projected:
  16.       sources:
  17.       - secret:
  18.           name: mysecret
  19.           items:
  20.             - key: username
  21.               path: my-group/my-username
  22.       - downwardAPI:
  23.           items:
  24.             - path: "labels"
  25.               fieldRef:
  26.                 fieldPath: metadata.labels
  27.             - path: "cpu_limit"
  28.               resourceFieldRef:
  29.                 containerName: container-test
  30.                 resource: limits.cpu
  31.       - configMap:
  32.           name: myconfigmap
  33.           items:
  34.             - key: config
  35.               path: my-group/my-config

Example configuration: secrets with a non-default permission mode set

pods/storage/projected-secrets-nondefault-permission-mode.yaml Projected Volumes - 图2

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4.   name: volume-test
  5. spec:
  6.   containers:
  7.   - name: container-test
  8.     image: busybox:1.28
  9.     volumeMounts:
  10.     - name: all-in-one
  11.       mountPath: "/projected-volume"
  12.       readOnly: true
  13.   volumes:
  14.   - name: all-in-one
  15.     projected:
  16.       sources:
  17.       - secret:
  18.           name: mysecret
  19.           items:
  20.             - key: username
  21.               path: my-group/my-username
  22.       - secret:
  23.           name: mysecret2
  24.           items:
  25.             - key: password
  26.               path: my-group/my-password
  27.               mode: 511

Each projected volume source is listed in the spec under sources. The parameters are nearly the same with two exceptions:

  • For secrets, the secretName field has been changed to name to be consistent with 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.

serviceAccountToken projected volumes

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

pods/storage/projected-service-account-token.yaml Projected Volumes - 图3

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4.   name: sa-token-test
  5. spec:
  6.   containers:
  7.   - name: container-test
  8.     image: busybox:1.28
  9.     volumeMounts:
  10.     - name: token-vol
  11.       mountPath: "/service-account"
  12.       readOnly: true
  13.   serviceAccountName: default
  14.   volumes:
  15.   - name: token-vol
  16.     projected:
  17.       sources:
  18.       - serviceAccountToken:
  19.           audience: api
  20.           expirationSeconds: 3600
  21.           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. The 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.

The 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 --service-account-max-token-expiration option for the API server. The path field specifies a relative path to the mount point of the projected volume.

Note: A container using a projected volume source as a subPath volume mount will not receive updates for those volume sources.

SecurityContext interactions

The proposal for file permission handling in projected service account volume enhancement introduced the projected files having the correct owner permissions set.

Linux

In Linux pods that have a projected volume and RunAsUser set in the Pod SecurityContext, the projected files have the correct ownership set including container user ownership.

When all containers in a pod have the same runAsUser set in their PodSecurityContext or container SecurityContext, 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 0600.

Note:

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 0600 because all other containers in the Pod have the same runAsUser, ephemeral containers must use the same runAsUser to be able to read the token.

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:

  1. PS C:\> Get-Acl C:\var\run\secrets\kubernetes.io\serviceaccount\..2021_08_31_22_22_18.318230061\ca.crt | Format-List
  3. Path   : Microsoft.PowerShell.Core\FileSystem::C:\var\run\secrets\kubernetes.io\serviceaccount\..2021_08_31_22_22_18.318230061\ca.crt
  4. Owner  : BUILTIN\Administrators
  5. Group  : NT AUTHORITY\SYSTEM
  6. Access : NT AUTHORITY\SYSTEM Allow  FullControl
  7.          BUILTIN\Administrators Allow  FullControl
  8.          BUILTIN\Users Allow  ReadAndExecute, Synchronize
  9. Audit  :
  10. 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.