brokerapi

README

brokerapi

A go package for building V2 CF Service Brokers in Go. Depends on lager and gorilla/mux.

Requires go 1.4 or greater.

Usage

brokerapi defines a ServiceBroker interface with 5 methods. Simply create a concrete type that implements these methods, and pass an instance of it to brokerapi.New, along with a lager.Logger for logging and a brokerapi.BrokerCredentials containing some HTTP basic auth credentials.

e.g.

package main

import (
    "github.com/pivotal-cf/brokerapi"
    "github.com/pivotal-golang/lager"
)

type myServiceBroker struct {}

func (*myServiceBroker) Services() []brokerapi.Service {
    // Return a []brokerapi.Service here, describing your service(s) and plan(s)
}

func (*myServiceBroker) Provision(instanceID string, details brokerapi.ProvisionDetails) error {
    // Provision a new instance here
}

func (*myServiceBroker) Deprovision(instanceID string) error {
    // Deprovision instances here
}

func (*myServiceBroker) Bind(instanceID, bindingID string, details brokerapi.BindDetails) (interface{}, error) {
    // Bind to instances here
    // Return credentials which will be marshalled to JSON
}

func (*myServiceBroker) Unbind(instanceID, bindingID string) error {
    // Unbind from instances here
}

func main() {
    serviceBroker := &myServiceBroker{}
    logger := lager.NewLogger("my-service-broker")
    credentials := brokerapi.BrokerCredentials{
        Username: "username",
        Password: "password",
    }

    brokerAPI := brokerapi.New(serviceBroker, logger, credentials)
    http.Handle("/", brokerAPI)
    http.ListenAndServe(":3000", nil)
}

Errors

brokerapi defines a handful of error types in service_broker.go for some common error cases that your service broker may encounter. Return these from your ServiceBroker methods where appropriate, and brokerapi will do the right thing, and give Cloud Foundry an appropriate status code, as per the V2 Service Broker API specification.

The error types are:

ErrInstanceAlreadyExists
ErrInstanceDoesNotExist
ErrInstanceLimitMet
ErrBindingAlreadyExists
ErrBindingDoesNotExist

Change Notes

• d97ebdd adds a new map property to the brokerapi.BindDetails struct in order to support arbitrary bind parameters. This allows API clients to send configuration parameters with their bind request.
• Starting with 10997ba the Bind function now takes an additional input parameter of type brokerapi.BindDetails. The corresponding struct specifies bind-specific properties sent by the CF API client.
• 8d9dd34 adds support for arbitrary provision parameters. The broker can access the Parameters map in brokerapi.ProvisionDetails to lookup any configuration parameters sent by the client as part of their provision request.

Documentation

Index

• Variables
• func New(serviceBroker ServiceBroker, logger lager.Logger, ...) http.Handler
• type BindDetails
• type BindingResponse
• type BrokerCredentials
• type CatalogResponse
• type EmptyResponse
• type ErrorResponse
• type ProvisionDetails
• type ProvisioningResponse
• type Service
• type ServiceBroker
• type ServiceMetadata
• type ServiceMetadataListing
• type ServiceMetadataProvider
• type ServicePlan
• type ServicePlanMetadata

Variables

var (
	ErrInstanceAlreadyExists = errors.New("instance already exists")
	ErrInstanceDoesNotExist  = errors.New("instance does not exist")
	ErrInstanceLimitMet      = errors.New("instance limit for this service has been reached")
	ErrBindingAlreadyExists  = errors.New("binding already exists")
	ErrBindingDoesNotExist   = errors.New("binding does not exist")
)

Functions

func New

func New(serviceBroker ServiceBroker, logger lager.Logger, brokerCredentials BrokerCredentials) http.Handler

Types

type BindDetails

type BindDetails struct {
	AppGUID    string                 `json:"app_guid"`
	PlanID     string                 `json:"plan_id"`
	ServiceID  string                 `json:"service_id"`
	Parameters map[string]interface{} `json:"parameters"`
}

type BindingResponse

type BindingResponse struct {
	Credentials interface{} `json:"credentials"`
}

type BrokerCredentials

type BrokerCredentials struct {
	Username string
	Password string
}

type CatalogResponse

type CatalogResponse struct {
	Services []Service `json:"services"`
}

type EmptyResponse

type EmptyResponse struct{}

type ErrorResponse

type ErrorResponse struct {
	Description string `json:"description"`
}

type ProvisionDetails

type ProvisionDetails struct {
	ID               string                 `json:"service_id"`
	PlanID           string                 `json:"plan_id"`
	OrganizationGUID string                 `json:"organization_guid"`
	SpaceGUID        string                 `json:"space_guid"`
	Parameters       map[string]interface{} `json:"parameters"`
}

type ProvisioningResponse

type ProvisioningResponse struct {
	DashboardURL string `json:"dashboard_url,omitempty"`
}

type Service

type Service struct {
	ID          string          `json:"id"`
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Bindable    bool            `json:"bindable"`
	Plans       []ServicePlan   `json:"plans"`
	Metadata    ServiceMetadata `json:"metadata"`
	Tags        []string        `json:"tags"`
}

type ServiceBroker

type ServiceBroker interface {
	Services() []Service

	Provision(instanceID string, details ProvisionDetails) error
	Deprovision(instanceID string) error

	Bind(instanceID, bindingID string, details BindDetails) (interface{}, error)
	Unbind(instanceID, bindingID string) error
}

type ServiceMetadata

type ServiceMetadata struct {
	DisplayName      string                  `json:"displayName"`
	LongDescription  string                  `json:"longDescription"`
	DocumentationUrl string                  `json:"documentationUrl"`
	SupportUrl       string                  `json:"supportUrl"`
	Listing          ServiceMetadataListing  `json:"listing"`
	Provider         ServiceMetadataProvider `json:"provider"`
}

type ServiceMetadataListing

type ServiceMetadataListing struct {
	Blurb    string `json:"blurb"`
	ImageUrl string `json:"imageUrl"`
}

type ServiceMetadataProvider

type ServiceMetadataProvider struct {
	Name string `json:"name"`
}

type ServicePlan

type ServicePlan struct {
	ID          string              `json:"id"`
	Name        string              `json:"name"`
	Description string              `json:"description"`
	Metadata    ServicePlanMetadata `json:"metadata"`
}

type ServicePlanMetadata

type ServicePlanMetadata struct {
	Bullets     []string `json:"bullets"`
	DisplayName string   `json:"displayName"`
}