Using volumes to persist container data¶

You can use volumes to persist the data used by the containers in a pod. A volume is directory, accessible to the containers in a pod, where data is stored for the life of the pod.

Files in a container are ephemeral. As such, when a container crashes or stops, the data is lost.

Understanding volumes¶

You can provide persistent or temporary storage for your applications by mounting volumes to pods and containers. Using volumes ensures that data remains available even if a container restarts by backing the file system with host-local or network-attached storage.

Volumes are mounted file systems available to pods and their containers which may be backed by a number of host-local or network attached storage endpoints. Containers are not persistent by default; on restart, their contents are cleared.

To ensure that the file system on the volume contains no errors and, if errors are present, to repair them when possible, OpenShift Container Platform invokes the fsck utility prior to the mount utility. This occurs when either adding a volume or updating an existing volume.

The simplest volume type is emptyDir, which is a temporary directory on a single machine. Administrators may also allow you to request a persistent volume that is automatically attached to your pods.

Working with volumes using the OpenShift Container Platform CLI¶

You can use the CLI command oc set volume to add and remove volumes and volume mounts for any object that has a pod template like replication controllers or deployment configs. You can also list volumes in pods or any object that has a pod template.

The oc set volume command uses the following general syntax:

$ oc set volume <object_selection> <operation> <mandatory_parameters> <options>

Object selection

Specify one of the following for the object_selection parameter in the oc set volume command:

Object Selection

Operation

Specify --add or --remove for the operation parameter in the oc set volume command.

Mandatory parameters

Any mandatory parameters are specific to the selected operation and are discussed in later sections.

Options

Any options are specific to the selected operation and are discussed in later sections.

About listing volumes and volume mounts in a pod¶

You can list volumes and volume mounts in pods or pod templates.

You can list volumes by running the following command:

$ oc set volume <object_type>/<name> [options]

List volume supported options:

For example:

• To list all volumes for pod p1:
  terminal

  $ oc set volume pod/p1

• To list volume v1 defined on all deployment configs:
  terminal

  $ oc set volume dc --all --name=v1

About adding volumes to a pod¶

You can add volumes and volume mounts to a pod. Volumes persist the data used by the containers, even if container crashes or stops.

You can add a volume, a volume mount, or both to pod templates by running the following command:

$ oc set volume <object_type>/<name> --add [options]

Supported Options for Adding Volumes

For example:

• To add a new volume source emptyDir to the registry DeploymentConfig object:
  terminal

  $ oc set volume dc/registry --add

  Tip

  You can alternatively apply the following YAML to add the volume:

  Sample deployment config with an added volume

  yaml

  kind: DeploymentConfig
  apiVersion: apps.openshift.io/v1
  metadata:
    name: registry
    namespace: registry
  spec:
    replicas: 3
    selector:
      app: httpd
    template:
      metadata:
        labels:
          app: httpd
      spec:
        volumes:
          - name: volume-pppsw
            emptyDir: {}
        containers:
          - name: httpd
            image: >-
              image-registry.openshift-image-registry.svc:5000/openshift/httpd:latest
            ports:
              - containerPort: 8080
                protocol: TCP

  where:

  spec.template.spec.volumes

  Specifies the volume source emptyDir.

• To add volume v1 with secret secret1 for replication controller r1 and mount inside the containers at /data:
  terminal

  $ oc set volume rc/r1 --add --name=v1 --type=secret --secret-name='secret1' --mount-path=/data

  Tip

  You can alternatively apply the following YAML to add the volume:

  Sample replication controller with added volume and secret

  yaml

  kind: ReplicationController
  apiVersion: v1
  metadata:
    name: example-1
    namespace: example
  spec:
    replicas: 0
    selector:
      app: httpd
      deployment: example-1
      deploymentconfig: example
    template:
      metadata:
        creationTimestamp: null
        labels:
          app: httpd
          deployment: example-1
          deploymentconfig: example
      spec:
        volumes:
          - name: v1
            secret:
              secretName: secret1
              defaultMode: 420
        containers:
          - name: httpd
            image: >-
              image-registry.openshift-image-registry.svc:5000/openshift/httpd:latest
            volumeMounts:
              - name: v1
                mountPath: /data

  where:

  spec.template.spec.volumes

  Specifies the volume and secret.

  spec.template.spec.containers.volumeMounts

  Specifies the container mount path.

• To add existing persistent volume v1 with claim name pvc1 to deployment configuration dc.json on disk, mount the volume on container c1 at /data, and update the DeploymentConfig object on the server:
  terminal

  $ oc set volume -f dc.json --add --name=v1 --type=persistentVolumeClaim \
    --claim-name=pvc1 --mount-path=/data --containers=c1

  Tip

  You can alternatively apply the following YAML to add the volume:

  Sample deployment config with persistent volume added

  yaml

  kind: DeploymentConfig
  apiVersion: apps.openshift.io/v1
  metadata:
    name: example
    namespace: example
  spec:
    replicas: 3
    selector:
      app: httpd
    template:
      metadata:
        labels:
          app: httpd
      spec:
        volumes:
          - name: volume-pppsw
            emptyDir: {}
          - name: v1
            persistentVolumeClaim:
              claimName: pvc1
        containers:
          - name: httpd
            image: >-
              image-registry.openshift-image-registry.svc:5000/openshift/httpd:latest
            ports:
              - containerPort: 8080
                protocol: TCP
            volumeMounts:
              - name: v1
                mountPath: /data

  where:

  spec.template.spec.volumes.name.v1

  Specifies the persistent volume claim named pvc1.

  spec.template.spec.containers.volumeMounts

  Specifies the container mount path.

