Pivotal/APIs/Service Broker API

APIs
Open Service Broker API

Overview

The open service broker API is used by service brokers; the brokers of services available to developers to supplement their applications.
It allows service brokers to register services, configure, manage, etc.

Manual Queries

Queries are structured like so:

~$  curl http://username:password@service-broker-url/v2/catalog -H "X-Broker-API-Version: 2.14"

The components are:

component	description
curl	command used
http://username:password	username and password for the service broker placed inline with the GET request
@service-broker-url	the service broker URL specific to the service deployed
/v2/catalog	the service broker API endpoint
-H "X-Broker-API-Version: 2.14"	A required header for the request that must declare the version number of the Open Service Broker API that the platform is using

Credentials

In order to manually query the service broker API endpoints, you will need to gather the credentials used to register the service. As of today, PAS 2.3, these credentials are stored within the BOSH credhub instance in Cloud Foundry, however they may be available from Ops Manager UI, PAS > Credentials.

Determine Credhub name

Credhub will have a fairly long string for a name, so its important that we discover what it is. From the Ops Manager VM, run the following command and it should print out the credhub variable names for the username and password.

~$ sudo cat /var/tempest/workspaces/default/deployments/credhub-service-broker*.yml | grep 'name: credhub_broker' -A 2
      name: credhub_broker
      password: "((/opsmgr/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/app_credentials.password))"
      user: "((/opsmgr/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/app_credentials.identity))"
--
      name: credhub_broker
    domain: run-19.haas-59.pez.pivotal.io
    org: credhub-service-broker-org

Credhub CLI

Before we can use the Credhub CLI, we need credentials for CredHub. In this instance we will be logging into the Credhub for BOSH, which is on the Bosh director VM.
To start, you'll need to ssh into the Ops Manager. We can run a remote ssh command from there into the Bosh Director VM to extract the username and password for credhub.

~$ ssh [email protected] 'cat /var/vcap/jobs/director/config/director.yml' | jq '.config_server.uaa.client_id,.config_server.uaa.client_secret'
Unauthorized use is strictly prohibited. All access and activity
is subject to logging and monitoring.
[email protected]'s password:
"director_to_credhub"
"client_secret_password"

Now with the credentials, we can try to connect, again from the Ops Manager vm since it already has the credhub cli installed.

~$ credhub api https://bosh_director_ip:8844 --skip-tls-validation
~$ credhub login --client-name=director_to_credhub --client-secret=client_secret_password
Login Successful

Or you can call the username and password inline to avoid having to look them up.

~$ credhub login \
--client-name=`ssh [email protected] 'cat /var/vcap/jobs/director/config/director.yml' | jq '.config_server.uaa.client_id' | sed s'/"//'g` \
--client-secret=`ssh [email protected] 'cat /var/vcap/jobs/director/config/director.yml' | jq '.config_server.uaa.client_secret' | sed s'/"//'g`
Unauthorized use is strictly prohibited. All access and activity
is subject to logging and monitoring.
[email protected]'s password:
Unauthorized use is strictly prohibited. All access and activity
is subject to logging and monitoring.
[email protected]'s password:
Login Successful

Now that we are authenticated with credhub, we can search for the desired credentials

~$ credhub find | grep -i credhub
- name: /opsmgr/director/credhub-service-broker-fe0bf86cb201f5273057/delete-all/vm_credentials
- name: /opsmgr/director/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/vm_credentials
- name: /opsmgr/director/credhub-service-broker-fe0bf86cb201f5273057/uaa_client_secret
- name: /opsmgr/director/cf-c4ad9789367ebcdd824b/credhub/vm_credentials
- name: /opsmgr/credhub-service-broker-fe0bf86cb201f5273057/delete-all/app_credentials
- name: /opsmgr/credhub-service-broker-fe0bf86cb201f5273057/delete-all/vm_credentials
- name: /opsmgr/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/app_credentials
- name: /opsmgr/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/vm_credentials
- name: /opsmgr/cf-c4ad9789367ebcdd824b/uaa/services_credhub_credentials
- name: /opsmgr/cf-c4ad9789367ebcdd824b/credhub_tls
- name: /opsmgr/cf-c4ad9789367ebcdd824b/credhub_key_encryption_passwords/0/key
- name: /opsmgr/cf-c4ad9789367ebcdd824b/credhub_hsm_provider_partition_password
- name: /opsmgr/cf-c4ad9789367ebcdd824b/credhub_hsm_provider_client_certificate
- name: /p-bosh/cf-c4ad9789367ebcdd824b/credhub-db-credentials

