Spring Cloud App Broker is a framework for building Spring Boot applications that implement the Open Service Broker API and deploy applications as brokered services.

Introduction

Spring Cloud App Broker builds on Spring Cloud Open Service Broker. It can be used to create a service broker which complies with the Open Service Broker API and deploys applications and backing services to a platform, such as Cloud Foundry or Kubernetes.

A service broker using Spring Cloud App Broker is a Spring Boot application. The broker can deploy applications written in any language supported by the targeted platform.

Getting Started

Create a Spring Boot application and include the Spring Cloud App Broker dependency in the application’s build file.

Maven Dependencies

Include the following in your application’s pom.xml file:

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-app-broker-cloudfoundry</artifactId>
        <version>1.0.0.BUILD-SNAPSHOT</version>
    </dependency>
</dependencies>

Gradle Dependencies

Include the following in your application’s build.gradle file:

dependencies {
    compile 'org.springframework.cloud:spring-cloud-starter-app-broker-cloudfoundry:1.0.0.BUILD-SNAPSHOT'
}

Configuring the Service Broker

The service broker is configured using Spring Boot externalized configuration, supplied using a YAML or Java Properties file (for example, you can provide configuration in the application.yml file). Because Spring Cloud App Broker builds on Spring Cloud Open Service Broker, you must provide Spring Cloud Open Service Broker configuration to use Spring Cloud App Broker.

Include Spring Cloud Open Servce Broker configuration using properties under spring.cloud.openservicebroker as in the following example:

spring:
  cloud:
    openservicebroker:
      catalog:
        services:
        - name: example
          id: ebca66fd-461d-415b-bba3-5e379d671c88
          description: A useful service
          bindable: true
          tags:
          - example
          plans:
          - name: standard
            id: e19e6bc3-37c1-4478-b70f-c7157ebbb28c
            description: A standard plan
            free: true

Include Spring Cloud App Broker configuration using properties under spring.cloud.appbroker as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
            - name: example-service-app2
              path: classpath:app2.jar
      deployer:
        cloudfoundry:
          api-host: api.sys.example.com
          api-port: 443
          username: admin
          password: adminpass
          default-org: test
          default-space: development

Advertising Services

The service broker catalog, through which the broker advertises service offerings, is provided by Spring Cloud Open Service Broker. In App Broker configuration (using properties under spring.cloud.appbroker.services), you can list services and their plans. This listing must correspond to the service and service plan listing given to Spring Cloud Open Service Broker (using properties under spring.cloud.openservicebroker.catalog.services).

For more information about configuring the broker catalog, see the Spring Cloud Open Service Broker documentation.

Service Instances

You can configure details of services, including apps to deploy, app deployment details, and backing services to create, in App Broker configuration properties. These properties are generally under spring.cloud.appbroker.services.

Configuring App Deployment

Deployment details for a backing application can be configured statically in the service broker’s application configuration and dynamically using service instance parameters and customization implementations.

Static Customization

You can statically configure backing application deployment details in the application configuration for the service broker, using properties under spring.cloud.appbroker.

Properties Configuration

You can specify app deployment properties in configuration. These properties can have default values and service-specific values.

For Cloud Foundry, set default values for all services under spring.cloud.appbroker.deployer.cloudfoundry.*, as shown in the following example:

spring:
  cloud:
    appbroker:
      deployer:
        cloudfoundry:
          properties:
            memory: 1G
            health-check: http
            health-check-http-endpoint: /health
            health-check-timeout: 180

Set overriding values for a specific service in the service’s configuration under spring.cloud.appbroker.services.*, as shown in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              properties:
                memory: 2G
                count: 2
                no-route: true

The following table lists properties that can be set for all or specific app deployments.

Property Description Default

count

memory

disk

host

target

buildpack

The buildpack to use for deploying the application.

domain

The domain to use when mapping routes for the deployed application. domain and host are mutually exclusive with routes.

routes

The routes to which to bind the deployed application.

health-check

The type of health check to perform on the deployed application.

PORT

health-check-http-endpoint

The path used by the HTTP health check.

/health

health-check-timeout

The timeout value used by the health check, in seconds.

120

api-timeout

The timeout value used for blocking API calls, in seconds.

360

status-timeout

staging-timeout

startup-timeout

