Skip to content

Latest commit

 

History

History
568 lines (497 loc) · 19.5 KB

configure-service-broker.md

File metadata and controls

568 lines (497 loc) · 19.5 KB
Raw

Table of Contents

  1. Open Service Broker Framework (by evoila)
  2. Components
  3. Configuring a Service Broker
  4. Service Keys
  5. Backup Agent
  6. Development
  7. Local Deployment
  8. Open Service Broker API Features
  9. IDE & Runtime
  10. Contribution
  11. License

Configuring a Service Broker

Basic Configuration

Within the following sections the documentation covers the maximum number of possibilities in regard of Service Broker configuration for the evoila OSB Framework. Each configuration section, which is not mandatory, is marked with (Optional).

In the spring section we define the endpoint properties, for communication between Config Server, Service Key Manager, Backup Manager and Service Broker (RabbitMQ) and the storage backend which is based on MongoDB. In regard to the storage backend it is important to note, that MongoDB might be replaced with any database of choice. The only thing that needs to adapted are the interfaces in the osb-persistence module.

Note: an important note here is, that we correlate multi site deployments with spring profiles. Means, the profiles section contains the name of the site, where the Service Broker is deployed.

spring:
  profiles: site1
  data:
    mongodb:
      database: dbName
      host: host1
      username: username1
      password: password1
      port: 27017        
  rabbitmq:
    host: host1
    username: usernam1
    password: password1
    port: 5672    
    virtual-host: vhost1
  thymeleaf:
    cache: true
    mode: LEGACYHTML5

In addition to the usual server related configurations by spring, you can set a retry-after header to be used by last_operation endpoints like this:

server:
  retry-afer: 120

The basic configuration for communication with the backend database, RabbitMQ (Config Updates, Service Key Creation) and Thymeleaf for Service Broker dashboard delivery.

login:
  password: cloudfoundry
  role: USER
  username: admin

The login section configures username and password (for Basic Authentication), which need to be provided, when the Service Broker is registered in Cloud Foundry or Kubernetes.

As defined in the Catalog (see below), the Open Service Broker Framework provides multiple deployment procedures to be configured within in one Service (separated through Plans).

The following three configurations show:

  • Bosh
  • Existing Endpoint
  • Openstack

Bosh

bosh:
  authentication: OAUTH
  host: host1
  username: username1
  password: password1
  stemcellOs: ubuntu-trusty
  stemcellVersion: 3468.13  
  vip_network: floating1

While host, username and password a self-explanatory, we provide a definition for the other properties:

  • authentication (BASIC for Basic Authentication, OAUTH for OAuth2 Authentication)
  • stemcellOs: a "Bosh-global" definition of the default Stemcell
  • stemcellVersion: a "Bosh-global" definition of the default Stemcell Version
  • vip_network: in Bosh you can define VIP networks for Floating IPs (e.g. used in a scenario where a dedicated Load Balancer needs a Public IP)

This config is NOT mandatory if you don't plan any interaction with Bosh for deployment/automation purposes.

OpenStack

openstack:
  cinder:
    az: zone00
  endpoint: https://os.domain:5000/v3
  imageId: 7e72a4b2-8dd4-4a3c-94f9-0ad895b7a622
  keypair: keypair-name
  networkId: feb96c822-631f-483f-a4b3-8eb4e87be9e9
  pool: publicIpPoolName
  project:
    domainName: domainName
    projectName: projectname
  subnetId: 9fe94282-36e8-42a9-8af9-fac6b68a8957
  user:
    domainName: domainName
    username: username1
    password: password1

OpenStack properties should be pretty straight-forward and well known for OpenStack Users.

This config is NOT mandatory if you don't plan any interaction with OpenStack for deployment/automation purposes.

Existing Endpoints

existing:
  endpoints:
    - server_name: platinum_cluster
      hosts: 
      - name: mongodb1
        ip: 172.16.105.3
        port: 27017
      - name: mongodb2
        ip: 172.16.105.4
        port: 27017
      - name: mongodb4
        ip: 172.16.105.5
        port: 27017      
      database: adminDatabase
      username: username1
      password: password1
    - server_name: gold_cluster
      hosts: 
      - name: mongodb1
        ip: 172.16.105.3
        port: 27017
      - name: mongodb2
        ip: 172.16.105.4
        port: 27017
      - name: mongodb4
        ip: 172.16.105.5
        port: 27017 
      database: adminDatabase
      username: username1
      password: password1

