Adding volume services to your deployment

Page last updated:

This topic describes how Cloud Foundry operators can deploy volume services.

Overview

A volume service gives apps access to a remote filesystem, such as NFS. To provide a volume service for Cloud Foundry developers to use with their apps, you must deploy a driver and broker pair.

For current versions of Cloud Foundry that have been been deployed with cf-deployment, you can deploy brokers and drivers using ops files.

For examples of deploying brokers and drivers using ops files, see Deploy NFS volume service to Cloud Foundry and Deploy SMB volume service to Cloud Foundry below.

Additional information

For more information about volume services and the drivers and brokers available to Cloud Foundry, see the following:

• Volume Services Google Doc
• Volume Services Troubleshooting Guide
• NFS volume release repository
• SMB volume release repository
• EFS volume release repository

Important If you are running a single Diego Cell Cloud Foundry deployment, you can deploy a local volume release in a test environment. Do not deploy local volume releases in production deployments. For information about local volume releases, see local-volume-release in GitHub.

Contact

If you have any questions, you can contact the team that develops volume services for Cloud Foundry on the #persi channel in the Cloud Foundry (Open Source) Slack organization.

Deploy NFS volume service to Cloud Foundry

This section provides an example of how to deploy the NFS broker and corresponding driver to an existing Cloud Foundry deployment.

To deploy the NFS broker and driver to an existing Cloud Foundry deployment, do the following:

1. Redeploy Cloud Foundry with NFS enabled
2. Grant Access to the NFS service
3. (Optional) Enable LDAP support
4. (Optional) Deploy test servers

Prerequisites

Before you deploy the NFS volume service to a Cloud Foundry deployment, you must have the following:

• A current version of Cloud Foundry deployed. See Overview of deploying Cloud Foundry.
• The BOSH CLI. See Installing the CLI in the BOSH documentation.
• An NFS server. If you require an NFS test server, you can deploy one by following the instructions in Deploy the NFS test server below.

Redeploy Cloud Foundry with NFS enabled

To redeploy Cloud Foundry with NFS enabled, do the following:

1. If you do not have the cf-deployment repository, clone it by running the following commands:

   $ cd ~/workspace
   $ git clone https://github.com/cloudfoundry/cf-deployment.git
   $ cd ~/workspace/cf-deployment

2. Redeploy your cf-deployment with the NFS ops file by running the following command:

   bosh -e MY-ENV -d MY-DEPLOYMENT deploy MANIFEST-YAML --vars-file VARIABLES-YAML \
       -o operations/enable-nfs-volume-service.yml
   

   Where:

   • MY-ENV is the name of the BOSH Director.
   • MY-DEPLOYMENT is the name of your deployment.
   • MANIFEST-YAML is the name of the manifest YAML file you used when you deployed Cloud Foundry.
   • VARIABLES-YAML is the name of the variables YAML file you used when you deployed Cloud Foundry.

   For example:

   $ bosh -e my-env -d cf deploy cf.yml -v deployment-vars.yml \
       -o operations/enable-nfs-volume-service.yml

3. Deploy the NFS service broker app by running the nfsbrokerpush errand.
   For example:

   $ bosh -e my-env -d cf run-errand nfsbrokerpush

Your Cloud Foundry deployment now has a running service broker and volume drivers and is ready to mount NFS volumes.

Grant access to the NFS service

For Cloud Foundry app developers to use the NFS broker, you must grant app developers access to the NFS service.

To grant access to the NFS service, do the following:

1. Run the following command:

   cf enable-service-access nfs
   

Cloud Foundry app developers can now create an NFS service and bind instances to their apps. For more information, see Using an external file system (volume services).

(Optional) Enable LDAP support

For better NFS security, you can configure your Cloud Foundry deployment to connect to an external LDAP server. When you connect your deployment to an LDAP server, the NFS volume service is secured so that an app developer cannot bind to an NFS share using an arbitrary UID. This ensures that an app developer cannot gain access to sensitive data stored by another user or app.

Configuring an LDAP server enables the NFS volume driver to do the following:

• Validate app developer credentials for user accounts.
• Translate user credentials into a valid UID and GID for that user.

When you enable LDAP support, regular UID and GID parameters are deactivated. If you enable LDAP, app developers need to provide valid credentials for any user they want to use on the NFS server.

To enable LDAP support, do the following:

1. Configure your LDAP server
2. Configure your Cloud Foundry deployment

Configure your LDAP server

If you want to integrate LDAP, your LDAP server must be configured to connect to a Cloud Foundry deployment.

To integrate LDAP with your Cloud Foundry deployment, do the following:

