投射卷

本文档描述 Kubernetes 中的投射卷（Projected Volumes）。 建议先熟悉卷概念。

介绍

一个 projected 卷可以将若干现有的卷源映射到同一个目录之上。

目前，以下类型的卷源可以被投射：

所有的卷源都要求处于 Pod 所在的同一个名字空间内。更多详细信息， 可参考一体化卷设计文档。

带有 Secret、DownwardAPI 和 ConfigMap 的配置示例

pods/storage/projected-secret-downwardapi-configmap.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: volume-test
spec:
  containers:
  - name: container-test
    image: busybox:1.28
    command: ["sleep", "3600"]
    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

带有非默认权限模式设置的 Secret 的配置示例

pods/storage/projected-secrets-nondefault-permission-mode.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: volume-test
spec:
  containers:
  - name: container-test
    image: busybox:1.28
    command: ["sleep", "3600"]
    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

每个被投射的卷源都列举在规约中的 sources 下面。参数几乎相同，只有两个例外：

  • 对于 Secret，secretName 字段被改为 name 以便于 ConfigMap 的命名一致；
  • defaultMode 只能在投射层级设置，不能在卷源层级设置。不过，正如上面所展示的， 你可以显式地为每个投射单独设置 mode 属性。

serviceAccountToken 投射卷

你可以将当前服务账号的令牌注入到 Pod 中特定路径下。例如：

pods/storage/projected-service-account-token.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: sa-token-test
spec:
  containers:
  - name: container-test
    image: busybox:1.28
    command: ["sleep", "3600"]
    volumeMounts:
    - name: token-vol
      mountPath: "/service-account"
      readOnly: true
  serviceAccountName: default
  volumes:
  - name: token-vol
    projected:
      sources:
      - serviceAccountToken:
          audience: api
          expirationSeconds: 3600
          path: token

示例 Pod 中包含一个投射卷，其中包含注入的服务账号令牌。 此 Pod 中的容器可以使用该令牌访问 Kubernetes API 服务器， 使用 Pod 的 ServiceAccount 进行身份验证。audience 字段包含令牌所针对的受众。 收到令牌的主体必须使用令牌受众中所指定的某个标识符来标识自身，否则应该拒绝该令牌。 此字段是可选的，默认值为 API 服务器的标识。

字段 expirationSeconds 是服务账号令牌预期的生命期长度。默认值为 1 小时， 必须至少为 10 分钟（600 秒）。管理员也可以通过设置 API 服务器的命令行参数 --service-account-max-token-expiration 来为其设置最大值上限。 path 字段给出与投射卷挂载点之间的相对路径。

clusterTrustBundle 投射卷

特性状态： Kubernetes v1.33 [beta] (enabled by default: false)

clusterTrustBundle 投射卷源将一个或多个 ClusterTrustBundle 对象的内容作为一个自动更新的文件注入到容器文件系统中。

ClusterTrustBundle 可以通过名称 或签名者名称被选中。

要按名称选择，可以使用 name 字段指定单个 ClusterTrustBundle 对象。

要按签名者名称选择，可以使用 signerName 字段（也可选用 labelSelector 字段） 指定一组使用给定签名者名称的 ClusterTrustBundle 对象。 如果 labelSelector 不存在，则针对该签名者的所有 ClusterTrustBundles 将被选中。

kubelet 会对所选 ClusterTrustBundle 对象中的证书进行去重，规范化 PEM 表示（丢弃注释和头部）， 重新排序证书，并将这些证书写入由 path 指定的文件中。 随着所选 ClusterTrustBundles 的集合或其内容发生变化，kubelet 会保持更新此文件。

默认情况下，如果找不到指定的 ClusterTrustBundle，或者 signerName / labelSelector 与所有 ClusterTrustBundle 都不匹配，kubelet 将阻止 Pod 启动。如果这不是你想要的行为， 可以将 optional 字段设置为 true，Pod 将使用 path 处的空白文件启动。

pods/storage/projected-clustertrustbundle.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: sa-ctb-name-test
spec:
  containers:
  - name: container-test
    image: busybox
    command: ["sleep", "3600"]
    volumeMounts:
    - name: token-vol
      mountPath: "/root-certificates"
      readOnly: true
  serviceAccountName: default
  volumes:
  - name: token-vol
    projected:
      sources:
      - clusterTrustBundle:
          name: example
          path: example-roots.pem
      - clusterTrustBundle:
          signerName: "example.com/mysigner"
          labelSelector:
            matchLabels:
              version: live
          path: mysigner-roots.pem
          optional: true