This section is a bit longer. It contains the definition for two existing endpoints. Important here is to define unique server_name and all the machines, which are needed to be contacted during service/binding creation, as well as the username/password and authentication database.

Java Version

The configuration of the service broker and the deployment manifest depends on the Java version you are working with. For version 9 or higher you have to add the following compiler arguments to maven-compiler-plugin in your pom.xml since the sun.* packages are no longer a part of the Java interface.

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<configuration>
		<source>${java.version}</source>
		<target>${java.version}</target>
		<compilerArgs>
			<arg>--add-exports</arg>
			<arg>java.base/sun.security.util=ALL-UNNAMED</arg>
		</compilerArgs>
	</configuration>
</plugin>

Also make sure to change to Java version in the pom.xml

<java.version>11</java.version>

Change the spring-boot-starter-parent version in the pom.xml as well

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.1.7.RELEASE</version>
</parent>

For deploying the service-broker on Cloud Foundry you also have to change the deployment manifest.yml. First you have to specify the buildpack version. For Java 12 this would be

buildpack: https://github.com/cloudfoundry/java-buildpack.git#v4.19.1

Furthermore if the spring cloud config is used, the spring-cloud.version has to be updated to the Greenwich release.

<spring-cloud.version>Greenwich.RELEASE</spring-cloud.version>

Last but not least add the following line to the environment section in the manifest and you are good to go.

env:
  JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 11.+ } }'

Catalog Configuration

The Catalog definition is an important part of the Service Broker deployment infrastructure. To demonstrate the implemented capabilites, we use the example of the osb-lbaas Catalog definition to show it capabilities:

catalog:
  services:
  - bindable: false
    plan_updateable: true
    dashboard:
      auth_endpoint: https://uaa.cf.domain.msh.host/oauth
      url: https://osb-lbaas.cf.domain.msh.host/v2/authentication
    dashboard_client:
      id: osb-lbaas.cf.domain.msh.host
      redirect_uri: https://osb-lbaas.cf.domain.msh.host/v2/authentication
      secret: DA2EDFE6-130C-4353-90EE-C202F2BD40F9
    description: LbaaS Instances
    id: 9F13ADE7-0AAC-468D-807F-3BD937FE530D
    name: osb-lbaas
    plans:
    - description: A simple LbaaS Bosh Deployment plan.
      free: false
      plan_updateable: false
      id: BB0DD792-C405-411C-B527-9771FE34B2D9
      metadata:
        connections: 1000
        instance_group_config:
        - name: haproxy
          properties:
            ha_proxy:
              stats_enable: false
              stats_password: me
              stats_user: overwrite
        networks:
        - default:
          - dns
          - gateway
          name: service
        - name: floating
        nodes: 1
        vm_type: minimal
      name: s
      platform: BOSH
    - description: A simple LbaaS Bosh Deployment plan.
      free: false
      id: CB0EE792-C405-411C-B527-9771FE53D329
      metadata:
        connections: 1000
        networks:
        - default:
          - dns
          - gateway
          name: service
        - name: floating
        nodes: 1
        vm_type: small
      name: m
      platform: BOSH

In the following sections we will explain the specifc details of a Catalog step by step.

Dashboard Client

When you are using the Dashboard and Core components of the OSB-Framework, the defintion of url and redirect_uri always need to point to /custom/v2/authentication, which is the endpoint for authentication and the delivery of the dashboard. Important here to note is, that the id should be multisite aware and the secret might be a UUID as seen below.

...
    dashboard:
      auth_endpoint: "https://uaa.cf.domain.com/oauth"
      url: "https://osb-lbaas.cf.domain.com/custom/v2/authentication"
    dashboard_client:
      id: osb-lbaas.cf.domain.com
      redirect_uri: "https://osb-lbaas.cf.domain.com/custom/v2/authentication"
      secret: DA2EDFE6-130C-4353-90EE-C202F2BD40F9

