deploy-vol-services.html.md.erb

---
title: Adding volume services to your deployment
owner: Diego Persistence
---

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

## <a id="overview"></a> 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](#example) and [Deploy SMB volume service to Cloud Foundry](#smb-example) below.

### <a id='additional-info'></a> Additional information

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

* [Volume Services Google Doc](https://docs.google.com/document/d/1YtPMY9EjxlgJPa4SVVwIinfid_fshCF48xRhzyoZhrQ/edit?usp=sharing)
* [Volume Services Troubleshooting Guide](https://github.com/cloudfoundry/volman/blob/master/TROUBLESHOOTING.md)
* [NFS volume release repository](https://github.com/cloudfoundry/nfs-volume-release)
* [SMB volume release repository](https://github.com/cloudfoundry/smb-volume-release)
* [EFS volume release repository](https://github.com/cloudfoundry-incubator/efs-volume-release)

<p class="note important">
<span class="note__title"><strong>Important</strong></span>
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 <a href="https://github.com/cloudfoundry/local-volume-release.git">local-volume-release</a> in GitHub.
</p>

### <a id='contact'></a> 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)](https://cloudfoundry.slack.com)
Slack organization.

## <a id="example"></a> 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](#redeploy)
1. [Grant Access to the NFS service](#broker)
1. [(Optional) Enable LDAP support](#ldap)
1. [(Optional) Deploy test servers](#server)

### <a id="pre"></a> 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](/deploying/index.html).
* The BOSH CLI. See [Installing the CLI](https://bosh.io/docs/cli-v2-install/) 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](#nfs-test) below.

### <a id="redeploy"></a> 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:
  <pre class="terminal">$ cd ~/workspace
  $ git clone https<span>:</span>//github.com/cloudfoundry/cf-deployment.git
  $ cd ~/workspace/cf-deployment</pre>

1. 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:
    <pre class="terminal">$ bosh -e my-env -d cf deploy cf.yml -v deployment-vars.yml \
		-o operations/enable-nfs-volume-service.yml</pre>

1. Deploy the NFS service broker app by running the `nfsbrokerpush` errand.<br>
  For example:
  <pre class="terminal">$ bosh -e my-env -d cf run-errand nfsbrokerpush</pre>

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

### <a id="broker"></a> 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)](../devguide/services/using-vol-services.html).

### <a id="ldap"></a> (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](#ldap-config)
1. [Configure your Cloud Foundry deployment](#cf-ldap-config)

#### <a name="ldap-config"></a>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.<br>
    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`.

#### <a name="cf-ldap-config"></a>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](https://github.com/cloudfoundry/cf-deployment/blob/main/operations/enable-nfs-ldap.yml)
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:

    <table class="table">
      <thead><tr>
        <th width=35%>Variable</th>
        <th>Description</th>
      </tr></thead>

      <tr>
        <td><code>nfs-ldap-service-user</code></td>
        <td>This is your LDAP service account user name.</td>
      </tr>

      <tr>
        <td><code>nfs-ldap-service-password</code></td>
        <td>This is your LDAP service account password.</td>
      </tr>

      <tr>
        <td><code>nfs-ldap-host</code></td>
        <td>This is the LDAP server host name or IP address.</td>
      </tr>

      <tr>
        <td><code>nfs-ldap-port</code></td>
        <td>This is the LDAP server port.</td>
      </tr>

      <tr>
        <td><code>nfs-ldap-proto</code></td>
        <td>This is the LDAP server protocol. The protocol is either TCP or UDP.</td>
      </tr>

      <tr>
        <td><code>nfs-ldap-fqdn</code></td>
        <td>This is the LDAP fully qualified domain name for user records.
          This domain name is searched against when user UIDs are looked up.</td>
      </tr>

    </table>

1. 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:
    <pre class="terminal">$ bosh -e my-env -d cf deploy cf.yml --vars-file ldap-vars.yml \
		-o operations/enable-nfs-ldap.yml</pre>


### <a id="server"></a> (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](#nfs-test) below.
+ A LDAP test server that provides sample UID resolution when the LDAP feature is enabled.
See [Deploy LDAP test server](#ldap-test) below.

#### <a name="nfs-test"></a> 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](https://github.com/cloudfoundry/cf-deployment/blob/main/operations/test/enable-nfs-test-server.yml)
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:
    <pre class="terminal">$ bosh -e my-env -d cf deploy cf.yml  \
		-o operations/test/enable-nfs-test-server.yml</pre>

    <p class="note important">
    <span class="note__title"><strong>Important</strong></span>
    By default, the NFS test server expects that your
    Cloud Foundry deployment is deployed to a <code>10.x.x.x </code>subnet.
    If you are deploying to a subnet that is not <code>10.x.x.x</code>,
    you must override the <code>export_cidr</code> property.<br><br>
    To override the <code>export_cidr</code> property, edit the ops file and
    replace <code>nfstestserver: {}</code>
    with <code>nfstestserver: {export_cidr: YOUR-SUBNET}</code>,
    where <code> YOUR-SUBNET</code> is the subnet you are deploying Cloud Foundry to.
    </p>

#### <a name="ldap-test"></a>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](https://github.com/cloudfoundry/cf-deployment/blob/main/operations/test/enable-nfs-test-ldapserver.yml)
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:

    <table class="table">
      <thead><tr>
        <th width=35%>Variable</th>
        <th>Value</th>
      </tr></thead>

      <tr>
        <td><code>nfs-ldap-service-user</code></td>
        <td><code>cn=admin,dc=domain,dc=com</code></td>
      </tr>

      <tr>
        <td><code>nfs-ldap-service-password</code></td>
        <td><code>secret</code></td>
      </tr>

      <tr>
        <td><code>nfs-ldap-host</code></td>
        <td><code>nfstestldapserver.service.cf.internal</code></td>
      </tr>

      <tr>
        <td><code>nfs-ldap-port</code></td>
        <td><code>389</code></td>
      </tr>

      <tr>
        <td><code>nfs-ldap-proto</code></td>
        <td><code>tcp</code></td>
      </tr>

      <tr>
        <td><code>nfs-ldap-fqdn</code></td>
        <td><code> ou=Users,dc=domain,dc=com</code></td>
      </tr>

    </table>

1. 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:
    <pre class="terminal">$ bosh -e my-env -d cf deploy cf.yml --vars-file ldapserver-vars.yml \
		-o operations/test/enable-nfs-test-ldapserver.yml</pre>

## <a id="smb-example"></a>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](#smb-redeploy)
2. [Grant access to the SMB service](#smb-broker)
3. [(Optional) Deploy the SMB test server](#smb-server)


### <a id="smb-pre"></a> 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](/deploying/index.html).
* The BOSH CLI. See [Installing the CLI](https://bosh.io/docs/cli-v2-install/) 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](#smb-server).

### <a id="smb-redeploy"></a> 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:

  <pre class="terminal">$ cd ~/workspace
  $ git clone https<span>:</span>//github.com/cloudfoundry/cf-deployment.git
  $ cd ~/workspace/cf-deployment</pre>

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:
    <pre class="terminal">$ bosh -e my-env -d cf deploy cf.yml --vars-file deployment-vars.yml \
		-o operations/experimental/enable-smb-volume-service.yml</pre>

1. Deploy the SMB service broker app by running the `smbbrokerpush` errand.<br>
  For example:
  <pre class="terminal">$ bosh -e my-env -d cf run-errand smbbrokerpush</pre>

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

### <a id="smb-broker"></a> 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)](../devguide/services/using-vol-services.html).

### <a id="smb-server"></a> (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](https://github.com/cloudfoundry/cf-deployment/blob/main/operations/test/enable-smb-test-server.yml)
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:
    <pre class="terminal">$ bosh -e my-env -d cf deploy cf.yml \
		-o operations/test/enable-smb-test-server.yml</pre>

<p class="note important">
<span class="note__title"><strong>Important</strong></span>
By default, the SMB test server expects that your
Cloud Foundry deployment is deployed to a <code>10.x.x.x </code>subnet.
If you are deploying to a subnet that is not <code>10.x.x.x</code>,
you must override the <code>export_cidr</code> property.<br><br>
To override the <code>export_cidr</code> property, edit the ops file and
add in the properties section <code>export_cidr: YOUR-SUBNET</code>,
where <code> YOUR-SUBNET</code> is the subnet you are deploying Cloud Foundry to.
</p>