Adding Volume Services to Your Deployment

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

Note: Volume services are only available to CF deployments that use the Diego architecture.

Overview

A volume service gives apps access to an ephemeral filesystem, such as NFS. To provide a volume service for CF developers to use with their apps, you must deploy a driver and broker pair as outlined below in Example: Deploy NFS to AWS.

Additional Information

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

Note: For test purposes, you can deploy the Local Volume Release if running a single Diego Cell CF deployment. This is not intended for production deployments.

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.

Example: Deploy NFS Volume Service to AWS

The following procedure provides an example of how to deploy the NFS broker and corresponding driver on AWS.

Prerequisites

This procedure requires the following:

Enable Volume Services in Cloud Foundry

  1. Run the BOSH CLI bosh -e MY-ENV vms command to list the virtual machines (VMs) managed by your BOSH Director. Replace MY-ENV with the alias you set for your BOSH Director.

    $ bosh -e my-env vms 

  2. In the output, locate the CF Cloud Controller VM and record the corresponding deployment name.

  3. Run bosh -e MY-ENV -d MY-CF-DEPLOYMENT-NAME download-manifest > cf.yml to download your CF deployment manifest. Replace MY-ENV with the alias you set for your BOSH Director and MY-CF-DEPLOYMENT-NAME with the deployment name you recorded in the previous step.

     $ bosh -e my-env -d my-dep download-manifest > cf.yml

  4. Add the following property to the cf.yml manifest if it does not already exist: properties: cc: volume_services_enabled: true

  5. Run bosh -e MY-ENV -d MY-CF-DEPLOYMENT-NAME deploy cf.yml to redeploy Cloud Foundry with volume services enabled.

    $ bosh -e my-env -d my-dep deploy cf.yml

Add the NFS Driver to Diego Cells

  1. Download the nfs-volume-release release from bosh.io.

  2. Run bosh -e MY-ENV -d DIEGO-DEP-NAME upload-release PATH-TO-RELEASE to upload the release to your BOSH Director. Replace PATH-TO-RELEASE with the path to the nfs volume release you downloaded in the previous step.

    $ bosh -e my-env -d my-dep upload-release ~/downloads/nfs-volume-release-1.1.0.tgz

  3. Examine the output and record the version of the release you uploaded.

    Release info
    ------------
    Name:    nfs-volume
    Version: 0.0.11
    
  4. Run bosh -e MY-ENV vms to list the VMs managed by your BOSH Director.

    $ bosh -e my-env vms 

  5. Examine the output for the Diego cell VMs labeled cell_* and record the corresponding deployment name.

  6. Create a new runtime-config.yml file with the following content:

    ---
    releases:
    - name: nfs-volume
      version: MY-VERSION
    addons:
    - name: voldrivers
      include:
        deployments:
        - DIEGO-DEP-NAME
        jobs:
        - name: rep
          release: diego
        jobs:
        - name: nfsv3driver
          release: nfs-volume
          properties: {}
    
    • Replace MY-VERSION with the version you recorded in a previous step.
    • Replace DIEGO-DEP-NAME with the deployment name you recorded in the previous step.
  7. Run bosh -e MY-ENV -d DIEGO-DEP-NAME update-runtime-config runtime-config.yml to update the BOSH runtime configuration.

    $ bosh -e my-env -d my-dep update-runtime-config runtime-config.yml

  8. Run bosh -e MY-ENV -d DIEGO-DEP-NAME download-manifest > diego.yml to download your Diego manifest.

     $ bosh -e my-env -d my-dep download-manifest > diego.yml

  9. Run bosh -e MY-ENV -d DIEGO-DEP-NAME deploy diego.yml to deploy Diego:

     $ bosh -e my-env -d my-dep deploy diego.yml

Generate a Manifest for the NFS Broker

To create an NFS Service Broker, you must combine several pieces of information into a single BOSH manifest to deploy. Follow the steps below to put this information into stubs, then use a script to combine the stubs into a manifest.

Create the Cloud Foundry Stub

  1. Run bosh -e MY-ENV vms to list the VMs managed by your BOSH Director. Replace MY-ENV with the alias you set for your BOSH Director.

    $ bosh -e my-env vms 

  2. Examine the output for the Cloud Foundry NATS VM labeled nats_* and record the corresponding deployment name.

  3. Run bosh -e MY-ENV -d MY-CF-DEPLOYMENT-NAME download-manifest > cf.yml to download your CF deployment manifest. Replace MY-CF-DEPLOYMENT-NAME with the deployment name you recorded in the previous step.

     $ bosh -e my-env -d my-dep download-manifest > cf.yml