This framework uses spring boot resource server autoconfiguration. This means that all bearer tokens are checked by a Uaa or other identity provider. To ensure this, the issuer-url has to be configured like this:

...
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: "https://uaa.cf.domain.com/oauth/token"

Plans

The Plan definition is according to the Open Service Specification with extension made b the OSB Framework to provide a delcarative approach of feature enrichment on a plan level. This declarative approach enables Service Catalog managers, which are not necessarily developers to change/extend the Service Catalog without any coding.

All the important configurations you can make and are still compliant the the OSB-API standard are located in the metadata section of a Plan.

...
  plans:
  - name: s
    platform: BOSH
    description: A simple LbaaS Bosh Deployment plan.
    free: false
    id: BB0DD792-C405-411C-B527-9771FE34B2D9
    metadata:
      instance_group_config:
      - name: haproxy
        properties:
          ha_proxy:
            stats_enable: false
            stats_password: me
            stats_user: overwrite
      networks:
      - default:
        - dns
        - gateway
        name: service
      - name: floating
      nodes: 1
      vm_type: minimal
    schemas:
        service_binding:
          create:
            parameters:
              properties:
                admin:
                  description: is an admin
                  type: boolean
                connections:
                  description: connections
                  type: number
                database:
                  description: Specify the database for the service binding.
                  type: string
                list:
                  description: a simple list
                  type: array
              schema: http://json-schema.org/draft-04/schema#
              type: object
        service_instance:
          create:
            parameters:
              properties:
                mail:
                  description: mail for reference
                  pattern: ^[_a-z0-9-]+(.[a-z0-9-]+)@[a-z0-9-]+(.[a-z0-9-]+)*(.[a-z]{2,4})$
                  type: string
                name:
                  description: name of the db that will be created
                  maxLength: 7
                  minLength: 3
                  type: string
                value:
                  description: a value
                  maximum: 10
                  minimum: 2
                  type: integer
              schema: http://json-schema.org/draft-04/schema#
              type: object
...

Platform

The Platform in the plan section defines, which type of deployment should be called, when the Plan is requested. Currently the OSB Framework offers three different ways of deploying and instance:

  • EXISTING_FACTORY
  • BOSH
  • OPENSTACK (Deprecated)

Depending on the Platform that is configured there, the Service Broker needs to provide a specific implementation for it and automically searches for it. If the specific platform is not implemented the Service Broker throws an exception.

If there is an implementation, the PlatformService picks it up and provides all the information configured in the Plan Metadata.

Metadata

The Metadata section provides a fully customized section in the Plan definition of the Service Broker. We will go through the sub-sections one by one:

Configuration for all VMs

nodes: 1
vm_type: minimal
persistent_disk_type: 10GB
networks:
  - default:
    - dns
    - gateway
    name: service
  - name: floating
custom_parameters:
  property_one: value_one
  • nodes: overwrites the number of instances for all VMs in all Instance Groups of the Bosh Deployment Manifest.
  • vm_type: overwrites the VM Type for all VMs in all Instance Groups of the Bosh Deployment Manifest.
  • persistent_disk_type: overwrites the Persistent Disk Type for all VMs in all Instance Groups of the Bosh Deployment Manifest.
  • networks: overwrites the networks in all VMs in all Instance Groups of the Bosh Deployment Manifest. It currently supports multi network overwrites (and also floating networks with VIPs). The only important thing here is: the name and number of networks in the Metadata definition need to match the networks in the Bosh Deployment Manifest within the Service Broker.

Instance Group Specific Configuration of VMs

