Working with Projected Volumes
1. Understanding Projected Volumes
Combine multiple volume sources (Secrets, ConfigMaps, downwardAPI, SA tokens) into a single directory.
| Source Type | Use |
|---|
| secret | Pick keys from Secret |
| configMap | Pick keys from ConfigMap |
| downwardAPI | Pod metadata as files |
| serviceAccountToken | Bound, audience-scoped token |
| clusterTrustBundle NEW | Cluster CA bundle (1.29+) |
2. Projecting Secrets
volumes:
- name: all
projected:
sources:
- secret:
name: tls
items:
- { key: tls.crt, path: certs/server.crt }
- { key: tls.key, path: certs/server.key, mode: 0400 }
3. Projecting ConfigMaps
- configMap:
name: app-config
items: [{ key: app.properties, path: config/app.properties }]
| Property | Detail |
|---|
| path | Relative file path inside volume |
| mode | Octal permissions |
4. Projecting Service Account Tokens
- serviceAccountToken:
audience: vault
expirationSeconds: 3600
path: vault/token
| Field | Effect |
|---|
| audience | Restrict token validity scope |
| expirationSeconds | Min 600; auto-rotated |
5. Projecting Downward API
- downwardAPI:
items:
- { path: meta/labels, fieldRef: { fieldPath: metadata.labels } }
- { path: meta/annotations, fieldRef: { fieldPath: metadata.annotations } }
- { path: meta/pod_name, fieldRef: { fieldPath: metadata.name } }
| fieldRef.fieldPath | Exposes |
|---|
metadata.name | Pod name |
metadata.namespace | Namespace |
metadata.uid | Pod UID |
status.podIP | Pod IP |
spec.nodeName | Scheduled node |
6. Configuring Token Expiration
| Setting | Detail |
|---|
| expirationSeconds | Token TTL (min 600) |
| Auto-refresh | kubelet rotates before expiry |
7. Setting Token Audience
| Audience | Use |
|---|
| api | Kubernetes API (default) |
| vault | HashiCorp Vault JWT auth |
| sts.amazonaws.com | AWS IRSA |
| custom.example.com | Custom OIDC RP |
8. Combining Multiple Sources
Example: All-in-one projected volume
volumes:
- name: app-meta
projected:
sources:
- configMap: { name: app-config }
- secret: { name: db-creds }
- downwardAPI:
items: [{ path: pod-name, fieldRef: { fieldPath: metadata.name } }]
- serviceAccountToken:
audience: vault
path: vault-token
| Rule | Detail |
|---|
| Path conflicts | Detected at pod admission |
| Sub-paths | Use path with sub-dirs |
9. Using Projected Volumes for mTLS
volumes:
- name: identity
projected:
sources:
- clusterTrustBundle: { name: cluster-ca, path: ca.crt }
- serviceAccountToken: { audience: spire, path: spire-token }
10. Debugging Projected Volumes
| Check | Command |
|---|
kubectl exec POD -- ls -lR /mnt/proj | Verify files present |
kubectl describe pod | Mount errors in events |
kubectl get cm/secret | Verify source objects exist |