Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE Cloud Application Platform 1.5.2

22 Service Brokers

The Open Service Broker API provides (OSBAPI) your SUSE Cloud Application Platform applications with access to external dependencies and platform-level capabilities, such as databases, filesystems, external repositories, and messaging systems. These resources are called services. Services are created, used, and deleted as needed, and provisioned on demand. This chapter introduces several different service brokers that implement the Open Service Broker API.

Use the following guideline to determine which service broker is most suitable for your situation.

22.1 cf-usb

Universal Service Broker for Cloud Foundry, or cf-usb, is a project that implements and exposes the Open Service Broker API. It uses drivers, referred to as plugins, to connect to different services. More information about cf-usb can be found at https://github.com/SUSE/cf-usb.

Important
Important: Kubernetes Compatability

cf-usb is currently compatible with Kubernetes version 1.15 and earlier. Usage with Kubernetes version 1.16 and beyond is not supported.

22.1.1 Enabling and Disabling Service Brokers

The service broker feature is enabled as part of a default SUSE Cloud Foundry deployment. To disable it, use the --set "enable.cf_usb=false" flag when running helm install or helm upgrade.

If disabling the feature on an initial deployment, run the following command:

Note
Note: Setting UAA_CA_CERT

Starting with SUSE Cloud Application Platform 1.5.2, you no longer need to set UAA_CA_CERT when using an external UAA with a certificate signed by a well known Certificate Authority (CA). It is only needed when you use an external UAA with either a certificate generated by the secret-generator or a self-signed certificate.

If you need to set UAA_CA_CERT:

  1. Obtain your UAA secret and certificate:

    tux > SECRET=$(kubectl get pods --namespace uaa \
    --output jsonpath='{.items[?(.metadata.name=="uaa-0")].spec.containers[?(.name=="uaa")].env[?(.name=="INTERNAL_CA_CERT")].valueFrom.secretKeyRef.name}')
    
    tux > CA_CERT="$(kubectl get secret $SECRET --namespace uaa \
    --output jsonpath="{.data['internal-ca-cert']}" | base64 --decode -)"
  2. Then pass --set "secrets.UAA_CA_CERT=${CA_CERT}" as part of your helm command.

tux > helm install suse/cf \
--name susecf-scf \
--namespace scf \
--values scf-config-values.yaml \
--set "enable.cf_usb=false"

If disabling the feature on an existing deployment, run the following command:

tux > helm upgrade susecf-scf suse/cf \
--values scf-config-values.yaml \
--set "secrets.UAA_CA_CERT=${CA_CERT}" \
--set "enable.cf_usb=false" \
--version 2.20.3

To enable the feature again, run helm upgrade with the --set "enable.cf_usb=true" flag. Be sure to pass your uaa secret and certificate to scf first:

tux > SECRET=$(kubectl get pods --namespace uaa \
--output jsonpath='{.items[?(.metadata.name=="uaa-0")].spec.containers[?(.name=="uaa")].env[?(.name=="INTERNAL_CA_CERT")].valueFrom.secretKeyRef.name}')

tux > CA_CERT="$(kubectl get secret $SECRET --namespace uaa \
--output jsonpath="{.data['internal-ca-cert']}" | base64 --decode -)"

tux > helm upgrade susecf-scf suse/cf \
--values scf-config-values.yaml \
--set "secrets.UAA_CA_CERT=${CA_CERT}" \
--set "enable.cf_usb=true" \
--version 2.20.3

22.1.2 Prerequisites

The following examples demonstrate how to deploy service brokers for MySQL and PostgreSQL with Helm, using charts from the SUSE repository. You must have the following prerequisites:

  • A working SUSE Cloud Application Platform deployment with Helm and the Cloud Foundry command line interface (cf CLI).

  • An Application Security Group (ASG) for applications to reach external databases. (See Understanding Application Security Groups.)

  • An external MySQL or PostgreSQL installation with account credentials that allow creating and deleting databases and users.

