OpenShift: Getting Started with the Service Broker

12 minute read



In this article we will look at the OpenShift service broker, understand how to integrate external services into OpenShift and even create a custom broker. First before we begin a big thanks to Marek Jelen and Paul Morie, Red Hatters who both helped me understand the service broker in greater detail.

Obviously if you are reading this article you already understand microservices, containers and why it is all so incredible awesome on OpenShift. Of course everything should be in a container but unfortunately it is going to take a while to get there. As we start dissecting and breaking down the monolithic architectures of the past, likely there will be a mix of lightweight services running in containers on OpenShift and other more heavy services (databases, ESBs, etc) running outside. In addition while the service catalog in OpenShift is vast, even allowing you to add your own custom services for anything that can run in OpenShift as-a-container using a template, there will be the need, especially with public cloud to connect to external services. Both of these use cases, on-premise external services and off-premise cloud services really made it obvious that a service broker and more robust service catalog was needed. Originally OpenShift did not have a service broker so you couldn't easily consume external services. All that existed was the service catalog and templates, so every service had to be a container running on OpenShift. Thankfully other companies also saw a need for an open service abstraction and the Open Service Broker API was born as an opensource project.

Service Catalog API, Controller and Broker

Red Hat quickly adopted the open service broker API as the basis for the service broker in OpenShift. A service broker is simply an endpoint that manages a set of services. Of course this wasn't enough, in addition the service catalog had to be re-worked in Kubernetes. The service catalog API and controller were added into the existing service catalog to provide the necessary abstraction that would allow all services to be represented by a broker or API endpoint.


image source:

Since OpenShift 3.7 this has been GA and all services are provided by a broker including the built-in OpenShift services. OpenShift comes with two built-in service brokers. The template service broker and the Ansible service broker.

List cluster service brokers.

[cloud-user@master0 ~]$ oc get clusterservicebroker
ansible-service-broker 72d
template-service-broker 72d

The template service broker provides services to service catalog that are templates. Think of this was as the original service catalog with an API. If you can run the service as-a-container on OpenShift you would likely just create a template under the openshift project, no need for custom broker there.

View all templates part of service catalog.

[cloud-user@master0 ~]$ oc get templates -n openshift

The Ansible service broker was also added to OpenShift and allows you to do something similar to template service broker, only using Ansible. The ASB though, unlike the template service broker enables you to connect services that are outside of OpenShift. You just need to create a playbook. The main idea or use case here is around infrastructure provisioning or setup. Using the ASB you can easily launch instances, applications, services on infrastructure platforms outside OpenShift. Maybe your developers need a load balancer, provision a database outside OpenShift, etc. Anything is possible. Likely if that is what you are trying to do you would use the ASB, no need for custom service broker.

Red Hat is also adding service brokers for the public cloud providers like AWS, Azure and GCE. So out-of-the-box you will be able to natively interface with public cloud services from directly inside OpenShift. You are probably thinking, well this is awesome, I don't need anything else. You are probably right, but just in case you might actually want to create your own service broker endpoint, for example gain fine granular control over a service, let's look at how to do it.

Building Customer Service Broker

We will now create a custom service broker using a project I cloned from Marek Jelen.

Login in as user with cluster-admin role.

[cloud-user@master0 ~]$ oc whoami

Add cluster-admin role to user if missing.

[cloud-user@master0 ~]$ oc adm policy add-cluster-role-to-user \
cluster-admin admin

Create new project.

[cloud-user@master0 ~]$ oc new-project custom-broker

Create service account with cluster-admin permission.

In order to provision services, certain privileges are required to do so on behalf of other users. To make things easy just make service account cluster-admin.

[cloud-user@master0 ~]$ oc adm policy add-cluster-role-to-user \
cluster-admin system:serviceaccount:custom-broker:default

Launch Service Broker.

The service broker in this case is written in ruby and is just really an example, not a proper implementation to follow. While you can use any language, go would be more ideal. I recommend checking out the open service broker starter pack Paul Morie provides

[cloud-user@master0 ~]$ oc new-app --name broker \

Expose service broker service.

[cloud-user@master0 ~]$ oc expose svc broker

Get broker service route.

Note the route, you need to provide that in the cluster service broker.

[cloud-user@master0 ~]$ oc get routes
broker broker 8080-tcp None

Create cluster service broker.

You can also get example of broker.yaml from

[cloud-user@master0 ~]$ vi broker.yaml
kind: ClusterServiceBroker
  name: summit-broker
[cloud-user@master0 ~]$ oc create -f broker.yaml

Create a workshop service using broker.

The service we will create are simply the directions on how to create the service broker called workshop. After creating the cluster service broker, the workshops service should now be visible in OpenShift service catalog (this may take several minutes to update, you can force update though). Once it is visible, simply click the service, create a new project for it, add a GUID (can be anything) and the service will be provisioned using the new service broker.

Force update of broker.

Simply increment the number of the relistRequest to force update.

[cloud-user@master0 ~]$ oc edit clusterservicebroker summit-broker


  relistRequests: 2


Find workshops service under 'other' in service catalog.


Select workshops service.


Provide a project, GUID and off you go.


Of course you can also use the CLI to provision a service using the broker.

Create service instance of workshops service.

[cloud-user@master0 ~]$ vi blablaServiceInstance.yaml
kind: ServiceInstance
  name: workshops-q74t
  clusterServiceClassExternalName: workshops
  clusterServicePlanExternalName: workshop
    GUID: blabla


[cloud-user@master0 ~]$ of create -f blablaServiceInstance.yaml

Expose workshop service.

Expose the provisioned workshop service to access it.

[cloud-user@master0 ~]$ oc project my-custom-service1
[cloud-user@master0 ~]$ oc expose svc workshop
[cloud-user@master0 ~]$ oc get routes
broker broker 8080-tcp None
workshop workshop 8080 None

Access workshop service via browser.


In this article we discussed the value of service abstraction and the need to integrate external services in OpenShift. We reviewed the OpenShift service catalog architecture and the open service broker API. Finally using a practical example, we built our own custom service broker and provisioned a service via the UI and CLI. Obviously this is just a starting point to understand the service broker and service catalog components in OpenShift. If this is interesting I encourage you to look into starter pack provided by Paul Morie. This will get you started building your own custom brokersservice broker


Happy Brokering of Services on OpenShift!

(c) 2018 Keith Tenzer