delete-routes

Whether to delete routes when un-deploying an application.

true

java-opts
Environment Configuration

You can provide environment variables to be set on a deployed app. Environment variables are set using properties under environment for the deployed app, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              environment:
                logging.level.spring.security: DEBUG
                spring.profiles.active: cloud
Service Configuration

You can configure services which should be bound to a deployed app. Services are configured using properties under services for the deployed app, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              services:
              - service-instance-name: example-db
          services:
          - service-instance-name: example-db
            name: mysql
            plan: small
            parameters:
            param-key: param-value

Dynamic Customization

To customize the backing application deployment using information that is only available when performing a service broker operation or that must be generated per service instance, you can use the service broker application configuration to provide the names of customization implementations.

Backing Application Target

You can configure the target location for backing applications (in Cloud Foundry, an org and space) using a target specification, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          target:
          *  name: SpacePerServiceInstance*
        apps:
          apps:
            - name: example-service-app1
              path: classpath:app1.jar

By default (if you do not provide a target specification), all backing applications are deployed to the default target specified under spring.cloud.appbroker.deployer. For Cloud Foundry, this is the org named by spring.cloud.appbroker.deployer.cloudfoundry.default-org and the space named by spring.cloud.appbroker.deployer.cloudfoundry.default-space.

The SpacePerServiceInstance Target

If you use the SpacePerServiceInstance target, App Broker will deploy backing applications to a unique target location that is named using the service instance GUID provided by the platform at service instance create time. For Cloud Foundry, this target location will be the org named by spring.cloud.appbroker.deployer.cloudfoundry.default-org and a new space created using the service instance GUID as the space name.

The ServiceInstanceGuidSuffix Target

If you use the ServiceInstanceGuidSuffix target, App Broker will deploy backing applications using a unique name and hostname that incorporates the service instance GUID provided by the platform at service instance create time. For Cloud Foundry, the target location will be the org named by spring.cloud.appbroker.deployer.cloudfoundry.default-org, the space named by spring.cloud.appbroker.deployer.cloudfoundry.default-space, and an application name as [APP-NAME]-[SI-GUID], where [APP-NAME] is the name listed for the application under spring.cloud.appbroker.services.apps and [SI-GUID] is the service instance GUID. The application will also use a hostname incorporating the service instance GUID as a suffix, as [APP-NAME]-[SI-GUID].

Service Instance Parameters

When a user provides parameters while creating or updating a service instance, App Broker can transform these parameters into details of the backing app deployment using parameters transformers. You can configure parameters transformers using properties under parameters-transformers, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              parameters-transformers:
                - name: EnvironmentMapping
                  args:
                    - include: parameter1,parameter2
                - name: PropertyMapping
                  args:
                    - include: count,memory

In this example, the named parameters-transformers refer to Java objects which have been contributed to the Spring application context. A parameters transformer can accept one or more arguments that configure its behavior, and can modify any aspect of the backing application deployment (properties, environment variables, services, etc.).

The EnvironmentMapping Parameters Transformer

The EnvironmentMapping parameters transformer populates environment variables on the backing application from parameters provided when a service instance is created or updated. It supports a single argument, include, which specifies the names of parameters that will be mapped to environment variables.

The PropertyMapping Parameters Transformer

The PropertyMapping parameters transformer sets deployment properties of the backing application from parameters provided when a service instance is created or updated. It supports a single argument, include, which specifies the names of deployment properties that should be recognized.

Credentials Generation

App Broker can generate and assign unique credentials for each backing app deployment. You can configure credential providers using properties under credential-providers, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              credential-providers:
                - name: SpringSecurityBasicAuth
                - name: SpringSecurityOAuth2

In this example, the named credential-providers refer to Java objects which have been contributed to the Spring application context. A credential provider can accept one or more arguments that configure its behavior. A credential provider typically generates credentials and set environment variables on the backing application.

The SpringSecurityBasicAuth Credential Provider

The SpringSecurityBasicAuth credential provider generates a username and password and sets Spring Boot security properties to the generated values. Username and password generation can be configured with arguments, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              credential-providers:
                - name: SpringSecurityBasicAuth
                  args:
                    length: 14
                    include-uppercase-alpha: true
                    include-lowercase-alpha: true
                    include-numeric: true
                    include-special: true