Create the Director Stub

  1. Run bosh -e MY-ENV env to determine the UUID of your BOSH Director.

     $ bosh -e my-env env

  2. Create a new director.yml file with the following contents from the last step:

    ---
    director_uuid: BOSH-DIRECTOR-UUID
    ---
    

Create the IaaS Settings Stub

Note: This is an AWS-specific IaaS Settings Stub. If you want to deploy on another IaaS, use the templates available in the templates directory of each volume services release repository.

  1. Create an iaas.yml stub for IaaS-specific settings by copying the template below:

    ---
    jobs:
    - name: nfsbroker
      networks:
      - name: public
        static_ips: [PUBLIC-BROKER-IP]
    
    networks:
    - name: nfsvolume-subnet
      subnets:
      - cloud_properties:
          security_groups:
          - SECURITY-GROUP
          subnet: SUBNET
        dns:
        - DNS
        gateway: GATEWAY
        range: SUBNET-RANGE
        reserved:
        - [RESERVED-IPs]
        static:
        - [STATIC-IPs]
    
    resource_pools:
    - name: medium
      stemcell:
        name: bosh-aws-xen-hvm-ubuntu-trusty-go_agent
        version: latest
      cloud_properties:
        instance_type: m3.medium
        availability_zone: us-east-1c
    - name: large
      stemcell:
        name: bosh-aws-xen-hvm-ubuntu-trusty-go_agent
        version: latest
      cloud_properties:
        instance_type: m3.large
        availability_zone: us-east-1c
    
  2. Replace each of the below parameters in the stub:

    For this value… Replace with…
    PUBLIC-BROKER-IP A pre-allocated AWS Elastic IP address.
    SECURITY-GROUP A Security Group in which to create the NFS Broker. Ensure this security group can access the security group that contains your CF deployment.
    SUBNET A subnet in which to create the NFS Broker. Ensure this subnet can access the subnet that contains your CF deployment.
    DNS Typically the DNS for your CF system domain, unless you want to host the broker outside of CF.
    GATEWAY Typically the gateway address for your CF system domain, unless you want to host the broker outside of CF.
    SUBNET-RANGE The CIDR range of the subnet in which to create the NFS Broker.
    RESERVED-IPs An array of IP addresses that BOSH cannot use for the NFS Broker, such as 10.10.200.0 - 10.10.200.10.
    STATIC-IPs An array of IP addresses that BOSH can use for the NFS Broker, such as 10.10.200.10 - 10.10.200.100.

Create the Credentials Stub

Create a creds.yml file and paste in the following contents, replacing the indicated values with a username and password of your choosing:

---
properties:
  nfsbroker:
    username: BROKER-USERNAME
    password: BROKER-PASSWORD

Generate the Deployment Manifest

  1. Clone the NFS volume release repository.

    $ git clone https://github.com/cloudfoundry-incubator/nfs-volume-release.git
    

  2. Navigate into the directory you cloned.

    $ cd nfs-volume-release
    

  3. Run the script below to generate a deployment manifest based on your stubs. You must specify the path to each stub file you created.

    $ ./scripts/generate_manifest.sh cf.yml director-uuid.yml iaas.yml creds.yml
    

Deploy the NFS Broker

  1. Run bosh -e MY-ENV -d MY-CF-DEPLOYMENT-NAME deploy nfsvolume-aws-manifest.yml to deploy the broker using the generated manifest.

    $ bosh -e my-env -d my-dep deploy nfsvolume-aws-manifest.yml
    

  2. Register the broker using the credentials specified in the creds.yml stub.

    $ cf create-service-broker nfsbroker BROKER-USERNAME BROKER-PASSWORD http://nfs-broker.YOUR-SYSTEM-DOMAIN
    

  3. Grant access to the service of the broker.

    $ cf enable-service-access nfs
    
    CF Developers can now create an NFS service and bind instances to their apps as outlined in the Using an External File System (Volume Services) topic.

(Optional) Deploy a Test NFS Server

If you want to use NFS and do not currently have a server available, you can deploy the test NFS server bundled with the NFS Volume release. Follow the instructions in Deploying the Test NFS Server (Optional) of the NFS volume release repository.

Create a pull request or raise an issue on the source for this page in GitHub