Chapter 4. Service brokers

4.1. Installing the service catalog

Important

The service catalog is deprecated in OpenShift Container Platform 4. Equivalent and better functionality is present in the Operator Framework and Operator Lifecycle Manager (OLM).

4.1.1. About the service catalog

When developing microservices-based applications to run on cloud native platforms, there are many ways to provision different resources and share their coordinates, credentials, and configuration, depending on the service provider and the platform.

To give developers a more seamless experience, OpenShift Container Platform includes a service catalog, an implementation of the Open Service Broker API (OSB API) for Kubernetes. This allows users to connect any of their applications deployed in OpenShift Container Platform to a wide variety of service brokers.

The service catalog allows cluster administrators to integrate multiple platforms using a single API specification. The OpenShift Container Platform web console displays the cluster service classes offered by service brokers in the service catalog, allowing users to discover and instantiate those services for use with their applications.

As a result, service users benefit from ease and consistency of use across different types of services from different providers, while service providers benefit from having one integration point that gives them access to multiple platforms.

The service catalog is not installed by default in OpenShift Container Platform 4.

4.1.2. Installing service catalog

If you plan on using any of the services from the OpenShift Ansible Broker or Template Service Broker, you must install the service catalog by completing the following steps.

The custom resources for the service catalog’s API server and controller manager are created by default in OpenShift Container Platform, but initially have a managementState of Removed. To install the service catalog, you must change the managementState for these resources to Managed.

Procedure

  1. Enable the service catalog API server:

    1. Use the following command to edit the service catalog API server resource:

      $ oc edit servicecatalogapiservers
    2. Under spec, set the managementState field to Managed:

      spec:
        logLevel: Normal
        managementState: Managed
    3. Save the file to apply the changes.

      The Operator installs the service catalog API server component. As of OpenShift Container Platform 4, this component is installed into the openshift-service-catalog-apiserver namespace.

  2. Enable the service catalog controller manager:

    1. Use the following command to edit the service catalog controller manager resource:

      $ oc edit servicecatalogcontrollermanagers
    2. Under spec, set the managementState field to Managed:

      spec:
        logLevel: Normal
        managementState: Managed
    3. Save the file to apply the changes.

      The Operator installs the service catalog controller manager component. As of OpenShift Container Platform 4, this component is installed into the openshift-service-catalog-controller-manager namespace.

4.1.3. Uninstalling service catalog

To uninstall the service catalog, you must change the managementState for the service catalog’s API server and controller manager resources from Managed to Removed.

Procedure

  1. Disable the service catalog API server:

    1. Use the following command to edit the service catalog API server resource:

      $ oc edit servicecatalogapiservers
    2. Under spec, set the managementState field to Removed:

      spec:
        logLevel: Normal
        managementState: Removed
    3. Save the file to apply the changes.
  2. Disable the service catalog controller manager:

    1. Use the following command to edit the service catalog controller manager resource:

      $ oc edit servicecatalogcontrollermanagers
    2. Under spec, set the managementState field to Removed:

      spec:
        logLevel: Normal
        managementState: Removed
    3. Save the file to apply the changes.
Important

