Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 22. Projected Volumes

22.1. Overview
Copy link

A projected volume maps several existing volume sources into the same directory.

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

Note

All sources are required to be in the same namespace as the pod.

Projected volumes can map any combination of these volume sources into a single directory, allowing the user to:

  • automatically populate a single volume with the keys from multiple secrets, configmaps, and with downward API information, so that I can synthesize a single directory with various sources of information;
  • populate a single volume with the keys from multiple secrets, configmaps, and with downward API information, explicitly specifying paths for each item, so that I can have full control over the contents of that volume.

22.2. Example Scenarios
Copy link

The following general scenarios show how you can use projected volumes.

  • ConfigMap, Secrets, Downward API. Projected volumes allow you to to deploy containers with configuration data that includes passwords. An application using these resources could be deploying OpenStack on Kubernetes. The configuration data may need to be assembled differently depending on if the services are going to be used for production or for testing. If a pod is labeled with production or testing, the downward API selector metadata.labels can be used to produce the correct OpenStack configs.
  • ConfigMap + Secrets. Projected volumes allow you to deploy containers involving configuration data and passwords. For example, you might execute an Ansible playbook stored as a configmap, with some sensitive encrypted tasks that are decrypted using a vault password file.
  • ConfigMap + Downward API. Projected volumes allow you to generate a config including the pod name (available via the metadata.name selector). This application can then pass the pod name along with requests in order to easily determine the source without using IP tracking.
  • Secrets + Downward API. Projected volumes allow you to use a secret as a public key to encrypt the namespace of the pod (available via the metadata.namespace selector). This example allows the operator to use the application to deliver the namespace information securely without using an encrypted transport.

22.3. Example Pod Specifications
Copy link

The following are examples of pod specifications for creating projected volumes.

Example 22.1. Pod with a secret, a downward API, and a configmap

apiVersion: v1
kind: Pod
metadata:
  name: volume-test
spec:
  containers:
  - name: container-test
    image: busybox
    volumeMounts:
1 

    - name: all-in-one
      mountPath: "/projected-volume"
2 

      readOnly: true
3 

  volumes:
4 

  - name: all-in-one
5 

    projected:
      defaultMode: 0400
6 

      sources:
      - secret:
          name: mysecret
7 

          items:
            - key: username
              path: my-group/my-username
8 

      - downwardAPI:
9 

          items:
            - path: "labels"
              fieldRef:
                fieldPath: metadata.labels
            - path: "cpu_limit"
              resourceFieldRef:
                containerName: container-test
                resource: limits.cpu
      - configMap:
10 

          name: myconfigmap
          items:
            - key: config
              path: my-group/my-config
              mode: 0777
11
Copy to Clipboard Toggle word wrap
1
Add a volumeMounts section for each container that needs the secret.
2
Specify a path to an unused directory where the secret will appear.
3
Set readOnly to true.
4
Add a volumes block to list each projected volume source.
5
Specify any name for the volume.
6
Set the execute permission on the files.
7
Add a secret. Enter the name of the secret object. Each secret you want to use must be listed.
8
Specify the path to the secrets file under the mountPath. Here, the secrets file is in /projected-volume/my-group/my-config.
9
Add a Downward API source.
10
Add a ConfigMap source.
11
Set the mode for the specific projection
Note

If there are multiple containers in the pod, each container needs a volumeMounts section, but only one volumes section is needed.

Example 22.2. Pod with multiple secrets with a non-default permission mode set

apiVersion: v1
kind: Pod
metadata:
  name: volume-test
spec:
  containers:
  - name: container-test
    image: busybox
    volumeMounts:
    - name: all-in-one
      mountPath: "/projected-volume"
      readOnly: true
  volumes:
  - name: all-in-one
    projected:
      defaultMode: 0755
      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
Copy to Clipboard Toggle word wrap
Note

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.

22.4. Pathing Considerations
Copy link

When creating projected volumes, consider the following situations related to the volume file paths.

Collisions Between Keys when Configured Paths are Identical

If you configure any keys with the same path, the pod spec will not be accepted as valid. In the following example, the specified path for mysecret and myconfigmap are the same: 

apiVersion: v1
kind: Pod
metadata:
  name: volume-test
spec:
  containers:
  - name: container-test
    image: busybox
    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/data
      - configMap:
          name: myconfigmap
          items:
            - key: config
              path: my-group/data
