SMB volume release

This is a bosh release that packages an smbdriver and azurefilebroker for consumption by a volume_services_enabled Cloud Foundry deployment.

This broker/driver pair allows you:

1. to provision Azure storage accounts and bind Azure file shares to your applications for shared file access.
2. to provision preexisting shares and bind the shares to your applications for share file access.

Deploying to Azure

Pre-requisites

1. Install Cloud Foundry with Diego, or start from an existing CF+Diego deployment on Azure.

2. If you are starting from scratch, you can follow this guidance to deploy a Cloud Foundry with Diego on Azure via Azure template.

3. Install GO:

   mkdir ~/workspace ~/go
   cd ~/workspace
   wget https://storage.googleapis.com/golang/go1.9.linux-amd64.tar.gz
   sudo tar -C /usr/local -xzf go1.9.linux-amd64.tar.gz
   echo 'export GOPATH=$HOME/go' >> ~/.bashrc
   echo 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' >> ~/.bashrc
   exec $SHELL

4. Install direnv:

   mkdir -p $GOPATH/src/github.com/direnv
   git clone https://github.com/direnv/direnv.git $GOPATH/src/github.com/direnv/direnv
   pushd $GOPATH/src/github.com/direnv/direnv
       make
       sudo make install
   popd
   echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
   exec $SHELL

Create and Upload this Release

1. Clone smb-volume-release (master branch) from git:

   $ cd ~/workspace
   $ git clone https://github.com/AbelHu/smb-volume-release.git
   $ cd ~/workspace/smb-volume-release
   $ direnv allow .
   $ git checkout master
   $ ./scripts/update

2. Bosh create the release

   $ bosh -n create release --force

3. Bosh upload the release

   # BOSH CLI v1
   $ bosh -n upload release

   # BOSH CLI v2
   $ bosh -n -e <YOUR BOSH DEPLOYMENT NAME> upload-release

Enable Volume Services in CF and Redeploy

In your CF manifest, check the setting for properties: cc: volume_services_enabled (If multiple cc properties exist, please update cc properties under the job api). If it is not already true, set it to true and redeploy CF. (This will be quick, as it only requires BOSH to restart the cloud controller job with the new property.)

Colocate the smbdriver job on the Diego Cell

If you have a bosh director version < 259 you will need to use one of the OLD WAYS below. (check bosh status to determine your version). Otherwise we recommend the NEW WAY 👍👍👍

OLD WAY Manual Editing

1. Add smb-volume to the releases: key

   releases:
   - name: diego
     version: latest
     ...
   - name: smb-volume
     version: latest

2. Add smbdriver to the jobs: name: cell_z1 templates: key

   jobs:
     ...
     - name: cell_z1
       ...
       templates:
       - name: consul_agent
         release: cf
         ...
       - name: smbdriver
         release: smb-volume

3. Redeploy Diego using your new manifest.

NEW WAY Use bosh add-ons with filtering

This technique allows you to co-locate bosh jobs on cells without editing the Diego bosh manifest.

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

   ---
   releases:
   - name: smb-volume
     version: <YOUR VERSION HERE>
   addons:
   - name: voldrivers
     include:
       deployments:
       - <YOUR DIEGO DEPLOYMENT NAME>
       jobs:
       - name: rep
         release: diego
     jobs:
     - name: smbdriver
       release: smb-volume
       properties: {}

2. Set the runtime config:

   # BOSH CLI v1
   $ bosh update runtime-config runtime-config.yml

   # BOSH CLI v2
   $ bosh -e <YOUR BOSH DEPLOYMENT NAME> update-runtime-config runtime-config.yml

3. Redeploy Diego using your new manifest.

Deploying azurefilebroker

The azurefilebroker can be deployed in two ways; as a cf app or as a BOSH deployment. The choice is yours!

Way #1 cf push the broker

When the service broker is cf pushed, you can bind it to a MSSql or MySql database service instance.

NOTE It is not supported to bind to Azure SQL with an old meta-azure-service-broker before v1.5.1 because the variable names do not match. You must specify variables in the manifest.

If you want to use an Azure SQL service to store data for the service broker,

• If you are using meta-azure-service-broker to provision a new databse with a new server, you can set connectionPolicy to proxy in configuration parameters.

• Otherwise you need to change the policy from "default" to "proxy" after creating your SQL server by following below steps:

  1. Open PowerShell in administrator privilege and install AzureRM module.

     Install-Module AzureRM
     Import-Module AzureRM

  2. Download reconfig-mssql-policy.ps1 and run it to change the policy of your Azure SQL server.

     Set-ExecutionPolicy Unrestricted -Scope CurrentUser
     ./reconfig-mssql-policy.ps1