Warning
Warning: Azure Databases and cf-usb

The cf-usb service broker is not compatible with an external database hosted on Azure. We recommend using the service brokers that are provided by Microsoft Azure for OSBAPI connections to their hosted database services.

For testing purposes you may create an insecure security group:

tux > echo > "internal-services.json" '[{ "destination": "0.0.0.0/0", "protocol": "all" }]'
tux > cf create-security-group internal-services-test internal-services.json
tux > cf bind-running-security-group internal-services-test
tux > cf bind-staging-security-group internal-services-test

You may apply an ASG later, after testing. All running applications must be restarted to use the new security group.

22.1.3 Deploying on SUSE CaaS Platform

If you are deploying SUSE Cloud Application Platform on SUSE CaaS Platform, see a Pod Security Policy (PSP) must also applied to your new service brokers.

Take the example configuration file, cap-psp-rbac.yaml, and add the following. Replace mysql-sidecar with the namespace name of your service broker.

- kind: ServiceAccount
  name: default
  namespace: mysql-sidecar

Then apply the PSP configuration, before you deploy your new service broker, with this command:

tux > kubectl apply -f cap-psp-rbac.yaml

kubectl apply updates an existing deployment. After applying the PSP, proceed to configuring and deploying your service broker.

22.1.4 Configuring the MySQL Deployment

Start by extracting the uaa namespace secrets name, and the uaa and scf namespaces internal certificates with these commands. These will output the complete certificates. Substitute your secrets name if it is different than the example:

tux > kubectl get pods --namespace uaa \
--output jsonpath='{.items[*].spec.containers[?(.name=="uaa")].env[?(.name=="INTERNAL_CA_CERT")].valueFrom.secretKeyRef.name}'
 secrets-2.8.0-1

tux > kubectl get secret --namespace scf secrets-2.8.0-1 --output jsonpath='{.data.internal-ca-cert}' | base64 --decode
 -----BEGIN CERTIFICATE-----
 MIIE8jCCAtqgAwIBAgIUT/Yu/Sv4UHl5zHZYZKCy5RKJqmYwDQYJKoZIhvcNAQEN
 [...]
 xC8x/+zT0QkvcRJBio5gg670+25KJQ==
 -----END CERTIFICATE-----

tux > kubectl get secret --namespace uaa secrets-2.8.0-1 --output jsonpath='{.data.internal-ca-cert}' | base64 --decode
 -----BEGIN CERTIFICATE-----
 MIIE8jCCAtqgAwIBAgIUSI02lj0a0InLb/zMrjNgW5d8EygwDQYJKoZIhvcNAQEN
 [...]
 to2GI8rPMb9W9fd2WwUXGEHTc+PqTg==
 -----END CERTIFICATE-----

You will copy these certificates into your configuration file as shown below.

Create a values.yaml file. The following example is called usb-config-values.yaml. Modify the values to suit your SUSE Cloud Application Platform installation.

env:
  # Database access credentials
  SERVICE_MYSQL_HOST: mysql.example.com
  SERVICE_MYSQL_PORT: 3306
  SERVICE_MYSQL_USER: mysql-admin-user
  SERVICE_MYSQL_PASS: mysql-admin-password

  # CAP access credentials, from your original deployment configuration
  # file, scf-config-values.yaml
  CF_ADMIN_USER: admin
  CF_ADMIN_PASSWORD: password
  CF_DOMAIN: example.com

  # Copy the certificates you extracted above, as shown in these
  # abbreviated examples, prefaced with the pipe character

  # SCF cert
  CF_CA_CERT: |
    -----BEGIN CERTIFICATE-----
    MIIE8jCCAtqgAwIBAgIUT/Yu/Sv4UHl5zHZYZKCy5RKJqmYwDQYJKoZIhvcNAQEN
    [...]
    xC8x/+zT0QkvcRJBio5gg670+25KJQ==
    -----END CERTIFICATE-----

  # UAA cert
  UAA_CA_CERT: |
    -----BEGIN CERTIFICATE-----
    MIIE8jCCAtqgAwIBAgIUSI02lj0a0InLb/zMrjNgW5d8EygwDQYJKoZIhvcNAQEN
    [...]
    to2GI8rPMb9W9fd2WwUXGEHTc+PqTg==
    -----END CERTIFICATE-----