Since we got the name of the credentials we need earlier, this is pretty easy. remember to remove .identity or .password

~$ credhub get --name /opsmgr/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/app_credentials
id: a9b9d259-19a1-4577-9f3d-3ed42ae4580c
name: /opsmgr/credhub-service-broker-fe0bf86cb201f5273057/deploy-all/app_credentials
type: json
value:
  identity: username
  password: password
  salt: salt
  sha512_hashed_password: salted password hash
version_created_at: 2018-10-23T11:09:56Z

Query

Now we are almost ready to submit our first query, however we need to know the service broker URL we will be using. This is fairly easy with CF CLI

~$ cf service-brokers
Getting service brokers as admin...

name                         url
apigee_cf_service_broker     https://apigee-cf-service-broker.cfapps-19.haas-59.pez.pivotal.io
app-autoscaler               https://autoscale.run-19.haas-59.pez.pivotal.io
aws-services-broker          https://aws-services-broker.run-19.haas-59.pez.pivotal.io
azure_service_broker         https://azure-service-broker.cfapps-19.haas-59.pez.pivotal.io
credhub-broker               https://credhub-broker.cfapps-19.haas-59.pez.pivotal.io
dedicated-mysql-broker       http://10.193.84.55:8080
mongodb-service-broker-bjm   https://mongodb-service-broker-anxious-gelada.cfapps-19.haas-59.pez.pivotal.io
nfsbroker                    https://nfsbroker.run-19.haas-59.pez.pivotal.io
p-redis                      https://redis-broker.run-19.haas-59.pez.pivotal.io
redis-odb                    http://10.193.84.73:12345
scheduler-for-pcf            https://scheduler.run-19.haas-59.pez.pivotal.io

In the above, we can see that the credhub broker URL is:

https://credhub-broker.cfapps-19.haas-59.pez.pivotal.io

Finally we are ready to put everything together and submit a query. We are start by testing against the /v2/catalog endpoint.
NOTE: Make sure you are using HTTPS.

~$ curl https://username:[email protected]/v2/catalog -H "X-Broker-API-Version: 2.14" --insecure | jq '.'
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   581  100   581    0     0  14237      0 --:--:-- --:--:-- --:--:-- 14897
{
  "services": [
    {
      "id": "E70C96CA-88E2-4FE9-9157-EFC835A38C9F",
      "name": "credhub",
      "description": "Stores configuration parameters securely in CredHub",
      "bindable": true,
      "tags": [
        "credhub"
      ],
      "plan_updateable": true,
      "plans": [
        {
          "id": "6D7F1C1B-EC2C-4A99-86B0-08E1987EE5A6",
          "name": "default",
          "description": "Stores configuration parameters securely in CredHub",
          "metadata": {
            "bullets": [
              "Stores configuration parameters securely in CredHub"
            ],
            "displayName": "default"
          }
        }
      ],
      "metadata": {
        "displayName": "credhub-broker",
        "longDescription": "Stores configuration parameters securely in CredHub",
        "shareable": true
      }
    }
  ]
}

Data Storage

The data you obtain from the Service Broker API comes from (at the time of this writing, PAS 2.3) the MySQL DB on the MySQL VM within the CF Deployment, and then specifically the CCDB database.
Start by ssh'ing into the MySQL vm

~$ bosh -e lab19 -d cf-c4ad9789367ebcdd824b ssh mysql/44aee7c1-fa49-471d-ab66-64c5f278f4a9

Now lets log into MySQL. we can use credentials stored on the MySQL vm.

~$ mysql --defaults-file=/var/vcap/jobs/mysql/config/mylogin.cnf -h 127.0.0.1

Once logged in, you can perform a variety of commands to query information, but in the case of this exercise, these are what we used.

mysql> show databases;
mysql> use ccdb;
mysql> show tables;
mysql> describe services;
mysql> select guid,label,extra,service_broker_id from services where label='credhub';

In the above we wanted to look at the DB entries for the credhub service broker and see what sort of JSON the extra column contained.

Note: You could also use the Database entries in the CCDB to determine the username (but not password) for the service broker API. Just FYI that it is here too, not just in the previously mentioned .yml.

Reference

https://pivotal.lightning.force.com/lightning/r/KnowledgeArticle__kav/ka00P0000009KJHQA2/view

References

If you want further information about the available endpoints, these are the best resources out there:
http://petstore.swagger.io/?url=https://raw.githubusercontent.com/openservicebrokerapi/servicebroker/v2.14/openapi.yaml
https://github.com/openservicebrokerapi/servicebroker/blob/v2.14/spec.md