Using Azure Service Broker

This topic describes how to use Azure Service Broker.

Before performing the procedures in this topic, ensure that you have installed the Cloud Foundry Command Line Interface (cf CLI).

List Services

  1. In a terminal window, run cf marketplace to list all the service offerings from Azure Service Broker.

  2. Run cf marketplace -s SERVICE to view the descriptions for the plans of a service.

Note: See the Azure Pricing topic to view pricing details for each service.

Create Service Instances

This section describes how to create service instances for the services offered by Azure Service Broker.

Azure Storage

Create

To create an Azure storage service instance named mystorage with the standard plan, run the following command:

$ cf create-service azure-storage standard mystorage

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-storage standard mystorage -c storage-example-config.json

The contents of storage-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "storageAccountName": "generated-string",
  "location": "eastus",
  "accountType": "Standard_LRS"
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure Storage Service.

Bind

Bind the service instance mystorage to an app with the following command:

$ cf bind-service myapp mystorage

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-storage": [
    {
      "credentials": {
        "primary_access_key": "PRIMARY-ACCOUNT-KEY",
        "secondary_access_key": "SECONDARY-ACCOUNT-KEY",
        "storage_account_name": "ACCOUNT-NAME"
      }
    }
  ]
}

You can get the credentials from the ENV['VCAP_SERVICES'] environment variable.

Note: Run cf unbind-service to delete the binding.

Azure Redis Cache

Create

To create an Azure Redis Cache service instance named myrediscache with the standard plan, run the following command:

$ cf create-service azure-rediscache basic myrediscache

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-rediscache basic myrediscache -c rediscache-example-config.json

The contents of rediscache-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "location": "eastus",
  "cacheName": "generated-string",
  "parameters": {
    "enableNonSslPort": false
  }
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure Redis Cache Service.

Bind

Bind the service instance myrediscache to an app by running the following command:

