Installing and Configuring SMB Volume Service for PCF

This document walks you through how to install and configure SMB Volume Service for PCF.

Prerequisite

  1. This tile includes a service broker, which will need a database to save mappings and other metadata about service instances. Both SQL and MySQL databases are supported. There are two options available to provide the database.

    1. Create a database manually or via script under your own control. For example, for instructions to create MySQL server using Azure portal, see the Microsoft Azure Product Documents. After the service is created, connect to the database service, create a database for the tile, then copy and save following information as these values will be used later to configure the service broker database:
    2. Server name, Server admin login, Password in step 2 (Create an Azure Database for MySQL server)
    3. The name of the database you created in step 5 (Connect to MySQL by using the mysql command-line tool).

      Note: Microsoft recommends Standard tier database for the broker, you could also adjust its tier and size based on your usage later.


    4. Create a database instance using CF service brokers, for example, MySQL for PCF v2 or Meta Azure service broker. In this way, service broker used to provide the database should be installed before you start to install this tile. We will use the Meta Azure service broker MySQL service as an example in this document. Follow the instruction here to install the service broker.

      Note: As Open Service Broker Azure currently does not support parameter Connection Policy for SQL database while TLS is forced, you will not be able to use SQL database provided by OSBA until this issue is fixed. For more details and to track this feature, see the GitHub issue.

      WARNING: Open Service Broker for Azure is currently in Beta, do NOT use in production.

  2. If you plan to use Azure file service, prepare a service principal and a resource group. Then new SMB share service instances could be created with storage accounts (new or existing), requiring a service principle to access resource (Azure File Service provided by storage account) on Azure. You can either reuse an existing service principal or create a new one depending on how you want to manager the permissions. Document on how to create a new service principal can be found here. Your storage account will be created under sprcified resource groups, while a resource group will be specified as default one. Creation and access permissions in these resource groups on storage account will be required for your service principal.

    WARNING: For security reasons, Microsoft recommends using different service principals with minimum permissions for each broker and BOSH.

    Note: Tenant ID/Tenant, Client ID/App ID and Client Secret/Password of your service principal and the ID for your default resource group will be used in Allow Azure File Service of Step 3.

Step 1: Add SMB Volume Service to Ops Manager

  1. Download the product file smb-volume-service-x.x.x.pivotal from Pivotal Network.

  2. Navigate to your Ops Manager Installation Dashboard and click Import a Product to upload the product file.

  3. Under the Import a Product button, click + next to the version number of SMB Volume Service. This adds the tile to your staging area.

  4. Click the newly added SMB Volume Service tile.

Step 2: Assign Networks

  1. Click Assign Networks. Network

  2. Assign a network for SMB Volume Service.

  3. Click Save.

Step 3: Service Broker Application Config

  1. Click Service Broker Application. Service broker application

  2. Select your desired Log Level per your preference.

  3. Select your file system provider environment with Share Environment.

    WARNING: This setting cannot be changed once deployment is done.

Use Preexisting Shares Only

  1. To use pre-existing SMB shares only, select Preexisting SMB share for Share Environment. Service broker application existing

    Note: You can still create Azure file shares manually and use them as Preexisting SMB shares in this mode.

  2. Click Save.

Use Azure File Service

  1. To enable the broker to use Azure File Service, select Azure File Share for Share Environment. Service broker application azure

  2. For Tenant ID, enter the tenant ID of your Azure service principal.

  3. For Client ID, enter the client ID/Application ID of your Azure service principal.

  4. For Client Secret, enter the client secret/password of your Azure service principal.

  5. For Default Subsctiption ID, enter the default Azure Subscription ID to use for storage accounts.

    Note: Ensure your service principal has permissions Storage Account Contributor and Storage Account Key Operator Service Role to this subscription.

  6. For Default Resource Group Name, enter the default resource group name to use for storage accounts.

  7. For Default Location, enter the location to use for creating storage accounts. For example, eastus.

    Note: Resource group and location can be specified as parameters at the creation of new service instances, overriding default values here.

  8. Enable Allow Create Storage Account if you want to allow the broker to create storage accounts.

  9. Enable Allow Create File Share if you want to allow the broker to create Azure file shares.

  10. Enable Allow Delete Storage Account if you want to allow the broker to delete storage accounts.

  11. Enable Allow Delete File Share if you want to allow the broker to delete Azure file shares.

  12. Click Save.

