Welcome to Eden – a CLI for every Open Service Broker API

Gemalto’s https://cf-hsm.io is HSM-as-a-service with the API being the Open Service Broker API. This was fantastic as I’d been working on a CLI that interacts with any Open Service Broker API called Eden.

Welcome to Eden!

What is the Open Service Broker API?

There are a class of applications that provide a service to other applications – for example, SaaS businesses. For example, Heroku Postgres provides Postgres database service instances on demand. But to access Heroku Postgres you must use the Heroku platform; rather than directly to an API.

Conversely, Gemalto’s https://cf-hsm.io provides an API for users to provision HSM-as-a-service service instances. And instead of designing their own API, they used the Open Service Broker API specification.

A couple of example API endpoints:

• GET /v2/catalog – returns JSON describing one or more different services that the API/broker provides, and one or more service plans for each service (different plans might map to different sizes or quality of service).
• PUT /v2/service_instance/:uuid – request to provision a new service instance
• DELETE /v2/service_instance/:uuid – request to deprovision (delete) an existing service instance

It is a very simple API spec and makes a lot of sense for service providers to implement, even if it is in addition to an existing bespoke API design.

Why do I need a CLI to talk to it?

You don’t! You can interact with an Open Service Broker API service using curl or a programming language. Or if you’re using a higher level platform like Cloud Foundry then you’ll access service brokers via their UI or CLIs.

But in general we all prefer a nice CLI than manually constructing curl -X PUT -d '{...}' commands.

The eden CLI is useful for users of a service broker, and also for developers’ own dev/test. We’ve been using eden in our CI for service brokers for the last six months and it has simplified our sanity-test suites a lot.

If I use Cloud Foundry, do I need eden?

Cloud Foundry was the original user of the Open Service Broker API – all Cloud Foundry service brokers are also Open Service Brokers.

No, if you’re already accessing a service broker via cf create-service commands then you’ll continue to do so. As a user of Cloud Foundry you probably do not have direct access to service brokers at the moment.

Getting started

After installing Eden, it is very easy to configure for any target API.

For example, with https://cf-hsm.io you are presented with the administration API keys after creating an account:

To use Eden, first setup environment variables for these credentials:

EDEN_BROKER_URL=https://servicebroker.apps.cf-hsm.io/account-uuid
EDEN_BROKER_CLIENT=apikey
EDEN_BROKER_CLIENT_SECRET=apisecret

You can now view all the available services and their plans for this broker:

$ eden catalog
Service Name  Plan Name        Description
hsm           micro_partition  An even smaller partition (1024 bytes)
~             small_partition  A small partition (80000 bytes)

Next stop, "provision" one of the service planes:

$ eden provision -s hsm -p micro_partition
provision:   hsm/micro_partition - name: hsm-micro_partition-c33bb305-35c9-4488-xxx
provision:   in-progress
provision:   in progress - Provisioning service on HSM.
provision:   in progress - Provisioning service on HSM.
provision:   succeeded -
provision:   done - http://servicebroker.apps.cf-hsm.io

Finally, to generate credentials you will "bind" and then display the cached credentials:

$ eden bind -i hsm-micro_partition-c33bb305-35c9-4488-xxx
Success
Run 'eden credentials -i hsm-micro_partition-c33bb305-35c9-4488-xxx -b hsm-5c4c98d7-67f5-xxx' to see credentials
$ eden credentials -i hsm-micro_partition-c33bb305-35c9-4488-xxx -b hsm-5c4c98d7-67f5-xxx
... JSON ...

Pass this through jq to extract interesting values:

$ eden credentials -i hsm-micro_partition-c33bb305-35c9-4488-xxx -b hsm-5c4c98d7-67f5-xxx | jq -r ".servers[].name"
elab16.safenet-inc.com

Later, you can deprovision a service instance when you no longer need it:

$ eden services
... lists service instances...
$ eden deprovision -i hsm-micro_partition-c33bb305-35c9-4488-xxx

Eden is a new project and the Open Service Broker API is under new stewardship of the https://www.openservicebrokerapi.org/ community. Together we will have a great standardized API and CLI for all SaaS and on-prem services.

Alternates

Prior to this blog post I started to share eden with friends + coworkers and I was point to a similar "Service Broker CLI" project from Dmitriy Kalinin https://github.com/cppforlife/sb-cli