Open Service Broker Reference App

Overview

Every service onboarding in IBM Cloud Catalog requires to build a broker app that follow the Open Service Broker (OSB) spec. This project provides an quick setup reference broker implementation.

As you onboard through Partner Center , you will be required to provide your broker app URL. This readme provides a step by step guide on how to configure and deploy a reference broker app that hooks up to your service and helps you test an end to end flow early in the onboarding process. This is all done with the help of the CLI makefile automation that performs the following tasks for you:

• builds the Java based OSB broker code using maven
• builds a docker container image of the OSB broker app,
• creates an IBM Container Registry (ICR) namespace (if it does exist) and uploads the image to the ICR namesapce
• deploys the app on IBM Code Engine

Note that this broker is not recommended to be used in production. It to be used as a reference to help you build your production broker

Whats is an Onboarding and a Deployment IBM Cloud Account

In the sections to follow you will come across many references to Onboarding and Deployment IBM Cloud account. This section tries do demystify the two.

Onboarding IBM Cloud Account

is the IBM Cloud account under which your service is being onboarded. The will be the cloud account selection when you are working with Partner Center.

Note to IBMers: If you are an IBMers, very likely while you will be onboarding via test.cloud.ibm.com, your Deployment IBM Cloud account MUST be cloud.ibm.com.

Deployment IBM Cloud Account

is the cloud account under which you will be deploying your broker app using Code Engine. You Deployment Cloud Account could be same as your Onboarding Cloud account as long as the account is on cloud.ibm.com (IBM Cloud Production)

Note to IBMers: The Deployment cloud account MUST be an account in cloud.ibm.com and NOT in test.cloud.ibm.com or any other flavor of IBM cloud. This implies, the IBM Container registry, namespace and the IBM Code Engine app to be deployed in the sections to follow have to be on cloud.ibm.com

Prerequisites

1. Docker setup locally on your computer

2. IBM Cloud Access

   The following privileges are required

   1. You have to be invited to the IBM Cloud account where the service is being on-boarded

   2. You will need the following access in the Deployment IBM Cloud Account

      a. Writer and Editor access to IBM Container Registry

      b. Editor access to IBM Cloud Code Engine

      Search your user and verify you have the required access here

   3. You have to be added to the service in the Global catalog (via the Visibility tab in the UI)

Create IBM Cloud API keys

The project expects 3 IBM Cloud API keys. Two are covered in this section and the third one in the next section.

• ONBOARDING_IAM_API_KEY

  is the API key created in cloud account where the SaaS service is being onboarded via Partner Center. The API key will used to access Global Catalog API

• DEPLOYMENT_IAM_API_KEY

  is the IBM cloud API key created in cloud account where the broker is to be deployed. The API key (and therefore the user owning the API key) must have the following access in the Deployment IBM Cloud Account

  a. Writer and Editor access to IBM Container Registry

  b. Editor access to IBM Cloud Code Engine

  Find your user and verify you have the required access here

  You may follow this document to create the API keys. Once created, save the API key values to a safe location on your local machine.

• METERING_API_KEY

  The Reference Broker provides a dashboard that allows you to send test metering data to BSS for your service. To be able to do so your metering Service ID and API key need to be setup.
  If you are onboarding via Partner Center,

  • Navigating to My products -> Dashboard
  • Click on the Create Service ID button
  • Create an API key for the Service ID using the Create API key link on the same page.

  Note down the API Key as this will be used as METERING_API_KEY during the deploy step

Building the Broker

1. Clone the repo and cd into the directory

git clone https://github.com/IBM-Cloud/onboarding-osb.git
cd onboarding-osb

2. Complete the deploy/build.config.properties config

Complete the properties file with the instructions provided below and export as environment variables

• ONBOARDING_ENV

  • is set to stage if the IBM Cloud Onboarding is on test.cloud.ibm.com (used by IBMers) or prod if the IBM Cloud Onboarding is on cloud.ibm.com

• GC_OBJECT_ID

  • In Partner Center, this value can be found in the Brokers tab. Additional help is available by clicking the Open the guide button in the Broker tab