kube:
  organization: "cap"
  registry:
    hostname: "registry.suse.com"
    username: ""
    password: ""

22.1.5 Deploying the MySQL Chart

SUSE Cloud Application Platform includes charts for MySQL and PostgreSQL (see Section 5.6, “Add the Kubernetes Charts Repository” for information on managing your Helm repository):

tux > helm search suse
NAME                            CHART VERSION   APP VERSION     DESCRIPTION
suse/cf                         2.20.3          1.5.2           A Helm chart for SUSE Cloud Foundry
suse/cf-usb-sidecar-mysql       1.0.1                           A Helm chart for SUSE Universal Service Broker Sidecar fo...
suse/cf-usb-sidecar-postgres    1.0.1                           A Helm chart for SUSE Universal Service Broker Sidecar fo...
suse/console                    3.1.0           1.5.2           A Helm chart for deploying Stratos UI Console
suse/log-agent-rsyslog      	1.0.1        	8.39.0     	Log Agent for forwarding logs of K8s control pl...
suse/metrics                    1.1.2           1.5.2           A Helm chart for Stratos Metrics
suse/minibroker                 0.3.1                           A minibroker for your minikube
suse/nginx-ingress              0.28.4          0.15.0          An nginx Ingress controller that uses ConfigMap to store ...
suse/uaa                        2.20.3          1.5.2           A Helm chart for SUSE UAA

Create a namespace for your MySQL sidecar:

tux > kubectl create namespace mysql-sidecar

Install the MySQL Helm chart:

tux > helm install suse/cf-usb-sidecar-mysql \
  --devel \
  --name mysql-service \
  --namespace mysql-sidecar \
  --set "env.SERVICE_LOCATION=http://cf-usb-sidecar-mysql.mysql-sidecar:8081" \
  --set default-auth=mysql_native_password
  --values usb-config-values.yaml \
  --wait

Wait for the new pods to become ready:

tux > watch kubectl get pods --namespace=mysql-sidecar

Confirm that the new service has been added to your SUSE Cloud Application Platform installation:

tux > cf marketplace
Warning
Warning: MySQL Requires mysql_native_password

