Adding Volume Services to your Deployment

This document 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 vms command to list the virtual machines (VMs) deployed by your BOSH Director.
    $ bosh vms 
    • Examine the output for the CF Cloud Controller VM and record the corresponding deployment name for use in the next step.
  2. Run bosh download manifest YOUR-CF-DEPLOYMENT-NAME > cf.yml to download your CF deployment manifest. Replace YOUR-CF-DEPLOYMENT-NAME with the deployment name you recorded in the previous step.
     $ bosh download manifest YOUR-CF-DEPLOYMENT-NAME > cf.yml
  3. Add the following property to the cf.yml manifest if it does not already exist: properties: cc: volume_services_enabled: true
  4. Run bosh -d cf.yml deploy to redeploy Cloud Foundry with volume services enabled.
    $ bosh -d cf.yml deploy

Add the NFS Driver to Diego Cells

  1. Download the nfs-volume-release release from bosh.io.
  2. Target your deployment using the BOSH CLI.
    $ bosh target BOSH-DIRECTOR-IP
  3. Upload the release to your BOSH Director
    $ bosh upload release PATH-TO-DOWNLOADED-NFS-VOLUME-RELEASE
    • Examine the output and record the version of the release you uploaded for later use.
      Release info
      ------------
      Name:    nfs-volume
      Version: 0.0.11
      
  4. Run the following command to list the VMs deployed by your BOSH Director:
    $ bosh vms 
    • Examine the output for the diego cell VMs labeled cell_* and record the corresponding deployment name for use in the next step.
  5. Create a new runtime-config.yml with the following content:

    • Replace YOUR-VERSION with the version you previously recorded.
    • For YOUR-DIEGO-DEPLOYMENT-NAME, use the deployment name from the previous step.

      ---
      releases:
      - name: nfs-volume
        version: YOUR-VERSION
      addons:
      - name: voldrivers
        include:
          deployments:
          - YOUR-DIEGO-DEPLOYMENT-NAME
          jobs:
          - name: rep
            release: diego
        jobs:
        - name: nfsv3driver
          release: nfs-volume
          properties: {}
      
  6. Update the BOSH runtime configuration:

    $ bosh update runtime-config runtime-config.yml

  7. Download the Diego manifest:

    $ bosh download manifest YOUR-DIEGO-DEPLOYMENT-NAME > diego.yml

  8. Deploy Diego:

     $ bosh -d diego.yml deploy

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 the following command to list the VMs deployed by your BOSH Director:
    $ bosh vms 
    • Examine the output for the Cloud Foundry NATS VM labeled nats_* and record the corresponding deployment name for use in the next step.
  2. Run the following command using the deployment name from the previous step to download your CF deployment manifest:
     $ bosh download manifest YOUR-CF-DEPLOYMENT-NAME > cf.yml

Create the Director Stub

  1. Run the following command to determine the UUID of your BOSH Director:

     $ bosh status --uuid

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

    ---
    director_uuid: YOUR-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 respository.

  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. Deploy the broker using the generated manifest.

    $ bosh -d nfsvolume-aws-manifest.yml deploy
    

  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 from the NFS volume release repository: Deploying the Test NFS Server (Optional).

View the source for this page in GitHub