1. Configure your external LDAP server to have the following:
   • A provisioned service account that has read-only access to user records. This account is used by nfsv3driver to look up usernames and convert them to UIDs.
     In Windows Server 2008 and later, you can do this by creating a new user and adding it to the Read-only Domain Controllers group.
   • A LDAP schema that contains uidNumber and gidNumber fields for the user accounts used by NFS services. These fields are used to establish the correct UID for a named user.
   • A LDAP schema where each user record contains the attribute objectClass: User. When searching, this field is used by the nfsv3driver as a filter to identify which records are user records.
   • Be reachable through the network from the Diego Cell VMs on the port you use to connect to your deployment. This port is usually 389 or 636.

Configure your Cloud Foundry deployment

If you want to integrate LDAP, your Cloud Foundry deployment must redeployed with the enable-nfs-ldap.yml ops file and your LDAP server information. To view the NFS LDAP ops file, see cf-deployment in GitHub.

To integrate LDAP with your Cloud Foundry deployment, do the following:

1. Provide the following variables in a variables file using the --vars-file flag or with the -v flag on the BOSH command line:

   Variable	Description
   nfs-ldap-service-user	This is your LDAP service account user name.
   nfs-ldap-service-password	This is your LDAP service account password.
   nfs-ldap-host	This is the LDAP server host name or IP address.
   nfs-ldap-port	This is the LDAP server port.
   nfs-ldap-proto	This is the LDAP server protocol. The protocol is either TCP or UDP.
   nfs-ldap-fqdn	This is the LDAP fully qualified domain name for user records. This domain name is searched against when user UIDs are looked up.

2. Redeploy your cf-deployment with the enable-nfs-ldap.yml ops file by running the following command:

   bosh -e MY-ENV -d MY-DEPLOYMENT deploy MANIFEST-YAML -v VARIABLES-YAML \
       -o operations/enable-nfs-ldap.yml
   

   Where:

   • MY-ENV is the name of the BOSH Director.
   • MY-DEPLOYMENT is the name of your deployment.
   • MANIFEST-YAML is the name of the manifest YAML file you used when you deployed Cloud Foundry.
   • VARIABLES-YAML is the name of the variables YAML file for the LDAP information.

   For example:

   $ bosh -e my-env -d cf deploy cf.yml --vars-file ldap-vars.yml \
       -o operations/enable-nfs-ldap.yml

(Optional) Deploy test servers

The NFS volume service includes the following test servers:

• A NFS test server that provides NFS shares. See Deploy the NFS test server below.
• A LDAP test server that provides sample UID resolution when the LDAP feature is enabled. See Deploy LDAP test server below.

Deploy the NFS test server

If you want to experiment with volume mounts, you can deploy a NFS test server using the enable-nfs-test-server.yml ops file. This file creates a separate VM with NFS exports. To view the NFS test server ops file, see cf-deployment in GitHub.

To redeploy your Cloud Foundry deployment with a NFS test server, do the following:

1. Run the following command:

   bosh -e MY-ENV -d MY-DEPLOYMENT deploy MANIFEST-YAML \
       -o operations/test/enable-nfs-test-server.yml
   

   Where:

   • MY-ENV is the name of the BOSH Director.
   • MY-DEPLOYMENT is the name of your deployment.
   • MANIFEST-YAML is the name of the manifest YAML file you used when you deployed Cloud Foundry.

   For example:

   $ bosh -e my-env -d cf deploy cf.yml  \
       -o operations/test/enable-nfs-test-server.yml

   Important By default, the NFS test server expects that your Cloud Foundry deployment is deployed to a 10.x.x.x subnet. If you are deploying to a subnet that is not 10.x.x.x, you must override the export_cidr property.
   
   To override the export_cidr property, edit the ops file and replace nfstestserver: {} with nfstestserver: {export_cidr: YOUR-SUBNET}, where YOUR-SUBNET is the subnet you are deploying Cloud Foundry to.

Deploy LDAP test server

If you want to experiment with using LDAP with an NFS server, you can deploy a LDAP test server using the enable-nfs-test-ldapserver.yml ops file. This file installs an LDAP server onto the VM created for the NFS test server. To view the LDAP test server ops file, see cf-deployment in GitHub.

The deployed LDAP server is preconfigured with a single user account with username uid1000 and password secret. When the test user is queried, the user resolves to UID 1000 and GID 1000.

To redeploy your Cloud Foundry deployment with a LDAP test server, do the following:

1. Provide the following variables in a variables file or with the -v flag on the BOSH command line:

   Variable	Value
   nfs-ldap-service-user	cn=admin,dc=domain,dc=com
   nfs-ldap-service-password	secret
   nfs-ldap-host	nfstestldapserver.service.cf.internal
   nfs-ldap-port	389
   nfs-ldap-proto	tcp
   nfs-ldap-fqdn	ou=Users,dc=domain,dc=com