Step 4: Service Broker Database Config

  1. Click Service Broker Database Config. Service broker database

  2. For Database Driver, select the database type for the broker’s state, MSSQL (Microsoft SQL) or MySQL.

  3. (Optional) For Database CACert, enter the content of CA Cert to verify your SSL connection. Leave this empty if you are not using self-signed certificate for your database.

  4. (Optional) For Host Name in Certificate, enter the Common Name (CN) in the server certificate. Enter one of below values to enable TLS encryption when using both an Azure SQL service and an Azure MySQL service.

    • For AzureCloud: *.database.windows.net
    • For AzureUSGovernment: *.database.usgovcloudapi.net
    • For AzureChinaCloud: *.database.chinacloudapi.cn
    • For AzureGermanCloud: *.database.cloudapi.de

      Note: If either Database CACert or Host Name in Certificate is set, connections to the database will be forced to use SSL.

  5. You can configure SMB Volume Service to use a database service instance provided by CF service brokers, or to use an existing external database by Database Type.

    WARNING: This setting cannot be changed once your deployment is done.

    Note: If you are performing an upgrade that changes databases, do not modify your existing database configuration without migration or you may lose data. You must migrate your existing data first before applying new configurations.

Use Database Service Provided by Service Brokers

IF you choose to use a service broker to create the service database for SMB Volume Service, then during the installation, a database service instance will be created and bind to SMB Volume Service.

  1. To use a database service provided by a service broker, select Cloud Foundry Service for Database Type.
    Service broker database service

  2. For Cloud Foundry Service Name, enter the service name you choose to create the database instance, which can be retrived by command cf marketplace

    Note: If you want to use an Azure SQL service, make sure you set its Connection Policy to Proxy.

  3. For Cloud Foundry Service Plan, enter the service plan name for the database service instance.

    Note: You should be able to query all avaliable services and plans with CF CLI command cf marketplace.

  4. For Service Creation Parameters, enter a JSON format object which will be used as parameter to create the database instance.

    Note: For SQL database provided by Meta Azure Service Broker, this field should be set to {"sqlServerParameters":{"connectionPolicy":"Proxy"}} to set its Connection Policy to Proxy.

    Note: For MySQL database provided by Meta Azure Service Broker, this field should be set to {"location":"LOCATION_WITH_GEN4_HARDWARE"} to use regions with Gen4 hardware. For availabilities of Gen4 hardware across Microsoft Azure regions, check the Microsoft Azure Product Documents

  5. Click Save.

Use an Existing External Database Directly

Note: If you choose this option, you should already created a database server consists of at least one database in Azure by yourself in step Prerequisite.

  1. To use the database service directly without the service broker, please select Existing External Database for Database Type.
    Service broker database external

  2. For Database Hostname, enter the hostname for the database.

  3. For Database Port, enter the port for the database.

  4. For Database Name, enter the name for the database.

  5. For Database Username, enter the username for the database.

  6. For Database Password, enter the password for the database.

  7. Click Save.

Step 5: (Optional) Service Broker Bind Config

Different options can be set while binding service instance to your application. This form sets which options are allowed to be used and what are default options for these options. Full list of options can be found in document here.

  1. Click Service Broker Bind Config. Service broker bind

  2. For Allowed Options, enter a comma-separated list of parameters that are allowed during service binding.

    Note: Except share and mount, all other parameters here must also be in the list of Mount Flag Allowed in the SMB Driver Config.

  3. For Default Options, enter a comma-separated list of default parameters and values in the format of param:value.

    Note: If a parameter has a default value, and is not in the Allowed Options list, then this value becomes a fixed value that cannot be overridden.

  4. Click Save.

Step 6: (Optional) SMB Driver Config

  1. Click SMB Driver Config. Smb driver

  2. For Mount Flag Allowed, enter a comma-separated list of parameters to be set in the extra config. Each parameter here will specified by brokers.

  3. For Mount Flag Default, enter a comma-separated list of default values for parameters in the format of params:value.

  4. Click Save.

Step 7: (Optional) Configure Service Access

  1. Click Service Access. Service access

  2. Enable Enable Global access to all Services and Plans if you plan to give access to all organizations and spaces.

  3. Click Save.

Step 8: Configure Stemcell

  1. Click Installation Dashboard link to return to the Installation Dashboard.

  2. Find and click Stemcell Library to navigate to the Stemcell Library Page. Stemcell

  3. If there is a notification indicating that stemcell required by SMB Volume Service is missing, you must import a specific stemcell.

    1. If PAS detects that a stemcell .tgz file is present in the BOSH Director VM* at /var/tempest/stemcells/, the Stemcell screen displays filename information and is ready to proceed.
    2. If the stemcell is not detected, download it from Pivotal Network.
      1. Login to Pivotal Network and click Stemcells.
      2. Download the required version of the stemcell targeted for your IaaS, shown in the Stemcell page of this tile.
      3. In the Stemcell section of SMB Volume Service tile, click Import Stemcell to import the .tgz stemcell you just downloaded.

Step 9: Complete Installation

  1. Click Installation Dashboard link to return to the Installation Dashboard.

  2. Check the status of the tile SMB Volume Service. If the status bar is green, proceed to the next step.
    Tile ready

  3. (Apply to OpsManager 2.3 or later only) Click Preview Pending Changes and make sure SMB Volume Service is selected.

  4. Click Apply Changes to install SMB Volume Service tile.

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