The SpringSecurityOAuth2 Credential Provider

The SpringSecurityOAuth2 credential provider creates an OAuth2 client in a token server (e.g. UAA for Cloud Foundry) using details provided as arguments and a generated client secret, and sets Spring Boot security properties to the generated values. Client secret generation can also be configured with arguments, as in the following example:

spring:
  cloud:
    appbroker:
      services:
        - service-name: example
          plan-name: standard
          apps:
            - name: example-service-app1
              path: classpath:app1.jar
              credential-providers:
                - name: SpringSecurityOAuth2
                  args:
                    registration: my-client-1
                    client-id: example-client
                    client-name: example-client
                    scopes: ["uaa.resource"]
                    authorities: ["uaa.resource"]
                    grant-types: ["client_credentials"]
                    identity-zone-subdomain:
                    identity-zone-id:
                    length: 14
                    include-uppercase-alpha: true
                    include-lowercase-alpha: true
                    include-numeric: true
                    include-special: true

Creating a Service Instance

Spring Cloud App Broker provides the AppDeploymentCreateServiceInstanceWorkflow workflow, which handles deploying the configured backing applications and services as illustrated in the previous sections. The service broker application can implement the CreateServiceInstanceWorkflow interface to further modify the deployment. Multiple workflows may be annotated with @Order so as to process the workflows in a specific order. Alternatively, the service broker application can implement the ServiceInstanceService interface provided by Spring Cloud Open Service Broker. See Service Instances in the Spring Cloud Open Service Broker documentation.

Updating a Service Instance

Spring Cloud App Broker provides the AppDeploymentUpdateServiceInstanceWorkflow workflow, which handles updating the configured backing applications and services as illustrated in the previous sections. The service broker application can implement the UpdateServiceInstanceWorkflow interface to further modify the deployment. Multiple workflows may be annotated with @Order so as to process the workflows in a specific order. Alternatively, the service broker application can implement the ServiceInstanceService interface provided by Spring Cloud Open Service Broker. See Service Instances in the Spring Cloud Open Service Broker documentation.

Modifying certain properties, such as disk and memory, when updating an application, may result in downtime.

Deleting a Service Instance

Spring Cloud App Broker provides the AppDeploymentDeleteServiceInstanceWorkflow workflow, which handles deleting the configured backing applications and services as illustrated in the previous sections. The service broker application can implement the DeleteServiceInstanceWorkflow interface to further modify the deployment. Multiple workflows may be annotated with @Order so as to process the workflows in a specific order. Alternatively, the service broker application can implement the ServiceInstanceService interface provided by Spring Cloud Open Service Broker. See Service Instances in the Spring Cloud Open Service Broker documentation.

Service Bindings

By default, Spring Cloud App Broker does not include functionality for managing bindings to its service instances. App Broker provides interfaces which service broker authors can implement to control service bindings.

Creating a Service Binding

The service broker application can implement the CreateServiceInstanceAppBindingWorkflow interface. Alternatively, the service broker application can implement the ServiceInstanceBindingService interface provided by Spring Cloud Open Service Broker. See Service Bindings in the Spring Cloud Open Service Broker documentation.

Deleting a Service Binding

The service broker application can implement the DeleteServiceInstanceBindingWorkflow interface. Alternatively, the service broker application can implement the ServiceInstanceBindingService interface provided by Spring Cloud Open Service Broker. See Service Bindings in the Spring Cloud Open Service Broker documentation.

Deployment Platforms

You can configure details of deployment platforms in App Broker configuration properties. These properties are under spring.cloud.appbroker.deployer. Currently, Spring Cloud App Broker supports only Cloud Foundry as a deployment platform.

To configure a Cloud Foundry deployment platform, use properties under spring.cloud.appbroker.deployer.cloudfoundry, as in the following example:

spring:
  cloud:
    appbroker:
      deployer:
        cloudfoundry:
          api-host: api.sys.example.com
          api-port: 443
          username: admin
          password: adminpass
          client-id: EXAMPLE_ID
          client-secret: EXAMPLE_SECRET
          default-org: test
          default-space: development
The two properties username and password and the two properties client-id and client-secret are mutually exclusive. The client-id and client-secret properties are for use with OAuth 2.0.