The MySQL sidecar works only with deployments that use mysql_native_password as their authentication plugin. This is the default for MySQL versions 8.0.3 and earlier, but later versions must be started with --default-auth=mysql_native_password before any user creation. (See https://github.com/go-sql-driver/mysql/issues/785

22.1.6 Create and Bind a MySQL Service

To create a new service instance, use the Cloud Foundry command line client:

tux > cf create-service mysql default service_instance_name

You may replace service_instance_name with any name you prefer.

Bind the service instance to an application:

tux > cf bind-service my_application service_instance_name

22.1.7 Deploying the PostgreSQL Chart

The PostgreSQL configuration is slightly different from the MySQL configuration. The database-specific keys are named differently, and it requires the SERVICE_POSTGRESQL_SSLMODE key.

env:
  # Database access credentials
  SERVICE_POSTGRESQL_HOST: postgres.example.com
  SERVICE_POSTGRESQL_PORT: 5432
  SERVICE_POSTGRESQL_USER: pgsql-admin-user
  SERVICE_POSTGRESQL_PASS: pgsql-admin-password

  # The SSL connection mode when connecting to the database.  For a list of
  # valid values, please see https://godoc.org/github.com/lib/pq
  SERVICE_POSTGRESQL_SSLMODE: disable

  # CAP access credentials, from your original deployment configuration
  # file, scf-config-values.yaml
  CF_ADMIN_USER: admin
  CF_ADMIN_PASSWORD: password
  CF_DOMAIN: example.com

  # Copy the certificates you extracted above, as shown in these
  # abbreviated examples, prefaced with the pipe character

  # SCF certificate
  CF_CA_CERT: |
    -----BEGIN CERTIFICATE-----
    MIIE8jCCAtqgAwIBAgIUT/Yu/Sv4UHl5zHZYZKCy5RKJqmYwDQYJKoZIhvcNAQEN
    [...]
    xC8x/+zT0QkvcRJBio5gg670+25KJQ==
    -----END CERTIFICATE-----

  # UAA certificate
  UAA_CA_CERT: |
    ----BEGIN CERTIFICATE-----
    MIIE8jCCAtqgAwIBAgIUSI02lj0a0InLb/zMrjNgW5d8EygwDQYJKoZIhvcNAQEN
    [...]
    to2GI8rPMb9W9fd2WwUXGEHTc+PqTg==
    -----END CERTIFICATE-----

  SERVICE_TYPE: postgres

kube:
  organization: "cap"
  registry:
    hostname: "registry.suse.com"
    username: ""
    password: ""

Create a namespace and install the chart:

tux > kubectl create namespace postgres-sidecar

tux > helm install suse/cf-usb-sidecar-postgres \
  --devel \
  --name postgres-service \
  --namespace postgres-sidecar \
  --set "env.SERVICE_LOCATION=http://cf-usb-sidecar-postgres.postgres-sidecar:8081" \
  --values usb-config-values.yaml \
  --wait

Then follow the same steps as for the MySQL chart.

22.1.8 Removing Service Broker Sidecar Deployments

To correctly remove sidecar deployments, perform the following steps in order.

  • Unbind any applications using instances of the service, and then delete those instances:

    tux > cf unbind-service my_app my_service_instance
    tux > cf delete-service my_service_instance
  • Install the CF-USB CLI plugin for the Cloud Foundry CLI from https://github.com/SUSE/cf-usb-plugin/releases/, for example:

    tux > cf install-plugin \
     https://github.com/SUSE/cf-usb-plugin/releases/download/1.0.0/cf-usb-plugin-1.0.0.0.g47b49cd-linux-amd64
  • Configure the Cloud Foundry USB CLI plugin, using the domain you created for your SUSE Cloud Foundry deployment:

    tux > cf usb-target https://usb.example.com
  • List the current sidecar deployments and take note of the names:

    tux > cf usb-driver-endpoints
  • Remove the service by specifying its name:

    tux > cf usb-delete-driver-endpoint mysql-service
  • Find your release name, then delete the release:

    tux > helm list
    NAME           REVISION UPDATED                   STATUS    CHART                      NAMESPACE
    susecf-console 1        Wed Aug 14 08:35:58 2018  DEPLOYED  console-3.1.0              stratos
    susecf-scf     1        Tue Aug 14 12:24:36 2018  DEPLOYED  cf-2.20.3                  scf
    susecf-uaa     1        Tue Aug 14 12:01:17 2018  DEPLOYED  uaa-2.20.3                 uaa
    mysql-service  1        Mon May 21 11:40:11 2018  DEPLOYED  cf-usb-sidecar-mysql-1.0.1 mysql-sidecar
    
    tux > helm delete --purge mysql-service

22.1.9 Change in URL of Internal cf-usb Broker Endpoint

This change is only applicable for upgrades from Cloud Application Platform 1.2.1 to Cloud Application Platform 1.3 and upgrades from Cloud Application Platform 1.3 to Cloud Application Platform 1.3.1. The URL of the internal cf-usb broker endpoint has changed. Brokers for PostgreSQL and MySQL that use cf-usb will require the following manual fix after upgrading to reconnect with SCF/CAP:

For Cloud Application Platform 1.2.1 to Cloud Application Platform 1.3 upgrades:

  1. Get the name of the secret (for example secrets-2.14.5-1):

    tux > kubectl get secret --namespace scf
  2. Get the URL of the cf-usb host (for example https://cf-usb.scf.svc.cluster.local:24054):

    tux > cf service-brokers
  3. Get the current cf-usb password. Use the name of the secret obtained in the first step:

    tux > kubectl get secret --namespace scf secrets-2.14.5-1 --output yaml | grep \\scf-usb-password: | cut -d: -f2 | base64 -id
  4. Update the service broker, where password is the password from the previous step, and the URL is the result of the second step with the leading cf-usb part doubled with a dash separator

    tux > cf update-service-broker usb broker-admin password https://cf-usb-cf-usb.scf.svc.cluster.local:24054

For Cloud Application Platform 1.3 to Cloud Application Platform 1.3.1 upgrades:

  1. Get the name of the secret (for example secrets-2.15.2-1):

    tux > kubectl get secret --namespace scf
  2. Get the URL of the cf-usb host (for example https://cf-usb-cf-usb.scf.svc.cluster.local:24054):

    tux > cf service-brokers
  3. Get the current cf-usb password. Use the name of the secret obtained in the first step:

    tux > kubectl get secret --namespace scf secrets-2.15.2-1 --output yaml | grep \\scf-usb-password: | cut -d: -f2 | base64 -id
  4. Update the service broker, where password is the password from the previous step, and the URL is the result of the second step with the leading cf-usb- part removed:

    tux > cf update-service-broker usb broker-admin password https://cf-usb.scf.svc.cluster.local:24054

22.2 Provisioning Services with Minibroker

Minibroker is an OSBAPI compliant broker created by members of the Microsoft Azure team. It provides a simple method to provision service brokers on Kubernetes clusters.

Important
Important: Minibroker Upstream Services

The services deployed by Minibroker are sourced from the stable upstream charts repository, see https://github.com/helm/charts/tree/master/stable, and maintained by contributors to the Helm project. Though SUSE supports Minibroker itself, it does not support the service charts it deploys. Operators should inspect the charts and images exposed by the service plans before deciding to use them in a production environment.

22.2.1 Deploy Minibroker

  1. Minibroker is deployed using a Helm chart. Ensure your SUSE Helm chart repository contains the most recent Minibroker chart:

    tux > helm repo update
  2. Use Helm to deploy Minibroker:

    tux > helm install suse/minibroker --namespace minibroker --name minibroker --set "defaultNamespace=minibroker"

    The following table lists the services provided by Minibroker, along with the latest chart and application version combination known to work with Minibroker.

    Note that the table is only applicable to Kubernetes deployments with version 1.15 or earlier.

    ServiceVersionappVersion
    MariaDB4.3.010.1.34
    MongoDB5.3.34.0.6
    PostgreSQL6.2.111.5.0
    Redis3.7.24.0.10
  3. Monitor the deployment progress. Wait until all pods are in a ready state before proceeding:

    tux > watch --color 'kubectl get pods --namespace minibroker'

22.2.2 Setting Up the Environment for Minibroker Usage

  1. Begin by logging into your Cloud Application Platform deployment. Select an organization and space to work with, creating them if needed:

    tux > cf api --skip-ssl-validation https://api.example.com
     tux > cf login -u admin -p password
     tux > cf create-org org
     tux > cf create-space space -o org
     tux > cf target -o org -s space
  2. Create the service broker. Note that Minibroker does not require authentication and the username and password parameters act as dummy values to pass to the cf command. These parameters do not need to be customized for the Cloud Application Platform installation:

    tux > cf create-service-broker minibroker username password http://minibroker-minibroker.minibroker.svc.cluster.local

    After the service broker is ready, it can be seen on your deployment:

    tux > cf service-brokers
     Getting service brokers as admin...
    
     name               url
     minibroker         http://minibroker-minibroker.minibroker.svc.cluster.local
  3. List the services and their associated plans the Minibroker has access to:

    tux > cf service-access -b minibroker
  4. Enable access to a service. Refer to the table in Section 22.2.1, “Deploy Minibroker” for service plans known to be working with Minibroker.

    This example enables access to the Redis service:

    tux > cf enable-service-access redis -b minibroker -p 4-0-10

    Use cf marketplace to verify the service has been enabled:

    tux > cf marketplace
     Getting services from marketplace in org org / space space as admin...
     OK
    
     service      plans     description
     redis        4-0-10    Helm Chart for redis
    
     TIP:  Use 'cf marketplace -s SERVICE' to view descriptions of individual plans of a given service.
  5. Define your Application Security Group (ASG) rules in a JSON file. Using the defined rules, create an ASG and bind it to an organization and space:

    tux > echo > redis.json '[{ "protocol": "tcp", "destination": "10.0.0.0/8", "ports": "6379", "description": "Allow Redis traffic" }]'
     tux > cf create-security-group redis_networking redis.json
     tux > cf bind-security-group redis_networking org space

    Use following ports to define your ASG for the given service:

    ServicePort
    MariaDB3306
    MongoDB27017
    PostgreSQL5432
    Redis6379
  6. Create an instance of the Redis service. The cf marketplace or cf marketplace -s redis commands can be used to see the available plans for the service:

    tux > cf create-service redis 4-0-10 redis-example-service

    Monitor the progress of the pods and wait until all pods are in a ready state. The example below shows the additional redis pods with a randomly generated name that have been created in the minibroker namespace:

    tux > watch --color 'kubectl get pods --namespace minibroker'
     NAME                                            READY     STATUS             RESTARTS   AGE
     alternating-frog-redis-master-0                 1/1       Running            2          1h
     alternating-frog-redis-slave-7f7444978d-z86nr   1/1       Running            0          1h
     minibroker-minibroker-5865f66bb8-6dxm7          2/2       Running            0          1h

22.2.3 Using Minibroker with Applications

This section demonstrates how to use Minibroker services with your applications. The example below uses the Redis service instance created in the previous section.

  1. Obtain the demo application from Github and use cf push with the --no-start flag to deploy the application without starting it:

    tux > git clone https://github.com/scf-samples/cf-redis-example-app
     tux > cd cf-redis-example-app
     tux > cf push --no-start
  2. Bind the service to your application and start the application:

    tux > cf bind-service redis-example-app redis-example-service
     tux > cf start redis-example-app
  3. When the application is ready, it can be tested by storing a value into the Redis service:

    tux > export APP=redis-example-app.example.com
     tux > curl --request GET $APP/foo
     tux > curl --request PUT $APP/foo --data 'data=bar'
     tux > curl --request GET $APP/foo

    The first GET will return key not present. After storing a value, it will return bar.

Important
Important: Database Names for PostgreSQL and MariaDB Instances

By default, Minibroker creates PostgreSQL and MariaDB server instances without a named database. A named database is required for normal usage with these and will need to be added during the cf create-service step using the -c flag. For example:

tux > cf create-service postgresql 9-6-2 djangocms-db -c '{"postgresDatabase":"mydjango"}'
 tux > cf create-service mariadb 10-1-34 my-db  -c '{"mariadbDatabase":"mydb"}'

Other options can be set too, but vary by service type.

22.2.4 Upgrading SUSE Cloud Application Platform When Using Minibroker

If you are upgrading SUSE Cloud Application Platform to 1.5.2 and already use Minibroker to connect to external databases and are using Kubernetes 1.16 or higher, which is the case with SUSE CaaS Platform 4.1, you will need to update the database version to a compatible version and migrate your data over via the database’s suggested mechanism. This may require a database export/import.

Print this page