Copy to Clipboard Toggle word wrap
Collisions Between Keys without Configured Paths
The only run-time validation that can occur is when all the paths are known at pod creation, similar to the above scenario. Otherwise, when a conflict occurs the most recent specified resource will overwrite anything preceding it (this is true for resources that are updated after pod creation as well).
Collisions when One Path is Explicit and the Other is Automatically Projected
In the event that there is a collision due to a user specified path matching data that is automatically projected, the latter resource will overwrite anything preceding it as before

22.5. Configuring a Projected Volume for a Pod
Copy link

The following example shows how to use a projected volume to mount an existing Secret volume source.

The steps can be used to create a user name and password Secrets from local files. You then create a pod that runs one container, using a projected volume to mount the Secrets into the same shared directory.

  1. Create files containing the secrets:

    For example: 

    $ nano secret.yaml
    Copy to Clipboard Toggle word wrap

    Enter the following, replacing the password and user information as appropriate: 

    apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  pass: MWYyZDFlMmU2N2Rm
  user: YWRtaW4=
    Copy to Clipboard Toggle word wrap

    The user and pass values can be any valid string that is base64 encoded. The examples used here are base64 encoded values user: admin, pass:1f2d1e2e67df. 

    $ echo -n "admin" | base64
YWRtaW4=
$ echo -n "1f2d1e2e67df" | base64
MWYyZDFlMmU2N2Rm
    Copy to Clipboard Toggle word wrap

  2. Use the following command to create the secrets: 

    $ oc create -f <secrets-filename>
    Copy to Clipboard Toggle word wrap

    For example: 

    $ oc create -f secret.yaml
secret "mysecret" created
    Copy to Clipboard Toggle word wrap

  3. You can check that the secret was created using the following commands: 

    $ oc get secret <secret-name>
$ oc get secret <secret-name> -o yaml
    Copy to Clipboard Toggle word wrap

    For example: 

    $ oc get secret mysecret
NAME       TYPE      DATA      AGE
mysecret   Opaque    2         17h
    Copy to Clipboard Toggle word wrap 
    oc get secret mysecret -o yaml
apiVersion: v1
data:
  pass: MWYyZDFlMmU2N2Rm
  user: YWRtaW4=
kind: Secret
metadata:
  creationTimestamp: 2017-05-30T20:21:38Z
  name: mysecret
  namespace: default
  resourceVersion: "2107"
  selfLink: /api/v1/namespaces/default/secrets/mysecret
  uid: 959e0424-4575-11e7-9f97-fa163e4bd54c
type: Opaque
    Copy to Clipboard Toggle word wrap

  4. Create a pod configuration file similar to the following that includes a volumes section: 

    apiVersion: v1
kind: Pod
metadata:
  name: test-projected-volume
spec:
  containers:
  - name: test-projected-volume
    image: busybox
    args:
    - sleep
    - "86400"
    volumeMounts:
    - name: all-in-one
      mountPath: "/projected-volume"
      readOnly: true
  volumes:
  - name: all-in-one
    projected:
      sources:
      - secret:
          name: user
      - secret:
          name: pass
    Copy to Clipboard Toggle word wrap

  5. Create the pod from the configuration file: 

    $ oc create -f <your_yaml_file>.yaml
    Copy to Clipboard Toggle word wrap

    For example: 

    $ oc create -f secret-pod.yaml
pod "test-projected-volume" created
    Copy to Clipboard Toggle word wrap

  6. Verify that the pod container is running, and then watch for changes to the Pod: 

    $ oc get pod <name>
    Copy to Clipboard Toggle word wrap

    The output should appear similar to the following: 

    $ oc get pod test-projected-volume
NAME                    READY     STATUS    RESTARTS   AGE
test-projected-volume   1/1       Running   0          14s
    Copy to Clipboard Toggle word wrap

  7. In another terminal, use the oc exec command to open a shell to the running container: 

    $ oc exec -it <pod> <command>
    Copy to Clipboard Toggle word wrap

    For example: 

    $ oc exec -it test-projected-volume -- /bin/sh
    Copy to Clipboard Toggle word wrap

  8. In your shell, verify that the projected-volumes directory contains your projected sources: 

    / # ls
bin               home              root              tmp
dev               proc              run               usr
etc               projected-volume  sys               var
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat