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 7 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,
    asyncAllowed bool,
) (brokerapi.ProvisionedServiceSpec, error) {
    // Provision a new instance here. If async is allowed, the broker can still
    // chose to provision the instance synchronously.
}

func (*myServiceBroker) LastOperation(instanceID string) (brokerapi.LastOperation, error) {
    // If the broker provisions asynchronously, the Cloud Controller will poll this endpoint
    // for the status of the provisioning operation.
    // This also applies to deprovisioning (work in progress).
}

func (*myServiceBroker) Deprovision(instanceID string, details brokerapi.DeprovisionDetails, asyncAllowed bool) (brokerapi.IsAsync, error) {
    // Deprovision a new instance here. If async is allowed, the broker can still
    // chose to deprovision the instance synchronously, hence the first return value.
}

func (*myServiceBroker) Bind(instanceID, bindingID string, details brokerapi.BindDetails) (brokerapi.Binding, error) {
    // Bind to instances here
    // Return a binding which contains a credentials object that can be marshalled to JSON,
    // and (optionally) a syslog drain URL.
}

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

func (*myServiceBroker) Update(instanceID string, details brokerapi.UpdateDetails, asyncAllowed bool) (brokerapi.IsAsync, error) {
  // Update instance 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
ErrAsyncRequired

Change Notes

• 724bdb1 adds a new parameter and return type to Provision method of ServiceBroker to support asynchronous provisioning. Also adds LastOperation method for the same purpose.
• 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

• Constants
• Variables
• func AttachRoutes(router *mux.Router, serviceBroker ServiceBroker, logger lager.Logger)
• func FreeValue(v bool) *bool
• func New(serviceBroker ServiceBroker, logger lager.Logger, ...) http.Handler
• type BindDetails
• type BindResource
• type Binding
• type BrokerCredentials
• type CatalogResponse
• type DeprovisionDetails
• type EmptyResponse
• type ErrorResponse
• type IsAsync
• type LastOperation
• type LastOperationResponse
• type LastOperationState
• type PreviousValues
• type ProvisionDetails
• type ProvisionedServiceSpec
• type ProvisioningResponse
• type RequiredPermission
• type Service
• type ServiceBroker
• type ServiceCost
• type ServiceDashboardClient
• type ServiceMetadata
• type ServicePlan
• type ServicePlanMetadata
• type UnbindDetails
• type UpdateDetails

Constants

const (
	PermissionRouteForwarding = RequiredPermission("route_forwarding")
	PermissionSyslogDrain     = RequiredPermission("syslog_drain")
)

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")
	ErrAsyncRequired          = errors.New("This service plan requires client support for asynchronous service operations.")
	ErrPlanChangeNotSupported = errors.New("The requested plan migration cannot be performed")
	ErrRawParamsInvalid       = errors.New("The format of the parameters is not valid JSON")
)

Functions

func AttachRoutes

func AttachRoutes(router *mux.Router, serviceBroker ServiceBroker, logger lager.Logger)

func FreeValue

func FreeValue(v bool) *bool

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"`
	BindResource *BindResource          `json:"bind_resource,omitempty"`
	Parameters   map[string]interface{} `json:"parameters,omitempty"`
}

type BindResource

type BindResource struct {
	AppGuid string `json:"app_guid,omitempty"`
	Route   string `json:"route,omitempty"`
}

type Binding

type Binding struct {
	Credentials    interface{} `json:"credentials"`
	SyslogDrainURL string      `json:"syslog_drain_url,omitempty"`
}

type BrokerCredentials

type BrokerCredentials struct {
	Username string
	Password string
}

type CatalogResponse

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

type DeprovisionDetails

type DeprovisionDetails struct {
	PlanID    string `json:"plan_id"`
	ServiceID string `json:"service_id"`
}

type EmptyResponse

type EmptyResponse struct{}

type ErrorResponse

type ErrorResponse struct {
	Error       string `json:"error,omitempty"`
	Description string `json:"description"`
}

type IsAsync

type IsAsync bool

type LastOperation

type LastOperation struct {
	State       LastOperationState
	Description string
}

type LastOperationResponse

type LastOperationResponse struct {
	State       string `json:"state"`
	Description string `json:"description,omitempty"`
}

type LastOperationState

type LastOperationState string

const (
	InProgress LastOperationState = "in progress"
	Succeeded  LastOperationState = "succeeded"
	Failed     LastOperationState = "failed"
)

type PreviousValues

type PreviousValues struct {
	PlanID    string `json:"plan_id"`
	ServiceID string `json:"service_id"`
	OrgID     string `json:"organization_id"`
	SpaceID   string `json:"space_id"`
}

type ProvisionDetails

type ProvisionDetails struct {
	ServiceID        string          `json:"service_id"`
	PlanID           string          `json:"plan_id"`
	OrganizationGUID string          `json:"organization_guid"`
	SpaceGUID        string          `json:"space_guid"`
	RawParameters    json.RawMessage `json:"parameters,omitempty"`
}

type ProvisionedServiceSpec

type ProvisionedServiceSpec struct {
	IsAsync      bool
	DashboardURL string
}

type ProvisioningResponse

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

type RequiredPermission

type RequiredPermission string

type Service

type Service struct {
	ID              string                  `json:"id"`
	Name            string                  `json:"name"`
	Description     string                  `json:"description"`
	Bindable        bool                    `json:"bindable"`
	Tags            []string                `json:"tags,omitempty"`
	PlanUpdatable   bool                    `json:"plan_updateable"`
	Plans           []ServicePlan           `json:"plans"`
	Requires        []RequiredPermission    `json:"requires,omitempty"`
	Metadata        *ServiceMetadata        `json:"metadata,omitempty"`
	DashboardClient *ServiceDashboardClient `json:"dashboard_client,omitempty"`
}

type ServiceBroker

type ServiceBroker interface {
	Services() []Service

	Provision(instanceID string, details ProvisionDetails, asyncAllowed bool) (ProvisionedServiceSpec, error)
	Deprovision(instanceID string, details DeprovisionDetails, asyncAllowed bool) (IsAsync, error)

	Bind(instanceID, bindingID string, details BindDetails) (Binding, error)
	Unbind(instanceID, bindingID string, details UnbindDetails) error

	Update(instanceID string, details UpdateDetails, asyncAllowed bool) (IsAsync, error)

	LastOperation(instanceID string) (LastOperation, error)
}

type ServiceCost

type ServiceCost struct {
	Amount map[string]float64 `json:"amount"`
	Unit   string             `json:"unit"`
}

type ServiceDashboardClient

type ServiceDashboardClient struct {
	ID          string `json:"id"`
	Secret      string `json:"secret"`
	RedirectURI string `json:"redirect_uri"`
}

type ServiceMetadata

type ServiceMetadata struct {
	DisplayName         string `json:"displayName,omitempty"`
	ImageUrl            string `json:"imageUrl,omitempty"`
	LongDescription     string `json:"longDescription,omitempty"`
	ProviderDisplayName string `json:"providerDisplayName,omitempty"`
	DocumentationUrl    string `json:"documentationUrl,omitempty"`
	SupportUrl          string `json:"supportUrl,omitempty"`
}

type ServicePlan

type ServicePlan struct {
	ID          string               `json:"id"`
	Name        string               `json:"name"`
	Description string               `json:"description"`
	Free        *bool                `json:"free,omitempty"`
	Metadata    *ServicePlanMetadata `json:"metadata,omitempty"`
}

type ServicePlanMetadata

type ServicePlanMetadata struct {
	DisplayName string        `json:"displayName,omitempty"`
	Bullets     []string      `json:"bullets,omitempty"`
	Costs       []ServiceCost `json:"costs,omitempty"`
}

type UnbindDetails

type UnbindDetails struct {
	PlanID    string `json:"plan_id"`
	ServiceID string `json:"service_id"`
}

type UpdateDetails

type UpdateDetails struct {
	ServiceID      string                 `json:"service_id"`
	PlanID         string                 `json:"plan_id"`
	Parameters     map[string]interface{} `json:"parameters"`
	PreviousValues PreviousValues         `json:"previous_values"`
}