• BROKER_ICR_NAMESPACE_URL

  • This is the IBM Container Registry namespace in the Deployment Cloud Account where the OSB container image will be uploaded. You may choose one of the available namespaces here

    If you do not want to use an exisitng namespace, simply provide a unique name and the automation will create one for you. If you would like to create it manually please follow these instructions and provide the name

  • eg. us.icr.io/yournamespace

• ICR_IMAGE

  • is the name for the broker container image that will be pushed on ICR namespace in the Deployment Cloud Account

    eg. broker-img

• ICR_NAMESPACE_REGION

  • is the region in which the namespace is created (or is to be created). The region can be found here

    eg. us-south for Dallas, eu-central for Frankfurt

• ICR_RESOURCE_GROUP

  • is the resource group under which ICR namespace exists (or will be created). The resource group name can be found here eg. Default
  
  

3. Set the variables in your environment using:

export $(cat deploy/build.config.properties)

4. Build the broker:

Running the below command in your terminal will maven build your broker, package it as a container image and upload it to IBM Container Registry in the namespace you provided.

DEPLOYMENT_IAM_API_KEY=replace-with-your-DEPLOYMENT_IAM_API_KEY ONBOARDING_IAM_API_KEY=replace-with-your-ONBOARDING_IAM_API_KEY make build

Note: When prompted, enter your local computer's password.

Congratulations! We now have the broker application image.
Log in to IBM Cloud and look under ICR namespaces to find your image.

Our next step now is to deploy the broker application image we just created. The CLI tool we provide supports deployment to IBM Cloud Code Engine. Based on the platform of your choice, just to the next appropriate section section

Deploying the Broker on IBM Cloud Code Engine

1. Complete the deploy/ce/ce.config.properties config

Complete the properties file with the instructions provided below and export as environment variables

• APP_NAME

  • is the application name you would like to give the broker on Code Engine. Try using a unique identifier in the name so that you dont run into conflicts.

• ONBOARDING_ENV

  • is set to stage if the IBM Cloud Onboarding is on test.cloud.ibm.com (used by IBMers) or prod if the IBM Cloud Onboarding is on cloud.ibm.com

• BROKER_USERNAME

  • is the username you would like to set for the Broker

• BROKER_PASSWORD

  • is the password you would like to set for the Broker

  Note: The BROKER_USERNAME and BROKER_PASSWORD values provided here also need to be configured in Partner Center when publishing the broker.

• BROKER_ICR_NAMESPACE_URL

  • use the same namespace URL provided in deploy/build.config.properties during the build step
  • eg. us.icr.io/yournamespace

• ICR_IMAGE

  • use the same image name provided in deploy/build.config.properties during the build step

• CE_PROJECT

  • Select a project from the list of available projects. You can create a new one yourself or give us a name and we will create one for you.

• CE_REGION

  • Set region for IBM Code Engine deployment. This is value in the Location column from the list of available projects you would be using to create the app into.

• CE_RESOURCE_GROUP

  • Select resource group to target for IBM Code Engine. This is value in the Resource group column from the list of available projects you would be using to create the app into.

• CE_REGISTRY_SECRET_NAME

  • Select an exisitg registry access from your project or create one

• PC_URL [optional]

  • Partner Center url for dashboard. use this to see your applications and copy url.

2. Export the variables in your environment

export $(cat deploy/ce/ce.config.properties)

3. Deploy to IBM Code Engine

Running the below command in your terminal will deploy your app to IBM Code Engine. If you have not yet created the required API keys refer to section on IBM Cloud API keys

DEPLOYMENT_IAM_API_KEY=replace-with-your-DEPLOYMENT_IAM_API_KEY  METERING_API_KEY=your-replace-with-your-METERING_API_KEY make deploy-ce

Building and deploying in a single command

The CLI tool also provides a single command that both builds and deploys the the broker app

For Code Engine:

DEPLOYMENT_IAM_API_KEY=replace-with-your-DEPLOYMENT_IAM_API_KEY ONBOARDING_IAM_API_KEY=replace-with-your-ONBOARDING_IAM_API_KEY METERING_API_KEY=your-replace-with-your-METERING_API_KEY make build-deploy-ce

Testing the broker

• Download the postman_collection.json and import into your postman to test out the APIs
• Modify the planID and ServiceID in the postman collection to match your service

Guide for ui changes

see this