Using an External File System (Volume Services)

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

Prerequisite

Before you can use a volume service with your app, your Cloud Foundry administrator must add a volume service to your deployment. See the Adding Volume Services to your Deployment topic for more information.

You can run the Cloud Foundry Command Line Interface (cf CLI) cf marketplace command to determine 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 no volume service that fits your requirements exists, contact your Cloud Foundry administrator.

Create and Bind a Service Instance

To use a volume service deployed by your Cloud Foundry administrator, you must first create an instance of the specific volume service that you need. Follow the instructions below to create this service instance.

  1. In a terminal window, run cf create-service SERVICE-NAME PLAN SERVICE-INSTANCE -c SHARE-JSON to create a service instance. Replace the following with the specified values:

    • 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 with a JSON string, in-line or in a file. This parameter forwards information to the broker about the NFS server and share required for the service.

    The following example shows creating an instance of the “Existing” NFS service plan, passing an in-line JSON string:

    $ cf create-service nfs Existing nfs_service_instance -c '{"share": "10.10.10.10/export/myshare"}'

  2. Run cf bind-service YOUR-APP SERVICE-NAME -c GID-AND-UID-JSON to bind your service instance to an app. Replace the following with the specified values:

    • 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 string, in-line or in a file. This parameter specifies the gid and uid to use when mounting the share to the app.

    The following example shows binding my-app to the nfs_service_instance, passing an in-line JSON string:

    cf bind-service my-app nfs_service_instance -c '{"uid":"1000","gid":"1000"}'

  3. Run cf restage YOUR-APP to complete the service binding by restaging your app. Replace YOUR-APP with the name of your app.

    $ cf restage my-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 cf env YOUR-APP to view environment variables for your app. Replace YOUR-APP with the name of your app.

    $ cf env my-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. This 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