podCertificate 投射卷

特性状态： Kubernetes v1.34 [alpha] (enabled by default: false)

podCertificate 投射卷源为 Pod 安全地提供一个私钥和 X.509 证书链，用作客户端或服务器凭据。 当私钥和证书链接近过期时，kubelet 将处理刷新它们。应用程序只需确保在文件发生变化时， 及时通过类似 inotify 或轮询的机制重新加载文件。

每个 podCertificate 投射支持以下配置字段：

  • signerName：你希望签发证书的 签名者。 注意，签名者可能有自己的访问要求，并可能拒绝为你的 Pod 签发证书。
  • keyType：应生成的私钥类型。有效值为 ED25519、ECDSAP256、ECDSAP384、ECDSAP521、RSA3072 和 RSA4096。
  • maxExpirationSeconds：你将接受的颁发给 Pod 的证书的最大生命周期。 如果未设置，默认为 86400（24 小时）。必须至少为 3600（1 小时），最多为 7862400（91 天）。 Kubernetes 内置签名者的最大生命周期限制为 86400（1 天）。签名者允许颁发比指定时间更短生命周期的证书。
  • credentialBundlePath：投射内凭证包应写入的相对路径。凭证包是一个 PEM 格式的文件， 其中第一个块是包含 PKCS#8 序列化私钥的 "PRIVATE KEY" 块，其余块是组成证书链（叶证书和任何中间证书）的 "CERTIFICATE" 块。
  • keyPath 和 certificateChainPath：kubelet 应单独写入仅私钥或证书链的路径。
pods/storage/projected-podcertificate.yaml 
# Sample Pod spec that uses a podCertificate projection to request an ED25519
# private key, a certificate from the `coolcert.example.com/foo` signer, and
# write the results to `/var/run/my-x509-credentials/credentialbundle.pem`.
apiVersion: v1
kind: Pod
metadata:
  namespace: default
  name: podcertificate-pod
spec:
  serviceAccountName: default
  containers:
  - image: debian
    name: main
    command: ["sleep", "infinity"]
    volumeMounts:
    - name: my-x509-credentials
      mountPath: /var/run/my-x509-credentials
  volumes:
  - name: my-x509-credentials
    projected:
      defaultMode: 420
      sources:
      - podCertificate:
          keyType: ED25519
          signerName: coolcert.example.com/foo
          credentialBundlePath: credentialbundle.pem

与 SecurityContext 间的关系

关于在投射的服务账号卷中处理文件访问权限的提案 介绍了如何使得所投射的文件具有合适的属主访问权限。

Linux

在包含了投射卷并在 SecurityContext 中设置了 RunAsUser 属性的 Linux Pod 中，投射文件具有正确的属主属性设置， 其中包含了容器用户属主。

当 Pod 中的所有容器在其 PodSecurityContext 或容器 SecurityContext 中设置了相同的 runAsUser 时，kubelet 将确保 serviceAccountToken 卷的内容归该用户所有，并且令牌文件的权限模式会被设置为 0600。

Windows

在包含了投射卷并在 SecurityContext 中设置了 RunAsUsername 的 Windows Pod 中, 由于 Windows 中用户账号的管理方式问题，文件的属主无法正确设置。 Windows 在名为安全账号管理器（Security Account Manager，SAM） 的数据库中保存本地用户和组信息。每个容器会维护其自身的 SAM 数据库实例， 宿主系统无法窥视到容器运行期间数据库内容。Windows 容器被设计用来运行操作系统的用户态部分， 与宿主系统之间隔离，因此维护了一个虚拟的 SAM 数据库。 所以，在宿主系统上运行的 kubelet 无法动态为虚拟的容器账号配置宿主文件的属主。 如果需要将宿主机器上的文件与容器共享，建议将它们放到挂载于 C:\ 之外的独立卷中。

默认情况下，所投射的文件会具有如下例所示的属主属性设置：

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)

这意味着，所有类似 ContainerAdministrator 的管理员用户都具有读、写和执行访问权限， 而非管理员用户将具有读和执行访问权限。

最后修改 August 28, 2025 at 9:07 AM PST: [zh-cn]sync projected-podcertificate.yaml (3fdfb16a7b)