cloudfoundry/smb-volume-release

Name: smb-volume-release

Owner: Cloud Foundry

Description: BOSH release with SMB driver and Azure File Service Broker

Created: 2017-09-21 18:06:55.0

Updated: 2018-05-15 10:13:18.0

Pushed: 2018-05-14 19:01:17.0

Homepage:

Size: 239

Language: Shell

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

SMB volume release

This is a bosh release that packages:

• an smbdriver
• an azurefilebroker
• a test SMB server
• BOSH back & restore jobs for the broker's database

The broker and driver pair allows you:

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

The test server provides an easy test target with which you can try out volume mounts of preexisting shares.

Deploying to Cloud Foundry

Pre-requisites

1. Install Cloud Foundry, or start from an existing CF deployment. If you are starting from scratch, the article Overview of Deploying Cloud Foundry provides detailed instructions.

2. Install GO:

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

3. Install direnv:

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

Create and Upload this Release

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

    ~/workspace
   t clone https://github.com/cloudfoundry/smb-volume-release.git
    ~/workspace/smb-volume-release
   renv allow .
   t checkout master
   scripts/update
   

2. Bosh create the release

   sh -n create-release --force
   

3. Bosh upload the release

   SH CLI v2
   sh -n -e <YOUR BOSH DEPLOYMENT NAME> upload-release
   

Redeploy Cloud Foundry with smb enabled

1. You should have it already after deploying Cloud Foundry, but if not clone the cf-deployment repository from git:

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

2. Now redeploy your cf-deployment while including the smb ops file:

   sh -e my-env -d cf deploy cf.yml -v deployment-vars.yml -o ../smb-volume-release/operations/deploy-smb-broker-and-install-driver.yml
   

Note: the above command is an example, but your deployment command should match the one you used to deploy Cloud Foundry initially, with the addition of a -o ../smb-volume-release/operations/deploy-smb-broker-and-install-driver.yml option.

Your CF deployment will now have a running service broker and volume drivers, ready to mount or create SMB volumes. Unless you have explicitly defined a variable for your broker password, BOSH will generate one for you. You can find the password for use in broker registration via the bosh interpolate command:

 int deployment-vars.yml --path /smb-broker-password

Testing or Using this Release

Deploying the Test SMB Server (Optional)

If you do not have an existing SMB Server then you can optionally deploy the test SMB server bundled in this release.

The easiest way to deploy the test server is to include the enable-smb-test-server.yml operations file when you deploy Cloud Foundry, also specifying smb-username and smb-password variables:

sh -e my-env -d cf deploy cf.yml -v deployment-vars.yml \
 smb-username=smbuser \
 smb-password=something-secret \
 ../smb-volume-release/operations/deploy-smb-broker-and-install-driver.yml \
 ../smb-volume-release/operations/enable-smb-test-server.yml

NOTE: This test SMB server only works with Ubuntu stemcells.

Register azurefilebroker

• Register the broker and grant access to its service with the following command:

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

  Note:

  • if you deployed the service broker using the operations file from this release, your username will be admin and the password will be generated by bosh and discoverable with bosh interpolate as described above.

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

1. type the following:

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

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

1. type the following:

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

   NOTE:

   • Please see more details about parameters here.
   • The Azure file share only can be bound 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:

    create-service smbvolume Existing myVolume -c '{"share":"//smbtestserver.service.cf.internal/vol2"}'
    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:

   t clone https://github.com/cloudfoundry/persi-acceptance-tests.git
    persi-acceptance-tests/assets/pora
    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.

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

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

    bind-service pora myVolume -c '{"username":"smbuser","password":"something-secret"}'
   

   NOTE:

   • Please see more details about parameters here.
   • If you are using an Azure file share as the preexisting share, you need to specify "vers": "3.0" in the parameters.
   • 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

4. Start the application

    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.

BBR Support

If you are using Bosh Backup and Restore (BBR) to keep backups of your Cloud Foundry deployment, consider including the enable-azurefile-broker-backup.yml operations file from this repository when you redeploy Cloud Foundry. This file will install the requiste backup and restore scripts for service broker metadata on the backup/restore VM.

Troubleshooting

If you have trouble getting this release to operate properly, try consulting the Volume Services Troubleshooting Page

Deploying the service broker with cf push

You may wish to run the service broker in Cloud Foundry using cf push instead of bosh deploying it. That has the benefit of using one less virtual machine. To do that, you will first need to modify the deploy-smb-broker-and-install-driver.yml operations file to remove the service broker, and then push the broker instead using the steps below.

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.

     all-Module AzureRM
     rt-Module AzureRM
     

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

     ExecutionPolicy Unrestricted -Scope CurrentUser
     config-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.

  ush azurefilebroker
  

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

  ush azurefilebroker --no-start
  ind-service azurefilebroker <sql service instance name>
  tart 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.