Using an External File System (Volume Services)

This topic describes how Cloud Foundry (CF) app developers can read and write to a mounted filesystem from their apps. In CF, a volume service provides a volume so your app can read and/or write to a reliable, non-ephemeral file system.

Prerequisite

Before you can use a volume service with your app, your CF operator must add a volume service to your deployment.

You can run cf marketplace from the Cloud Foundry Command Line Interface (cf CLI) to see if any volume services are available. See the following example output of the NFS volume service:

$ cf marketplace
service   plans      description
nfs       Existing   Service for connecting to NFS volumes

If there is no volume service that fits your requirements, contact your CF operator.

Create and Bind a Service Instance

To use a volume service deployed by your operator, you must first create an instance of the specific volume service that you need:

  1. Create a service instance by running the following command and replacing the indicated values:

    $ cf create-service SERVICE-NAME PLAN SERVICE_INSTANCE -c SHARE-JSON

    • SERVICE: The name of the volume service that you want to use.
    • PLAN: The name of the service plan. Service plans are a way for providers to offer varying levels of resources or features for the same service.
    • SERVICE_INSTANCE: A name you provide for your service instance. Use any series of alpha-numeric characters, hyphens, and underscores. You can rename the instance at any time.
    • SHARE JSON (NFS Only): If you create an instance of the NFS volume service, you must supply an extra parameter, share, by using the -c flag and a JSON. This parameter forwards information to the broker about the NFS server and share required for the service. See the following example:
      cf create-service nfs Existing nfs_service_instance -c '{"share": "10.10.10.10/export/myshare"}'
  2. Bind your service instance to an app by running the following command and replacing the indicated values:

    $ cf bind-service YOUR-APP SERVICE-NAME -c GID_AND_UID_JSON

    • YOUR-APP: The name of the CF app for which you want to use the volume service.
    • SERVICE-NAME: The name of the volume service instance you created in the previous step.
    • GID_AND_UID_JSON (NFS only): If you bind an instance of the NFS volume service, you must supply two extra parameters, gid and uid. You can specify these parameters with the -c flag and a JSON. This parameter specifies the gid and uid to use when mounting the share to the app. See the following example:
      cf bind-service my-app nfs_service_instance -c '{"uid":"1000","gid":"1000"}'.
  3. Complete the service binding by restaging your app:

    $ cf restage YOUR-APP

Access the Volume Service from your App

To access the volume service from your app, you must know which file path to use in your code. You can view the file path in the details of the service binding, which are available from the VCAP_SERVICES environment variable. Follow the steps below.

  1. Run the cf env command to view environment variables for your app:

    $ cf env YOUR-APP
    "VCAP_SERVICES": {
    "nfs": [
    {
     "credentials": {},
     "label": "nfs",
     "name": "nfs_service_instance",
     "plan": "Existing",
     "provider": null,
     "syslog_drain_url": null,
     "tags": [
      "nfs"
     ],
     "volume_mounts": [
      {
       "container_dir": "/var/vcap/data/153e3c4b-1151-4cf7-b311-948dd77fce64",
       "device_type": "shared",
       "mode": "rw"
      }
     ]
    }
    ]
    }
    

  2. Use the properties under volume_mounts for any information your app needs. Refer to the following table:

    Property Description
    container_dir String containing the path to the mounted volume that you bound to your app.
    device_type The NFS volume release Currently only supports shared devices. A shared device represents a distributed file system that can mount on all app instances simultaneously.
    mode String that informs what type of access your app has to NFS, either read-only ro, or read and write rw.

View the source for this page in GitHub