instance_group_config:
- name: haproxy
  nodes: 1
  vm_type: minimal
  persistent_disk_type: 10GB
  networks:
    - default:
      - dns
      - gateway
      name: service
    - name: floating
  properties:
    ha_proxy:
      stats_enable: false
      stats_password: me
      stats_user: overwrite
  • nodes: overwrites the number of instances for a specific Instance Group of the Bosh Deployment Manifest.
  • vm_type: overwrites the VM Type for a specific Instance Group of the Bosh Deployment Manifest.
  • persistent_disk_type: overwrites the Persistent Disk Type for a specific Instance Group of the Bosh Deployment Manifest.
  • networks: overwrites the networks in a specific Instance Group of the Bosh Deployment Manifest. It currently supports multi network overwrites (and also floating networks with VIPs). The only important thing here is: the name and number of networks in the Metadata definition need to match the networks in the Bosh Deployment Manifest within the Service Broker.
  • properties: overwrites values for a specific Job in an Instance Group. These configuration properties, which rely to the Instance Group and are defined in the Bosh Spec of a Job.
schemas:
    service_binding:
        create:
        parameters:
            properties:
            admin:
                description: is an admin
                type: boolean
            connections:
                description: connections
                type: number
            database:
                description: Specify the database for the service binding.
                type: string
            list:
                description: a simple list
                type: array
            schema: http://json-schema.org/draft-04/schema#
            type: object
    service_instance:
        create:
        parameters:
            properties:
            mail:
                description: mail for reference
                pattern: ^[_a-z0-9-]+(.[a-z0-9-]+)@[a-z0-9-]+(.[a-z0-9-]+)*(.[a-z]{2,4})$
                type: string
            name:
                description: name of the db that will be created
                maxLength: 7
                minLength: 3
                type: string
            value:
                description: a value
                maximum: 10
                minimum: 2
                type: integer
            schema: http://json-schema.org/draft-04/schema#
            type: object

The OSB Framework offers complete support for the JSON Schema Defintion to provide additional and predefined parameters during Service Instance Creation/Update and Service Bindings.

(Partially Optional): Custom Dashboard Endpoints

endpoints:
  custom:
  - identifier: osb-backup-manager
    url: https://osb-backup-manager.cf.dev.eu-de-central.msh.host
  - identifier: osb-log-metric-backend
    url: https://osb-log-metric-dashboard-backend.cf.dev.eu-de-central.msh.host
  - identifier: osb-autoscaler-core
    url: https://osb-autoscaler-core.cf.dev.eu-de-central.msh.host
  default: https://osb-couchdb.cf.dev.eu-de-central.msh.host

(Optional): Enabling Service Keys To enable the handling and creation of Service Keys in the Service Broker, add and set the following property to true in your configuration.

service-keys:
    enabled: true

Note: To enable Service Keys via Service Broker Dashboard in UI see Dashboard section and configure serviceKeys: true in the module definition.

sharedModules: {
  general: true,
  backup: false,
  serviceKeys: true // This needs to be set to true
}

(Optional): Site Configuration

site:
  properties:
    osb-lbaas:
      backend_servers:
      - 10.0.8.13
      tcp_backend_servers:
      - 10.0.8.14

The Site Configuration is an additional way of configuring the Service Broker with custom properties, which are Site specific. In this example we see the configuration of IPs of backend servers, which are used to configure the Service Broker Deployment Manifest during deployment time.

Catalog Validation

This part describes how to configure the optional catalog validation of the service broker. When activated, a validation is performed during startup of the broker and logs are generated according to the result of the validation process. At this point in time, the catalog validator contains following checks:

  • Check whether the ids of the service definitions and service plans are GUIDs
  • Check whether the catalog has at least one service definition and each service definition has at least one service plan
  • Check whether the version string of maintenance_info of each plan is in line with Semantic Versioning 2 (if maintenance_info object is present)
config:
  catalog:
    validate: true
    strict: true

To enable catalog validation set validate: true and for a strict validation process set strict: true. A strict validation process will cancel the startup if the catalog is invalid, so set this flag with caution.

SSL Certificates

To trust additional ssl certificates you can configure them like in the example below.

spring:
  ssl:
    certificates:
      uaa_ssl: |
        -----BEGIN CERTIFICATE-----
        .....
         -----END CERTIFICATE-----
      credhub_ca: |
        -----BEGIN CERTIFICATE-----
        .....
         -----END CERTIFICATE-----

It is also possible to disable SSL certificate to allowing the service broker to accept all. However, this should NOT be used in production.

spring:
  ssl:
    acceptselfsigned: true

<- Previous   |   Next ->