• To add a volume v1 based on Git repository $https://github.com/namespace1/project1$ with revision 5125c45f9f563 for all replication controllers:
  terminal

  $ oc set volume rc --all --add --name=v1 \
    --source='{"gitRepo": {
                  "repository": "https://github.com/namespace1/project1",
                  "revision": "5125c45f9f563"
              }}'

About updating volumes and volume mounts in a pod¶

You can modify the volumes and volume mounts in a pod.

You can update existing volumes by using the --overwrite option:

$ oc set volume <object_type>/<name> --add --overwrite [options]

For example:

• To replace existing volume v1 for replication controller r1 with existing persistent volume claim pvc1:
  terminal

  $ oc set volume rc/r1 --add --overwrite --name=v1 --type=persistentVolumeClaim --claim-name=pvc1

  Tip

  You can alternatively apply the following YAML to replace the volume:

  Sample replication controller with persistent volume claim named `pvc1`

  yaml

  kind: ReplicationController
  apiVersion: v1
  metadata:
    name: example-1
    namespace: example
  spec:
    replicas: 0
    selector:
      app: httpd
      deployment: example-1
      deploymentconfig: example
    template:
      metadata:
        labels:
          app: httpd
          deployment: example-1
          deploymentconfig: example
      spec:
        volumes:
          - name: v1
            persistentVolumeClaim:
              claimName: pvc1
        containers:
          - name: httpd
            image: >-
              image-registry.openshift-image-registry.svc:5000/openshift/httpd:latest
            ports:
              - containerPort: 8080
                protocol: TCP
            volumeMounts:
              - name: v1
                mountPath: /data

  The spec.template.spec.volumes stanza sets the persistent volume claim to pvc1.

• To change the DeploymentConfig object d1 mount point to /opt for volume v1:
  terminal

  $ oc set volume dc/d1 --add --overwrite --name=v1 --mount-path=/opt

  Tip

  You can alternatively apply the following YAML to change the mount point:

  Sample deployment config with mount point set to `opt`.

  yaml

  kind: DeploymentConfig
  apiVersion: apps.openshift.io/v1
  metadata:
    name: example
    namespace: example
  spec:
    replicas: 3
    selector:
      app: httpd
    template:
      metadata:
        labels:
          app: httpd
      spec:
        volumes:
          - name: volume-pppsw
            emptyDir: {}
          - name: v2
            persistentVolumeClaim:
              claimName: pvc1
          - name: v1
            persistentVolumeClaim:
              claimName: pvc1
        containers:
          - name: httpd
            image: >-
              image-registry.openshift-image-registry.svc:5000/openshift/httpd:latest
            ports:
              - containerPort: 8080
                protocol: TCP
            volumeMounts:
              - name: v1
                mountPath: /opt

  The spec.template.spec.containers.volumeMounts stanza sets the mount point to /opt.

About removing volumes and volume mounts from a pod¶

You can remove a volume or volume mount from a pod.

You can remove a volume from a pod template by running the following command:

$ oc set volume <object_type>/<name> --remove [options]

Supported options for removing volumes

For example:

• To remove a volume v1 from the DeploymentConfig object d1:
  terminal

  $ oc set volume dc/d1 --remove --name=v1

• To unmount volume v1 from container c1 for the DeploymentConfig object d1 and remove the volume v1 if it is not referenced by any containers on d1:
  terminal

  $ oc set volume dc/d1 --remove --name=v1 --containers=c1

• To remove all volumes for replication controller r1:
  terminal

  $ oc set volume rc/r1 --remove --confirm

Configuring volumes for multiple uses in a pod¶

You can configure a volume to share one volume for multiple uses in a single pod by using the volumeMounts.subPath property to specify a subPath value inside a volume instead of the volume’s root.

Procedure

1. To view the list of files in the volume, run the oc rsh command:
   terminal

   $ oc rsh <pod>

   Example output

   sh-4.2$ ls /path/to/volume/subpath/mount
   example_file1 example_file2 example_file3

2. Specify the subPath:
   Example Pod spec with subPath parameter

   apiVersion: v1
   kind: Pod
   metadata:
     name: my-site
   spec:
       securityContext:
         runAsNonRoot: true
         seccompProfile:
           type: RuntimeDefault
       containers:
       - name: mysql
         image: mysql
         volumeMounts:
         - mountPath: /var/lib/mysql
           name: site-data
           subPath: mysql
         securityContext:
           allowPrivilegeEscalation: false
           capabilities:
             drop: [ALL]
       - name: php
         image: php
         volumeMounts:
         - mountPath: /var/www/html
           name: site-data
           subPath: html
         securityContext:
           allowPrivilegeEscalation: false
           capabilities:
             drop: [ALL]
       volumes:
       - name: site-data
         persistentVolumeClaim:
           claimName: my-site-data

   where:

   spec.containers.volumeMounts.subPath.mysql

   Specifies that databases are stored in the mysql folder.

   spec.containers.volumeMounts.subPath.html

   Specifies that HTML content is stored in the html folder.