2. Run the following command:

   bosh -e MY-ENV -d MY-DEPLOYMENT deploy MANIFEST-YAML --vars-file VARIABLES-YAML\
       -o operations/test/enable-nfs-test-ldapserver.yml
   

   Where:

   • MY-ENV is the name of the BOSH Director.
   • MY-DEPLOYMENT is the name of your deployment.
   • MANIFEST-YAML is the name of the manifest YAML file you used when you deployed Cloud Foundry.
   • VARIABLES-YAML is the name of the variables YAML file for the LDAP settings.

   For example:

   $ bosh -e my-env -d cf deploy cf.yml --vars-file ldapserver-vars.yml \
       -o operations/test/enable-nfs-test-ldapserver.yml

Deploy SMB volume service to Cloud Foundry

This section provides an example of how to deploy the SMB broker and corresponding driver to an existing Cloud Foundry deployment.

To deploy the SMB broker and driver to an existing Cloud Foundry deployment:

1. Redeploy Cloud Foundry with SMB enabled
2. Grant access to the SMB service
3. (Optional) Deploy the SMB test server

Prerequisites

Before you deploy the SMB volume service to a Cloud Foundry deployment, you must have the following:

• A current version of Cloud Foundry deployed. See Overview of Deploying Cloud Foundry.
• The BOSH CLI. See Installing the CLI in the BOSH documentation.
• An SMB server. If you require an SMB test server, you can deploy one by following the instructions in (Optional) Deploy the SMB test servers.

Redeploy Cloud Foundry with SMB enabled

To redeploy Cloud Foundry with SMB enabled, do the following:

1. If you do not have the cf-deployment repository, clone it by running the following commands:

$ cd ~/workspace
  $ git clone https://github.com/cloudfoundry/cf-deployment.git
  $ cd ~/workspace/cf-deployment

1. Redeploy your cf-deployment with the SMB ops file by running the following command:

   bosh -e MY-ENV -d MY-DEPLOYMENT deploy MANIFEST-YAML --vars-file VARIABLES-YAML \
     -o operations/experimental/enable-smb-volume-service.yml
   

   Where:

   • MY-ENV is the name of the BOSH Director.
   • MY-DEPLOYMENT is the name of your deployment.
   • MANIFEST-YAML is the name of the manifest YAML file you used when you deployed Cloud Foundry.
   • VARIABLES-YAML is the name of the variables YAML file you used when you deployed Cloud Foundry.

   For example:

   $ bosh -e my-env -d cf deploy cf.yml --vars-file deployment-vars.yml \
       -o operations/experimental/enable-smb-volume-service.yml

2. Deploy the SMB service broker app by running the smbbrokerpush errand.
   For example:

   $ bosh -e my-env -d cf run-errand smbbrokerpush

Your Cloud Foundry deployment now has a running service broker and volume drivers and is ready to mount existing SMB shares.

Grant access to the SMB service

For Cloud Foundry app developers to use the SMB broker, you must grant app developers access to the SMB service.

To grant access to the SMB service, do the following:

1. Run the following command:

   cf enable-service-access smb
   

Cloud Foundry app developers can now create an SMB service and bind instances to their apps. For more information, see Using an external file system (volume services).

(Optional) Deploy the SMB test server

If you want to experiment with volume mounts, you can deploy a SMB test server using the enable-smb-test-server.yml ops file. This file creates a separate VM with SMB shares. To view the SMB test server ops file, see cf-deployment in GitHub.

To redeploy your Cloud Foundry deployment with a SMB test server, do the following:

1. Run the following command:

   bosh -e MY-ENV -d MY-DEPLOYMENT deploy MANIFEST-YAML \
     -o operations/test/enable-smb-test-server.yml
   

   Where:

   • MY-ENV is the name of the BOSH Director.
   • MY-DEPLOYMENT is the name of your deployment.
   • MANIFEST-YAML is the name of the manifest YAML file you used when you deployed Cloud Foundry.

   For example:

   $ bosh -e my-env -d cf deploy cf.yml \
       -o operations/test/enable-smb-test-server.yml

Important By default, the SMB test server expects that your Cloud Foundry deployment is deployed to a 10.x.x.x subnet. If you are deploying to a subnet that is not 10.x.x.x, you must override the export_cidr property.

To override the export_cidr property, edit the ops file and add in the properties section export_cidr: YOUR-SUBNET, where YOUR-SUBNET is the subnet you are deploying Cloud Foundry to.