There is a known issue related to projects getting stuck in a "Terminating" state when attempting to delete them after disabling the service catalog. See the OpenShift Container Platform 4.1 Release Notes for a workaround. (BZ#1746174)

4.2. Installing the Template Service Broker

You can install the Template Service Broker to gain access to the template applications that it provides.

Important

The Template Service Broker is deprecated in OpenShift Container Platform 4. Equivalent and better functionality is present in the Operator Framework and Operator Lifecycle Manager (OLM).

4.2.1. About the Template Service Broker

The Template Service Broker gives the service catalog visibility into the default Instant App and Quickstart templates that have shipped with OpenShift Container Platform since its initial release. The Template Service Broker can also make available as a service anything for which an OpenShift Container Platform template has been written, whether provided by Red Hat, a cluster administrator or user, or a third-party vendor.

By default, the Template Service Broker shows objects that are globally available from the openshift project. It can also be configured to watch any other project that a cluster administrator chooses.

The Template Service Broker is not installed by default in OpenShift Container Platform 4.

4.2.2. Installing the Template Service Broker Operator

Prerequisites

  • You have installed the service catalog.

Procedure

The following procedure installs the Template Service Broker Operator using the web console.

  1. Create a namespace.

    1. Navigate in the web console to AdministrationNamespaces and click Create Namespace.
    2. Enter openshift-template-service-broker in the Name field and click Create.

      Note

      The namespace must start with openshift-.

  2. Navigate to the CatalogOperatorHub page. Verify that the openshift-template-service-broker project is selected.
  3. Select Template Service Broker Operator.
  4. Read the information about the Operator and click Install.
  5. Review the default selections and click Subscribe.

Next, you must start the Template Service Broker in order to access the template applications it provides.

4.2.3. Starting the Template Service Broker

After you have installed the Template Service Broker Operator, you can start the Template Service Broker using the following procedure.

Prerequisites

  • You have installed the service catalog.
  • You have installed the Template Service Broker Operator.

Procedure

  1. Navigate in the web console to CatalogInstalled Operators and select the openshift-template-service-broker project.
  2. Select the Template Service Broker Operator.
  3. Under Provided APIs, click Create New for Template Service Broker.
  4. Review the default YAML and click Create.
  5. Verify that the Template Service Broker has started.

    After the Template Service Broker has started, you can view the available template applications by navigating to CatalogDeveloper Catalog and selecting the Service Class checkbox. Note that it may take a few minutes for the Template Service Broker to start and the template applications to be available.

    If you do not yet see these Service classes, you can check the status of the following items:

    • Template Service Broker Pod status

      • From the WorkloadsPods page for the openshift-template-service-broker project, verify that the Pod that starts with apiserver- has a status of Running and readiness of Ready.
    • Cluster service broker status

      • From the CatalogBroker ManagementService Brokers page, verify that the template-service-broker service broker has a status of Ready.
    • Service catalog controller manager Pod logs

      • From the WorkloadsPods page for the openshift-service-catalog-controller-manager project, review the logs for each of the Pods and verify that you see a log entry with the message Successfully fetched catalog entries from broker.

4.3. Provisioning template applications

4.3.1. Provisioning template applications

The following procedure provisions an example PostgreSQL template application that was made available by the Template Service Broker.

Prerequisites

  • The service catalog is installed.
  • The Template Service Broker is installed.

Procedure

  1. Create a project.

    1. Navigate in the web console to HomeProjects and click Create Project.
    2. Enter test-postgresql in the Name field and click Create.
  2. Create a service instance.

    1. Navigate to the CatalogDeveloper Catalog page.
    2. Select the PostgreSQL (Ephemeral) template application and click Create Service Instance.
    3. Review the default selections and set any other required fields, and click Create.
    4. Go to CatalogProvisioned Services and verify that the postgresql-ephemeral service instance is created and has a status of Ready.

      You can check the progress on the HomeEvents page. After a few moments, you should see an event for postgresql-ephemeral with the message "The instance was provisioned successfully".

  3. Create a service binding.

    1. From the Provisioned Services page, click postgresql-ephemeral and click Create Service Binding.
    2. Review the default service binding name and click Create.

      This creates a new secret for binding using the name provided.

  4. Review the secret that was created.

    1. Navigate to WorkloadsSecrets and verify that a secret named postgresql-ephemeral was created.
    2. Click postgresql-ephemeral and review the key-value pairs in the Data section, which are used for binding to other apps.

4.4. Uninstalling the Template Service Broker

You can uninstall the Template Service Broker if you no longer require access to the template applications that it provides.

Important

The Template Service Broker is deprecated in OpenShift Container Platform 4. Equivalent and better functionality is present in the Operator Framework and Operator Lifecycle Manager (OLM).

4.4.1. Uninstalling the Template Service Broker

The following procedure uninstalls the Template Service Broker and its Operator using the web console.

Warning

Do not uninstall the Template Service Broker if there are any provisioned services from it in your cluster, otherwise you might encounter errors when trying to manage the services.

Prerequisites

  • The Template Service Broker is installed.

Procedure

This procedure assumes that you installed the Template Service Broker into the openshift-template-service-broker project.

  1. Uninstall the Template Service Broker.

    1. Navigate to CatalogInstalled Operators and select the openshift-template-service-broker project from the drop-down menu.
    2. Click Template Service Broker Operator.
    3. Select the Template Service Broker tab.
    4. Click template-service-broker.
    5. From the Actions drop-down menu, select Delete Template Service Broker.
    6. Click Delete from the confirmation pop-up window.

      The Template Service Broker is now uninstalled, and template applications will soon be removed from the Developer Catalog.

  2. Uninstall the Template Service Broker Operator.

    1. Navigate to CatalogOperator Management and select the openshift-template-service-broker project from the drop-down menu.
    2. Click View subscription for the Template Service Broker Operator.
    3. Select templateservicebroker.
    4. From the Actions drop-down menu, select Remove Subscription.
    5. Verify that the checkbox is checked next to Also completely remove the templateservicebroker Operator from the selected namespace and click Remove.

      The Template Service Broker Operator is no longer installed in your cluster.

After the Template Service Broker is uninstalled, users will no longer have access to the template applications provided by the Template Service Broker.

4.5. Installing the OpenShift Ansible Broker

You can install the OpenShift Ansible Broker to gain access to the service bundles that it provides.

Important

The OpenShift Ansible Broker is deprecated in OpenShift Container Platform 4. Equivalent and better functionality is present in the Operator Framework and Operator Lifecycle Manager (OLM).

4.5.1. About the OpenShift Ansible Broker

The OpenShift Ansible Broker is an implementation of the Open Service Broker (OSB) API that manages applications defined by Ansible playbook bundles (APBs). APBs provide a method for defining and distributing container applications in OpenShift Container Platform, and consist of a bundle of Ansible playbooks built into a container image with an Ansible runtime. APBs leverage Ansible to create a standard mechanism to automate complex deployments.

The OpenShift Ansible Broker follows this basic workflow:

  1. A user requests the list of available applications from the service catalog using the OpenShift Container Platform web console.
  2. The service catalog requests the list of available applications from the OpenShift Ansible Broker.
  3. The OpenShift Ansible Broker communicates with a defined container image registry to learn which APBs are available.
  4. The user issues a request to provision a specific APB.
  5. The OpenShift Ansible Broker fulfills the user’s provision request by invoking the provision method on the APB.

The OpenShift Ansible Broker is not installed by default in OpenShift Container Platform 4.

4.5.1.1. Ansible playbook bundles

An Ansible playbook bundle (APB) is a lightweight application definition that allows you to leverage existing investment in Ansible roles and playbooks.

APBs use a simple directory with named playbooks to perform OSB API actions, such as provision and bind. Metadata defined in the apb.yml file contains a list of required and optional parameters for use during deployment.

4.5.2. Installing the OpenShift Ansible Service Broker Operator

Prerequisites

  • You have installed the service catalog.

Procedure

The following procedure installs the OpenShift Ansible Service Broker Operator using the web console.

  1. Create a namespace.

    1. Navigate in the web console to AdministrationNamespaces and click Create Namespace.
    2. Enter openshift-ansible-service-broker in the Name field and openshift.io/cluster-monitoring=true in the Labels field and click Create.

      Note

      The namespace must start with openshift-.

  2. Create a cluster role binding.

    1. Navigate to AdministrationRole Bindings and click Create Binding.
    2. For the Binding Type, select Cluster-wide Role Binding (ClusterRoleBinding).
    3. For the Role Binding, enter ansible-service-broker in the Name field.
    4. For the Role, select admin.
    5. For the Subject, choose the Service Account option, select the openshift-ansible-service-broker namespace, and enter openshift-ansible-service-broker-operator in the Subject Name field.
    6. Click Create.
  3. Create a secret to connect to the Red Hat Container Catalog.

    1. Navigate to WorkloadsSecrets. Verify that the openshift-ansible-service-broker project is selected.
    2. Click CreateKey/Value Secret.
    3. Enter asb-registry-auth as the Secret Name.
    4. Add a Key of username and a Value of your Red Hat Container Catalog user name.
    5. Click Add Key/Value and add a Key of password and a Value of your Red Hat Container Catalog password.
    6. Click Create.
  4. Navigate to the CatalogOperatorHub page. Verify that the openshift-ansible-service-broker project is selected.
  5. Select OpenShift Ansible Service Broker Operator.
  6. Read the information about the Operator and click Install.
  7. Review the default selections and click Subscribe.

Next, you must start the OpenShift Ansible Broker in order to access the service bundles it provides.

4.5.3. Starting the OpenShift Ansible Broker

After you have installed the OpenShift Ansible Service Broker Operator, you can start the OpenShift Ansible Broker using the following procedure.

Prerequisites

  • You have installed the service catalog.
  • You have installed the OpenShift Ansible Service Broker Operator.

Procedure

  1. Navigate in the web console to CatalogInstalled Operators and select the openshift-ansible-service-broker project.
  2. Select the OpenShift Ansible Service Broker Operator.
  3. Under Provided APIs, click Create New for Automation Broker.
  4. Add the following to the spec field in the default YAML provided:

    registry:
      - name: rhcc
        type: rhcc
        url: https://registry.redhat.io
        auth_type: secret
        auth_name: asb-registry-auth

    This references the secret that was created when installing the OpenShift Ansible Service Broker Operator, which allows you to connect to the Red Hat Container Catalog.

  5. Set any additional OpenShift Ansible Broker configuration options and click Create.
  6. Verify that the OpenShift Ansible Broker has started.

    After the OpenShift Ansible Broker has started, you can view the available service bundles by navigating to CatalogDeveloper Catalog and selecting the Service Class checkbox. Note that it may take a few minutes for the OpenShift Ansible Broker to start and the service bundles to be available.

    If you do not yet see these Service classes, you can check the status of the following items:

    • OpenShift Ansible Broker Pod status

      • From the WorkloadsPods page for the openshift-ansible-service-broker project, verify that the Pod that starts with asb- has a status of Running and readiness of Ready.
    • Cluster service broker status

      • From the CatalogBroker ManagementService Brokers page, verify that the ansible-service-broker service broker has a status of Ready.
    • Service catalog controller manager Pod logs

      • From the WorkloadsPods page for the openshift-service-catalog-controller-manager project, review the logs for each of the Pods and verify that you see a log entry with the message Successfully fetched catalog entries from broker.

4.5.3.1. OpenShift Ansible Broker configuration options

You can set the following options for your OpenShift Ansible Broker.

Table 4.1. OpenShift Ansible Broker configuration options

YAML keyDescriptionDefault value

brokerName

The name used to identify the broker instance.

ansible-service-broker

brokerNamespace

The namespace where the broker resides.

openshift-ansible-service-broker

brokerImage

The fully qualified image used for the broker.

docker.io/ansibleplaybookbundle/origin-ansible-service-broker:v4.0

brokerImagePullPolicy

The pull policy used for the broker image itself.

IfNotPresent

brokerNodeSelector

The node selector string used for the broker’s deployment.

''

registries

Expressed as a yaml list of broker registry configs, allowing the user to configure the image registries the broker will discover and source its APBs from.

See the default registries array.

logLevel

The log level used for the broker’s logs.

info

apbPullPolicy

The pull policy used for APB Pods.

IfNotPresent

sandboxRole

The role granted to the service account used to execute APBs.

edit

keepNamespace

Whether the transient namespace created to run the APB is deleted after the conclusion of the APB, regardless of the result.

false

keepNamespaceOnError

Whether the transient namespace created to run the APB is deleted after the conclusion of the APB, only in the event of an error result.

false

bootstrapOnStartup

Whether or not the broker should run its bootstrap routine on startup.

true

refreshInterval

The interval of time between broker bootstraps, refreshing its inventory of APBs.

600s

launchApbOnBind

Experimental: Toggles the broker executing APBs on bind operations.

false

autoEscalate

Whether the broker should escalate the permissions of a user while running the APB. This should typically remain false since the broker performs originating user authorization to ensure that the user has permissions granted to the APB sandbox.

false

outputRequest

Whether to output the low level HTTP requests that the broker receives.

false

Default array for registries

- type: rhcc
  name: rhcc
  url: https://registry.redhat.io
  white_list:
  - ".*-apb$"
  auth_type: secret
  auth_name: asb-registry-auth

4.6. Configuring the OpenShift Ansible Broker

Important

The OpenShift Ansible Broker is deprecated in OpenShift Container Platform 4. Equivalent and better functionality is present in the Operator Framework and Operator Lifecycle Manager (OLM).

4.6.1. Configuring the OpenShift Ansible Broker

The following procedure customizes the settings for your OpenShift Ansible Broker.

Prerequisites

  • You have installed and started the OpenShift Ansible Broker.

Procedure

This procedure assumes that you used ansible-service-broker both as the OpenShift Ansible Broker name and the project that it was installed into.

  1. Navigate in the web console to CatalogInstalled Operators and select the ansible-service-broker project.
  2. Select the OpenShift Ansible Service Broker Operator.
  3. On the Automation Broker tab, select ansible-service-broker.
  4. On the YAML tab, add or update any OpenShift Ansible Broker configuration options under the spec field.

    For example:

    spec:
      keepNamespace: true
      sandboxRole: edit
  5. Click Save to apply these changes.

4.6.1.1. OpenShift Ansible Broker configuration options

You can set the following options for your OpenShift Ansible Broker.

Table 4.2. OpenShift Ansible Broker configuration options

YAML keyDescriptionDefault value

brokerName

The name used to identify the broker instance.

ansible-service-broker

brokerNamespace

The namespace where the broker resides.

openshift-ansible-service-broker

brokerImage

The fully qualified image used for the broker.

docker.io/ansibleplaybookbundle/origin-ansible-service-broker:v4.0

brokerImagePullPolicy

The pull policy used for the broker image itself.

IfNotPresent

brokerNodeSelector

The node selector string used for the broker’s deployment.

''

registries

Expressed as a yaml list of broker registry configs, allowing the user to configure the image registries the broker will discover and source its APBs from.

See the default registries array.

logLevel

The log level used for the broker’s logs.

info

apbPullPolicy

The pull policy used for APB Pods.

IfNotPresent

sandboxRole

The role granted to the service account used to execute APBs.

edit

keepNamespace

Whether the transient namespace created to run the APB is deleted after the conclusion of the APB, regardless of the result.

false

keepNamespaceOnError

Whether the transient namespace created to run the APB is deleted after the conclusion of the APB, only in the event of an error result.

false

bootstrapOnStartup

Whether or not the broker should run its bootstrap routine on startup.

true

refreshInterval

The interval of time between broker bootstraps, refreshing its inventory of APBs.

600s

launchApbOnBind

Experimental: Toggles the broker executing APBs on bind operations.

false

autoEscalate

Whether the broker should escalate the permissions of a user while running the APB. This should typically remain false since the broker performs originating user authorization to ensure that the user has permissions granted to the APB sandbox.

false

outputRequest

Whether to output the low level HTTP requests that the broker receives.

false

Default array for registries

- type: rhcc
  name: rhcc
  url: https://registry.redhat.io
  white_list:
  - ".*-apb$"
  auth_type: secret
  auth_name: asb-registry-auth

4.6.2. Configuring monitoring for the OpenShift Ansible Broker

In order for Prometheus to monitor the OpenShift Ansible Broker, you must create the following resources to grant Prometheus permission to access the namespace where the OpenShift Ansible Broker was installed.

Prerequisites

  • The OpenShift Ansible Broker is installed.

    Note

    This procedure assumes that you installed the OpenShift Ansible Broker into the openshift-ansible-service-broker namespace.

Procedure

  1. Create the role.

    1. Navigate to AdministrationRoles and click Create Role.
    2. Replace the YAML in the editor with the following:

      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: prometheus-k8s
        namespace: openshift-ansible-service-broker
      rules:
      - apiGroups:
        - ""
        resources:
        - services
        - endpoints
        - pods
        verbs:
        - get
        - list
        - watch
    3. Click Create.
  2. Create the role binding.

    1. Navigate to AdministrationRole Bindings and click Create Binding.
    2. For the Binding Type, select Namespace Role Binding (RoleBinding).
    3. For the Role Binding, enter prometheus-k8s in the Name field and openshift-ansible-service-broker in the Namespace field.
    4. For the Role, select prometheus-k8s.
    5. For the Subject, choose the Service Account option, select the openshift-monitoring namespace, and enter prometheus-k8s in the Subject Name field.
    6. Click Create.

Prometheus will now have access to OpenShift Ansible Broker metrics.

4.7. Provisioning service bundles

4.7.1. Provisioning service bundles

The following procedure provisions an example PostgreSQL service bundle (APB) that was made available by the OpenShift Ansible Broker.

Prerequisites

  • The service catalog is installed.
  • The OpenShift Ansible Broker is installed.

Procedure

  1. Create a project.

    1. Navigate in the web console to HomeProjects and click Create Project.
    2. Enter test-postgresql-apb in the Name field and click Create.
  2. Create a service instance.

    1. Navigate to the CatalogDeveloper Catalog page.
    2. Select the PostgreSQL (APB) service bundle and click Create Service Instance.
    3. Review the default selections and set any other required fields, and click Create.
    4. Go to CatalogProvisioned Services and verify that the dh-postgresql-apb service instance is created and has a status of Ready.

      You can check the progress on the HomeEvents page. After a few moments, you should see an event for dh-postgresql-apb with the message "The instance was provisioned successfully".

  3. Create a service binding.

    1. From the Provisioned Services page, click dh-postgresql-apb and click Create Service Binding.
    2. Review the default service binding name and click Create.

      This creates a new secret for binding using the name provided.

  4. Review the secret that was created.

    1. Navigate to WorkloadsSecrets and verify that a secret named dh-postgresql-apb was created.
    2. Click dh-postgresql-apb and review the key-value pairs in the Data section, which are used for binding to other apps.

4.8. Uninstalling the OpenShift Ansible Broker

You can uninstall the OpenShift Ansible Broker if you no longer require access to the service bundles that it provides.

Important

The OpenShift Ansible Broker is deprecated in OpenShift Container Platform 4. Equivalent and better functionality is present in the Operator Framework and Operator Lifecycle Manager (OLM).

4.8.1. Uninstalling the OpenShift Ansible Broker

The following procedure uninstalls the OpenShift Ansible Broker and its Operator using the web console.

Warning

Do not uninstall the OpenShift Ansible Broker if there are any provisioned services from it in your cluster, otherwise you might encounter errors when trying to manage the services.

Prerequisites

  • The OpenShift Ansible Broker is installed.

Procedure

This procedure assumes that you installed the OpenShift Ansible Broker into the openshift-ansible-service-broker project.

  1. Uninstall the OpenShift Ansible Broker.

    1. Navigate to CatalogInstalled Operators and select the openshift-ansible-service-broker project from the drop-down menu.
    2. Click OpenShift Ansible Service Broker Operator.
    3. Select the Automation Broker tab.
    4. Click ansible-service-broker.
    5. From the Actions drop-down menu, select Delete Automation Broker.
    6. Click Delete from the confirmation pop-up window.

      The OpenShift Ansible Broker is now uninstalled, and service bundles will soon be removed from the Developer Catalog.

  2. Uninstall the OpenShift Ansible Service Broker Operator.

    1. Navigate to CatalogOperator Management and select the openshift-ansible-service-broker project from the drop-down menu.
    2. Click View subscription for the OpenShift Ansible Service Broker Operator.
    3. Select automationbroker.
    4. From the Actions drop-down menu, select Remove Subscription.
    5. Verify that the checkbox is checked next to Also completely remove the automationbroker Operator from the selected namespace and click Remove.

      The OpenShift Ansible Service Broker Operator is no longer installed in your cluster.

After the OpenShift Ansible Broker is uninstalled, users will no longer have access to the service bundles provided by the OpenShift Ansible Broker.