Once you have a database service instance available in the space where you will push your service broker application, follow the following steps:

• ./script/build-broker

• Edit manifest.yml to set up all required parameters. manifest.yml and Procfile will work together to start the broker.

  • With a database directly: DBCACERT, HOSTNAMEINCERTIFICATE, DBUSERNAME, DBPASSWORD, DBHOST, DBPORT and DBNAME in manifest.yml need to be set up.

  cf push azurefilebroker

  • With a Cloud Foundry database service instance: DBCACERT, HOSTNAMEINCERTIFICATE and DBSERVICENAME needs to be set up.

  cf push azurefilebroker --no-start
  cf bind-service azurefilebroker <sql service instance name>
  cf start azurefilebroker

  NOTE:

  • When environment is Preexisting, only one plan Existing is supported; For others, both two plans Existing and AzureFileShare are supported.
  • Please see more details about broker's configurations here.

Way #2 - bosh deploy the broker

You can reference bosh deploy nfsbroker.

Testing or Using this Release

Register azurefilebroker

• Register the broker and grant access to it's service with the following command:

  $ cf create-service-broker azurefilebroker <BROKER_USERNAME> <BROKER_PASSWORD> http://azurefilebroker.YOUR.DOMAIN.com
  $ cf enable-service-access smbvolume

Create an SMB volume service with an existing storage account on Azure

1. type the following:

   $ cf create-service smbvolume AzureFileShare myVolume -c '{"storage_account_name":"<YOUR-AZURE-STORAGE-ACCOUNT>"}'
   $ cf services

Create an SMB volume service with a new storage account on Azure

1. type the following:

   $ cf create-service smbvolume AzureFileShare myVolume -c '{"storage_account_name":"<YOUR-AZURE-STORAGE-ACCOUNT>, "location":"<YOUR-LOCATION>"}'
   $ cf services

   NOTE:

   • Please see more details about parameters here.
   • The Azure file share only can be binded to your application in Linux when they are in the same location.

Create an SMB volume service with a preexisting share

1. type the following:

   $ cf create-service smbvolume Existing myVolume -c '{"share":"<YOUR-PREEXISTING-SHARE-URL>"}'
   $ cf services

   NOTE: The format of the share is //server/folder or \\\\server\\folder.

Deploy the pora test app, first by pushing the source code to CloudFoundry

1. type the following:

   $ git clone https://github.com/cloudfoundry/persi-acceptance-tests.git
   $ cd persi-acceptance-tests/assets/pora
   $ cf push pora --no-start

2. Bind the service to your app supplying the correct Azure file share. Broker will create it if it does not exist by default.

   $ cf bind-service pora myVolume -c '{"share": "one"}'

3. Bind the service to your app supplying the correct credentials for preexisting shares.

   $ cf bind-service pora myVolume -c '{"username": "a", "password": "b"}'

   NOTE:

   • Please see more details about parameters here.
   • uid & gid: When binding the Azure file share to the application, the uid and gid specified are supplied to the mount.cifs. The mount.cifs masks the running user id and group id as the true owner shown on the Azure file share. Any operation on the mount will be executed as the owner, but locally the mount will be seen as being owned by the running user.
   • mount: By default, volumes are mounted into the application container in an arbitrarily named folder under /var/vcap/data. If you prefer to mount your directory to some specific path where your application expects it, you can control the container mount path by specifying the mount option. The resulting bind command would look something like cf bind-service pora myVolume -c '{"share", "one", "uid":"0","gid":"0","mount":"/var/path"}' NOTE: As of this writing aufs used by Garden is not capable of creating new root level folders. As a result, you must choose a path with a root level folder that already exists in the container. (/home, /usr or /var are good choices.) If you require a path that does not already exist in the container it is currently only possible if you upgrade your Diego deployment to use GrootFS with Garden. For details on how to generate a Diego manifest using GrootFS see this note. Eventually, GrootFS will become the standard file system for CF containers, and this limitation will go away.
   • If you are using an Azure file share as the preexisting share, you need to specify "vers": "3.0" in the parameters.

4. Start the application

   $ cf start pora

Test the app to make sure that it can access your SMB volume

1. to check if the app is running, curl http://pora.YOUR.DOMAIN.com should return the instance index for your app
2. to check if the app can access the shared volume curl http://pora.YOUR.DOMAIN.com/write writes a file to the share and then reads it back out again.

Reference

Please reference more information about Application specifies here.