$ cf bind-service myapp myrediscache

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-rediscache": [
    {
      "credentials": {
        "hostname": ".redis.cache.windows.net",
        "name": "",
        "port": 6379,
        "primaryKey": "",
        "secondaryKey": "",
        "sslPort": 6380
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure DocumentDB

Create

To create an Azure DocumentDB service instance named mydocdb with the standard plan, run the following command:

$ cf create-service azure-documentdb standard mydocdb

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-documentdb standard mydocdb -c documentdb-example-config.json

The contents of documentdb-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "docDbAccountName": "generated-string",
  "docDbName": "generated-string",
  "location": "eastus"
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure DocumentDB.

Update

Update Non-SSL Port Setting

Running cf update-service myredis -c config.json. Content of config.json:

{
  "parameters": {
    "enableNonSslPort": true | false
  }
}
Update Service Plan

To change the amount of resources allocated to the service instance, do the following:

  1. Retrieve the name of the desired new service plan from cf marketplace.

  2. Change the service plan by running cf update-service myredis -p standardc0.

Note: You cannot change tier family and capacity at the same time in one single request per the limitation of Azure Redis service. For example, you can update from basicc0 to standardc0. But you cannot update from basicc0 to standardc1. You must update from basicc0 to standardc0, then from standardc0 to standardc1.

Bind

Bind the service instance mydocdb to an app by running the following command:

$ cf bind-service myapp mydocdb

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-documentdb": [
    {
      "credentials": {
        "documentdb_host_endpoint": "https://YOUR_DOCUMENTDB_NAME.documents.azure.com:443/",
        "documentdb_master_key": "YOUR_SECRET_KEY_ENDING_IN_==",
        "documentdb_database_id": "YOUR_DOCUMENTDB_NAME",
        "documentdb_database_link": "dbs/ID_ENDING_IN_==/"
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure Service Bus

Create

To create an Azure Service Bus service instance named myservicebus with the standard planAzure Redis Cache Service, run the following command:

$ cf create-service azure-servicebus standard myservicebus

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-servicebus standard myservicebus -c servicebus-example-config.json

The contents of servicebus-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "namespaceName": "generated-string",
  "location": "eastus"
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure Service Bus.

Bind

Bind the service instance myservicebus to an app by running the following command:

$ cf bind-service myapp myservicebus

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-servicebus": [
    {
      "credentials": {
        "namespace_name": "cf-2eac2d52-bfc9-4d0f-af28-c02187689d72",
        "key_name": "KEY-NAME",
        "key_value": "KEY-VALUE",
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure Event Hubs

Create

To create an Azure Event Hubs service instance named myeventhubs with the standard plan, run the following command:

$ cf create-service azure-eventhubs standard myeventhubs

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-eventhubs standard myeventhubs -c eventhubs-example-config.json

The contents of eventhubs-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "namespaceName": "generated-string",
  "location": "eastus",
  "eventHubProperties": {
    "messageRetentionInDays": 7,
    "partitionCount": 4
  }
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure Event Hubs.

Bind

Bind the service instance myeventhubs to an app by running the following command:

$ cf bind-service myapp myeventhubs

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-servicebus": [
    {
      "credentials": {
        "namespace_name": "cf-2eac2d52-bfc9-4d0f-af28-c02187689d72",
        "key_name": "KEY-NAME",
        "key_value": "KEY-VALUE",
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure SQL Database

Create

To create an Azure SQL Database service instance named mysqldb with the basic plan, run the following command:

$ cf create-service azure-sqldb basic mysqldb

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-sqldb basic mysqldb -c sqldb-example-config.json

The contents of sqldb-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "location": "eastus",
  "sqlServerName": "generated-string",
  "sqlServerParameters": {
      "allowSqlServerFirewallRules": [
          {
              "ruleName": "all",
              "startIpAddress": "0.0.0.0",
              "endIpAddress": "255.255.255.255"
          }
      ],
      "properties": {
          "administratorLogin": "generated-string",
          "administratorLoginPassword": "generated-string"
      }
  },
  "sqldbName": "generated-string",
  "transparentDataEncryption": true,
  "sqldbParameters": {
      "properties": {
          "collation": "SQL_Latin1_General_CP1_CI_AS"
      }
  }
}

To create an Azure SQL Database service instance named mysqldb on the SQL server named sqlservera with the basic plan, run the following command:

$ cf create-service azure-sqldb basic mysqldb -c '{"sqlServerName": "sqlservera"}'

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-sqldb basic mysqldb -c sqldb-example-config.json
{
  "sqlServerName": "sqlservera",
  "sqldbName": "generated-string",
  "transparentDataEncryption": true,
  "sqldbParameters": {
      "properties": {
          "collation": "SQL_Latin1_General_CP1_CI_AS"
      }
  }
}

The value generated-string indicates the corresponding parameter can be generated by the broker if Allow to Generate Names and Passwords for the Missing is enabled in the broker configuration.

For more information, see Azure SQL Database.

Update

Update Credentials

If the SQL server credentials are modified, the service broker must be informed of the change, or binding operations will fail.

As an Admin Using Ops Manager
  1. Modify the SQL server password in SQL Database Config.

  2. Apply the changes.

As a Developer Using cf update
  1. Modify the config.json file used to create the service instance.

    {
    'sqlServerParameters': {
    'properties': {
      'administratorLoginPassword': 'newPassword425'
    }
    }
    }
    

  2. Inform the broker by running cf update-service mydb -c config.json.

Update the Service Plan

To change the amount of resources allocated to the service instance, do the following:

  1. Retrieve the name of the desired new service plan from cf marketplace.

  2. Change the service plan by running cf update-service mysqldb -p StandardS0.

Note: Certain updates are not possible. For example, it is not possible to update from a standard plan to a datawarehouse one.

Bind

Bind the service instance mysqldb to an app by running the following command:

$ cf bind-service myapp mysqldb

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-sqldb": [
    {
      "credentials": {
        "sqldbName": "fake-database",
        "sqlServerName": "fake-server",
        "sqlServerFullyQualifiedDomainName": "fake-server.database.windows.net",
        "databaseLogin": "ulrich",
        "databaseLoginPassword": "u1r8chP@ss",
        "jdbcUrl": "jdbc:sqlserver://fake-server.database.windows.net:1433;database=fake-database;user=fake-admin;password=fake-password;Encrypt=true;TrustServerCertificate=false;HostNameInCertificate=*.database.windows.net;loginTimeout=30",
        "jdbcUrlForAuditingEnabled": "jdbc:sqlserver://fake-server.database.secure.windows.net:1433;database=fake-database;user=fake-admin;password=fake-password;Encrypt=true;TrustServerCertificate=false;HostNameInCertificate=*.database.secure.windows.net;loginTimeout=30",
        "hostname": "fake-server.database.windows.net",
        "port": 1433,
        "name": "fake-database",
        "username": "ulrich",
        "password": "u1r8chP@ss",
        "uri": "mssql://ulrich:u1r8chP@ss@fake-server.database.windows.net:1433/fake-database?encrypt=true&TrustServerCertificate=false&HostNameInCertificate=*.database.windows.net"
      }
    }
  ]
}

You can use jdbcUrlForAuditingEnabled to connect to the database if auditing is enabled. For more information, see SQL Database - Downlevel clients support and IP endpoint changes for Table Auditing.

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure SQL Database Failover Group

In this module, both the primary server and the secondary server should be provided in SQL Database Config. The primary database should also exist. You can create the the primary database with Azure SQL Database module.

Create

To create an secondary database and a failover group service instance named mysqldbfg with the SecondaryDatabaseWithFailoverGroup plan, run the following command:

$ cf create-service azure-sqldbfg SecondaryDatabaseWithFailoverGroup mysqldbfg -c sqldbfg-example-config.json

The contents of sqldbfg-example-config.json are as follows:

{
  "primaryServerName": "sqlservera",
  "primaryDbName": "sqldba",
  "secondaryServerName": "sqlserverb",
  "failoverGroupName": "failovergroupa"
}

Note: You can use the plan `ExistingDatabaseInFailoverGroup` to register a failover group as a service instance. Deleting the service instance does not delete the failover group.

For more information, see Azure SQL Database Failover Group.

Bind

Bind the service instance mysqldbfg to an app by running the following command:

$ cf bind-service myapp mysqldbfg

The credentials have the following format, keeping a consistent format with the credentials of azure-sqldb but assigning the failover group name as the SQL server name:

"VCAP_SERVICES": {
  "azure-sqldb": [
    {
      "credentials": {
        "sqldbName": "sqldba",
        "sqlServerName": "failovergroupa",
        "sqlServerFullyQualifiedDomainName": "failovergroupa.database.windows.net",
        "databaseLogin": "ulrich",
        "databaseLoginPassword": "u1r8chP@ss",
        "jdbcUrl": "jdbc:sqlserver://failovergroupa.database.windows.net:1433;database=sqldba;user=fake-admin;password=fake-password;Encrypt=true;TrustServerCertificate=false;HostNameInCertificate=*.database.windows.net;loginTimeout=30",
        "jdbcUrlForAuditingEnabled": "jdbc:sqlserver://failovergroupa.database.secure.windows.net:1433;database=sqldba;user=fake-admin;password=fake-password;Encrypt=true;TrustServerCertificate=false;HostNameInCertificate=*.database.secure.windows.net;loginTimeout=30",
        "hostname": "failovergroupa.database.windows.net",
        "port": 1433,
        "name": "sqldba",
        "username": "ulrich",
        "password": "u1r8chP@ss",
        "uri": "mssql://ulrich:u1r8chP@ss@failovergroupa.database.windows.net:1433/sqldba?encrypt=true&TrustServerCertificate=false&HostNameInCertificate=*.database.windows.net"
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure Database for MySQL

Create

To create an Azure Database for MySQL service instance named mysqldb with the basic100 plan, run the following command:

$ cf create-service azure-mysqldb basic100 mysqldb

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-mysqldb basic100 mysqldb -c mysqldb-example-config.json

The contents of mysqldb-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "location": "eastus",
  "mysqlServerName": "generated-string",
  "mysqlServerParameters": {
      "allowMysqlServerFirewallRules": [
          {
            "ruleName": "all",
            "startIpAddress": "0.0.0.0",
            "endIpAddress": "255.255.255.255"
          }
      ],
      "properties": {
          "version": "5.6",
          "sslEnforcement": "Disabled",
          "storageMB": 51200,
          "administratorLogin": "generated-string",
          "administratorLoginPassword": "generated-string"
      }
  }
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure MySQL Database.

Bind

Bind the service instance mysqldb to an app by running the following command:

$ cf bind-service myapp mysqldb

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-mysqldb": [
    {
      "credentials": {
        "mysqlServerName": "mysqlservera",
        "mysqlDatabaseName": "mysqldba",
        "mysqlServerFullyQualifiedDomainName": "mysqlservera.mysql.database.azure.com",
        "administratorLogin": "ulrich",
        "administratorLoginPassword": "u1r8chP@ss",
        "jdbcUrl": "jdbc:mysql://mysqlservera.mysql.database.azure.com:3306/mysqldba?user=&password=&verifyServerCertificate=true&useSSL=true&requireSSL=false",
        "hostname": "mysqlservera.mysql.database.azure.com",
        "port": 3306,
        "name": "mysqldba",
        "username": "ulrich@mysqlservera",
        "password": "u1r8chP@ss",
        "uri": "mysql://ulrich%40mysqlservera:u1r8chP@ss@mysqlservera.mysql.database.azure.com:3306/mysqldba?ssl=true"
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure Database for PostgreSQL

Create

To create an Azure Database for PostgreSQL service instance named postgresqldb with the basic100 plan, run the following command:

$ cf create-service azure-postgresqldb basic100 postgresqldb

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-postgresqldb basic100 postgresqldb -c postgresqldb-example-config.json

The contents of postgresqldb-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "location": "eastus",
  "postgresqlServerName": "generated-string",
  "postgresqlServerParameters": {
      "allowPostgresqlServerFirewallRules": [
          {
            "ruleName": "all",
            "startIpAddress": "0.0.0.0",
            "endIpAddress": "255.255.255.255"
          }
      ],
      "properties": {
          "version": "9.6",
          "sslEnforcement": "Disabled",
          "storageMB": 51200,
          "administratorLogin": "generated-string",
          "administratorLoginPassword": "generated-string"
      }
  }
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure Database for PostgreSQL Service.

Bind

Bind the service instance postgresqldb to an app by running the following command:

$ cf bind-service myapp mysqldb

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-postgresqldb": [
    {
      "credentials": {
        "postgresqlServerName": "postgresqlservera",
        "postgresqlDatabaseName": "postgresqldba",
        "postgresqlServerFullyQualifiedDomainName": "postgresqlservera.postgres.database.azure.com",
        "administratorLogin": "ulrich",
        "administratorLoginPassword": "u1r8chP@ss",
        "jdbcUrl": "jdbc:postgresql://postgresqlservera.postgres.database.azure.com:5432/postgresqldba?user=ulrich@fake-server&password=u1r8chP@ss&ssl=true",
        "hostname": "postgresqlservera.postgres.database.azure.com",
        "port": 5432,
        "name": "postgresqldba",
        "username": "ulrich@postgresqlservera",
        "password": "u1r8chP@ss",
        "uri": "postgres://ulrich%40postgresqlservera:u1r8chP@ss@postgresqlservera.postgres.database.azure.com:5432/postgresqldba"
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Azure CosmosDB

Create

To create an Azure CosmosSQL service instance named cosmosdb with the standard plan, run the following command:

$ cf create-service azure-cosmosdb standard cosmosdb

To create a service instance with custom parameters, run the following command:

$ cf create-service azure-cosmosdb standard cosmosdb -c cosmosdb-example-config.json

The contents of cosmosdb-example-config.json are as follows:

{
  "resourceGroup": "azure-service-broker",
  "cosmosDbAccountName": "generated-string",
  "cosmosDbName": "generated-string",
  "location": "eastus",
  "kind": "DocumentDB"
}

The value generated-string indicates the corresponding parameter can be generated by the broker if the Allow to Generate Names and Passwords for the Missing checkbox is enabled in the broker configuration.

For more information, see Azure CosmosDB Service.

Bind

Bind the service instance postgresqldb to an app by running the following command:

$ cf bind-service myapp mysqldb

The credentials have the following format:

"VCAP_SERVICES": {
  "azure-cosmosdb": [
    {
      "credentials": {
        "cosmosdb_host_endpoint": "https://YOUR_COSMOSDB_ACCOUNT_NAME.documents.azure.com:443/",
        "cosmosdb_master_key": "YOUR_SECRET_KEY_ENDING_IN_==",
        "cosmosdb_readonly_master_key": "YOUR_READONLY_SECRET_KEY_ENDING_IN_==",
        "cosmosdb_database_id": "YOUR_COSMOSDB_NAME",
        "cosmosdb_database_link": "dbs/ID_ENDING_IN_==/"
      }
    }
  ]
}

For MongoDB, the credentials have the following format:

"VCAP_SERVICES": {
  "azure-cosmosdb": [
    {
      "credentials": {
        "cosmosdb_host_endpoint": "https://YOUR_COSMOSDB_ACCOUNT_NAME.documents.azure.com:10255/",
        "cosmosdb_username": "YOUR_COSMOSDB_ACCOUNT_NAME",
        "cosmosdb_password": "YOUR_PASSWORD_ENDING_IN_==",
        "cosmosdb_database_name": "YOUR_COSMOSDB_NAME",
        "cosmosdb_connection_string": "mongodb://:@?ssl=true&replicaSet=globaldb"
      }
    }
  ]
}

You can get the credentials from ENV['VCAP_SERVICES'].

Note: Run cf unbind-service to delete the binding.

Delete a Service Instance

Note: Before deleting a service instance, ensure there are no apps bound to the service instance and no data contained within, such as objects in a storage account.

To delete a service instance, run the following command:

$ cf delete-service YOUR-SERVICE-INSTANCE
Really delete the service YOUR-SERVICE-INSTANCE> y
Deleting service YOUR-SERVICE-INSTANCE in org system / space dev1 as appdev1...
OK
Delete in progress. Use 'cf services' or 'cf service YOUR-SERVICE-INSTANCE' to check operation status.
Create a pull request or raise an issue on the source for this page in GitHub