README

BBS Server GoDoc

Note: This repository should be imported as code.cloudfoundry.org/bbs.

API to access the database for Diego.

A general overview of the BBS is documented here.

Reporting issues and requesting features

Please report all issues and feature requests in cloudfoundry/diego-release.

API

To interact with the BBS from outside of Diego, use the methods provided on the Client interface.

Components within Diego may use the full InternalClient interface to modify internal state.

Code Generation

The protobuf models in this repository require version 3.5 or later of the protoc compiler.

OSX

On Mac OS X with Homebrew, run the following to install it:

brew install protobuf
Linux
  1. Download a zip archive of the latest protobuf release from here.
  2. Unzip the archive in /usr/local.
  3. chmod a+x /usr/local/bin/protoc to make sure you can use the binary.

If you already have an older version of protobuf installed, you must uninstall it first by running brew uninstall protobuf

Install the gogoproto compiler by running:

go install github.com/gogo/protobuf/protoc-gen-gogoslick

Run go generate ./... from the root directory of this repository to generate code from the .proto files as well as to generate fake implementations of certain interfaces for use in test code.

Generating ruby models for BBS models

The following documentation assume the following versions:

  1. protoc > v3.5.0
  2. ruby protobuf gem > 3.6.12

Run the following commands from the models directory to generate .pb.rb files for the BBS models:

  1. gem install protobuf
  2. cp $(which protoc-gen-ruby){,2}
  3. protoc -I$GOPATH/src --proto_path=. --ruby2_out=/path/to/ruby/files *.proto

Note Replace /path/to/ruby/files with the desired destination of the .pb.rb files. That directory must exist before running this command.

Note The above steps assume that github.com/gogo/protobuf/gogoproto/gogo.proto is on the GOPATH.

Note Since protoc v3 now ships with a ruby generator, the built-in generator will mask the gem's binary. This requires a small hack in order to be able to use the protobuf gem, the hack is simply to rename the protobuf gem's binary to be ruby2 and ask protoc to generate ruby2 code which will force it to use the binary. For more information please read this github issue

SQL

See the instructions in Running the SQL Unit Tests for testing against a SQL backend

See Migrations for information about writing database migrations.

Run Tests

  1. First setup your GOPATH and install the necessary dependencies for running tests.
  2. Setup a MySQL server or a postgres server. Please follow these instructions.
  3. Run the tests from the root directory of the bbs repo:
SQL_FLAVOR=mysql ginkgo -r -p -race
Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const (
	ContentTypeHeader    = "Content-Type"
	XCfRouterErrorHeader = "X-Cf-Routererror"
	ProtoContentType     = "application/x-protobuf"
	KeepContainer        = true
	DeleteContainer      = false
	DefaultRetryCount    = 3
)
View Source
const (
	// Ping
	PingRoute_r0 = "Ping"

	// Domains
	DomainsRoute_r0      = "Domains"
	UpsertDomainRoute_r0 = "UpsertDomain"

	// Actual LRPs
	ActualLRPsRoute_r0                          = "ActualLRPs"
	ActualLRPGroupsRoute_r0                     = "ActualLRPGroups"                      // DEPRECATED
	ActualLRPGroupsByProcessGuidRoute_r0        = "ActualLRPGroupsByProcessGuid"         // DEPRECATED
	ActualLRPGroupByProcessGuidAndIndexRoute_r0 = "ActualLRPGroupsByProcessGuidAndIndex" // DEPRECATED

	// Actual LRP Lifecycle
	ClaimActualLRPRoute_r0  = "ClaimActualLRP"
	StartActualLRPRoute_r0  = "StartActualLRP"
	CrashActualLRPRoute_r0  = "CrashActualLRP"
	FailActualLRPRoute_r0   = "FailActualLRP"
	RemoveActualLRPRoute_r0 = "RemoveActualLRP"
	RetireActualLRPRoute_r0 = "RetireActualLRP"

	// Evacuation
	RemoveEvacuatingActualLRPRoute_r0 = "RemoveEvacuatingActualLRP"
	EvacuateClaimedActualLRPRoute_r0  = "EvacuateClaimedActualLRP"
	EvacuateCrashedActualLRPRoute_r0  = "EvacuateCrashedActualLRP"
	EvacuateStoppedActualLRPRoute_r0  = "EvacuateStoppedActualLRP"
	EvacuateRunningActualLRPRoute_r0  = "EvacuateRunningActualLRP"

	// Desired LRPs
	DesiredLRPsRoute_r3               = "DesiredLRPs"
	DesiredLRPSchedulingInfosRoute_r0 = "DesiredLRPSchedulingInfos"
	DesiredLRPByProcessGuidRoute_r3   = "DesiredLRPByProcessGuid"
	DesiredLRPsRoute_r2               = "DesiredLRPs_r2"             // DEPRECATED
	DesiredLRPByProcessGuidRoute_r2   = "DesiredLRPByProcessGuid_r2" // DEPRECATED

	// Desire LRP Lifecycle
	DesireDesiredLRPRoute_r2 = "DesireDesiredLRP"
	UpdateDesiredLRPRoute_r0 = "UpdateDesireLRP"
	RemoveDesiredLRPRoute_r0 = "RemoveDesiredLRP"

	// Tasks
	TasksRoute_r3         = "Tasks"
	TaskByGuidRoute_r3    = "TaskByGuid"
	DesireTaskRoute_r2    = "DesireTask"
	StartTaskRoute_r0     = "StartTask"
	CancelTaskRoute_r0    = "CancelTask"
	FailTaskRoute_r0      = "FailTask" // DEPRECATED
	RejectTaskRoute_r0    = "RejectTask"
	CompleteTaskRoute_r0  = "CompleteTask"
	ResolvingTaskRoute_r0 = "ResolvingTask"
	DeleteTaskRoute_r0    = "DeleteTask"
	TasksRoute_r2         = "Tasks_r2"      // DEPRECATED
	TaskByGuidRoute_r2    = "TaskByGuid_r2" // DEPRECATED

	// Event Streaming
	LRPGroupEventStreamRoute_r1    = "EventStream" // DEPRECATED
	TaskEventStreamRoute_r1        = "TaskEventStream"
	LRPInstanceEventStreamRoute_r1 = "LRPInstanceEventStream"
	EventStreamRoute_r0            = "EventStream_r0"            // DEPRECATED
	TaskEventStreamRoute_r0        = "TaskEventStream_r0"        // DEPRECATED
	LrpInstanceEventStreamRoute_r0 = "LrpInstanceEventStream_r0" // DEPRECATED

	// Cell Presence
	CellsRoute_r0 = "Cells"
)

Variables

View Source
var Routes = rata.Routes{

	{Path: "/v1/ping", Method: "POST", Name: PingRoute_r0},

	{Path: "/v1/domains/list", Method: "POST", Name: DomainsRoute_r0},
	{Path: "/v1/domains/upsert", Method: "POST", Name: UpsertDomainRoute_r0},

	{Path: "/v1/actual_lrps/list", Method: "POST", Name: ActualLRPsRoute_r0},
	{Path: "/v1/actual_lrp_groups/list", Method: "POST", Name: ActualLRPGroupsRoute_r0},
	{Path: "/v1/actual_lrp_groups/list_by_process_guid", Method: "POST", Name: ActualLRPGroupsByProcessGuidRoute_r0},
	{Path: "/v1/actual_lrp_groups/get_by_process_guid_and_index", Method: "POST", Name: ActualLRPGroupByProcessGuidAndIndexRoute_r0},

	{Path: "/v1/actual_lrps/claim", Method: "POST", Name: ClaimActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/start", Method: "POST", Name: StartActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/crash", Method: "POST", Name: CrashActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/fail", Method: "POST", Name: FailActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/remove", Method: "POST", Name: RemoveActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/retire", Method: "POST", Name: RetireActualLRPRoute_r0},

	{Path: "/v1/actual_lrps/remove_evacuating", Method: "POST", Name: RemoveEvacuatingActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/evacuate_claimed", Method: "POST", Name: EvacuateClaimedActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/evacuate_crashed", Method: "POST", Name: EvacuateCrashedActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/evacuate_stopped", Method: "POST", Name: EvacuateStoppedActualLRPRoute_r0},
	{Path: "/v1/actual_lrps/evacuate_running", Method: "POST", Name: EvacuateRunningActualLRPRoute_r0},

	{Path: "/v1/desired_lrp_scheduling_infos/list", Method: "POST", Name: DesiredLRPSchedulingInfosRoute_r0},

	{Path: "/v1/desired_lrps/list.r3", Method: "POST", Name: DesiredLRPsRoute_r3},
	{Path: "/v1/desired_lrps/get_by_process_guid.r3", Method: "POST", Name: DesiredLRPByProcessGuidRoute_r3},
	{Path: "/v1/desired_lrps/list.r2", Method: "POST", Name: DesiredLRPsRoute_r2},
	{Path: "/v1/desired_lrps/get_by_process_guid.r2", Method: "POST", Name: DesiredLRPByProcessGuidRoute_r2},

	{Path: "/v1/desired_lrp/desire.r2", Method: "POST", Name: DesireDesiredLRPRoute_r2},
	{Path: "/v1/desired_lrp/update", Method: "POST", Name: UpdateDesiredLRPRoute_r0},
	{Path: "/v1/desired_lrp/remove", Method: "POST", Name: RemoveDesiredLRPRoute_r0},

	{Path: "/v1/tasks/list.r3", Method: "POST", Name: TasksRoute_r3},
	{Path: "/v1/tasks/get_by_task_guid.r3", Method: "POST", Name: TaskByGuidRoute_r3},
	{Path: "/v1/tasks/list.r2", Method: "POST", Name: TasksRoute_r2},
	{Path: "/v1/tasks/get_by_task_guid.r2", Method: "POST", Name: TaskByGuidRoute_r2},

	{Path: "/v1/tasks/desire.r2", Method: "POST", Name: DesireTaskRoute_r2},
	{Path: "/v1/tasks/start", Method: "POST", Name: StartTaskRoute_r0},
	{Path: "/v1/tasks/cancel", Method: "POST", Name: CancelTaskRoute_r0},
	{Path: "/v1/tasks/fail", Method: "POST", Name: FailTaskRoute_r0},
	{Path: "/v1/tasks/reject", Method: "POST", Name: RejectTaskRoute_r0},
	{Path: "/v1/tasks/complete", Method: "POST", Name: CompleteTaskRoute_r0},
	{Path: "/v1/tasks/resolving", Method: "POST", Name: ResolvingTaskRoute_r0},
	{Path: "/v1/tasks/delete", Method: "POST", Name: DeleteTaskRoute_r0},

	{Path: "/v1/events.r1", Method: "GET", Name: LRPGroupEventStreamRoute_r1},
	{Path: "/v1/events/tasks.r1", Method: "POST", Name: TaskEventStreamRoute_r1},
	{Path: "/v1/events/lrp_instances.r1", Method: "POST", Name: LRPInstanceEventStreamRoute_r1},
	{Path: "/v1/events", Method: "GET", Name: EventStreamRoute_r0},
	{Path: "/v1/events/tasks", Method: "POST", Name: TaskEventStreamRoute_r0},
	{Path: "/v1/events/lrp_instances", Method: "POST", Name: LrpInstanceEventStreamRoute_r0},

	{Path: "/v1/cells/list.r1", Method: "POST", Name: CellsRoute_r0},
}

Functions

This section is empty.

Types

type Client

type Client interface {
	ExternalTaskClient
	ExternalDomainClient
	ExternalActualLRPClient
	ExternalDesiredLRPClient
	ExternalEventClient

	// Returns true if the BBS server is reachable
	Ping(logger lager.Logger) bool

	// Lists all Cells
	Cells(logger lager.Logger) ([]*models.CellPresence, error)
}

    The External InternalClient can be used to access the BBS's public functionality. It exposes methods for basic LRP and Task Lifecycles, Domain manipulation, and event subscription.

    type ClientConfig

    type ClientConfig struct {
    	URL                    string
    	IsTLS                  bool
    	CAFile                 string
    	CertFile               string
    	KeyFile                string
    	ClientSessionCacheSize int
    	MaxIdleConnsPerHost    int
    	InsecureSkipVerify     bool
    	Retries                int
    	RequestTimeout         time.Duration // Only affects the http client, not the streaming client
    }

    type ExternalActualLRPClient

    type ExternalActualLRPClient interface {
    	// Returns all ActualLRPs matching the given ActualLRPFilter
    	ActualLRPs(lager.Logger, models.ActualLRPFilter) ([]*models.ActualLRP, error)
    
    	// DEPRECATED
    	// Returns all ActualLRPGroups matching the given ActualLRPFilter
    	ActualLRPGroups(lager.Logger, models.ActualLRPFilter) ([]*models.ActualLRPGroup, error)
    
    	// DEPRECATED
    	// Returns all ActualLRPGroups that have the given process guid
    	ActualLRPGroupsByProcessGuid(logger lager.Logger, processGuid string) ([]*models.ActualLRPGroup, error)
    
    	// DEPRECATED
    	// Returns the ActualLRPGroup with the given process guid and instance index
    	ActualLRPGroupByProcessGuidAndIndex(logger lager.Logger, processGuid string, index int) (*models.ActualLRPGroup, error)
    
    	// Shuts down the ActualLRP matching the given ActualLRPKey, but does not modify the desired state
    	RetireActualLRP(logger lager.Logger, key *models.ActualLRPKey) error
    }

      The ExternalActualLRPClient is used to access and retire Actual LRPs

      type ExternalDesiredLRPClient

      type ExternalDesiredLRPClient interface {
      	// Lists all DesiredLRPs that match the given DesiredLRPFilter
      	DesiredLRPs(lager.Logger, models.DesiredLRPFilter) ([]*models.DesiredLRP, error)
      
      	// Returns the DesiredLRP with the given process guid
      	DesiredLRPByProcessGuid(logger lager.Logger, processGuid string) (*models.DesiredLRP, error)
      
      	// Returns all DesiredLRPSchedulingInfos that match the given DesiredLRPFilter
      	DesiredLRPSchedulingInfos(lager.Logger, models.DesiredLRPFilter) ([]*models.DesiredLRPSchedulingInfo, error)
      
      	// Creates the given DesiredLRP and its corresponding ActualLRPs
      	DesireLRP(lager.Logger, *models.DesiredLRP) error
      
      	// Updates the DesiredLRP matching the given process guid
      	UpdateDesiredLRP(logger lager.Logger, processGuid string, update *models.DesiredLRPUpdate) error
      
      	// Removes the DesiredLRP matching the given process guid
      	RemoveDesiredLRP(logger lager.Logger, processGuid string) error
      }

        The ExternalDesiredLRPClient is used to access and manipulate Disired LRPs.

        type ExternalDomainClient

        type ExternalDomainClient interface {
        	// Lists the active domains
        	Domains(logger lager.Logger) ([]string, error)
        
        	// Creates a domain or bumps the ttl on an existing domain
        	UpsertDomain(logger lager.Logger, domain string, ttl time.Duration) error
        }

          The ExternalDomainClient is used to access and update Diego's domains.

          type ExternalEventClient

          type ExternalEventClient interface {
          	// DEPRECATED
          	SubscribeToEvents(logger lager.Logger) (events.EventSource, error)
          
          	SubscribeToInstanceEvents(logger lager.Logger) (events.EventSource, error)
          	SubscribeToTaskEvents(logger lager.Logger) (events.EventSource, error)
          
          	// DEPRECATED
          	SubscribeToEventsByCellID(logger lager.Logger, cellId string) (events.EventSource, error)
          
          	SubscribeToInstanceEventsByCellID(logger lager.Logger, cellId string) (events.EventSource, error)
          }

            The ExternalEventClient is used to subscribe to groups of Events.

            type ExternalTaskClient

            type ExternalTaskClient interface {
            	// Creates a Task from the given TaskDefinition
            	DesireTask(logger lager.Logger, guid, domain string, def *models.TaskDefinition) error
            
            	// Lists all Tasks
            	Tasks(logger lager.Logger) ([]*models.Task, error)
            
            	// List all Tasks that match filter
            	TasksWithFilter(logger lager.Logger, filter models.TaskFilter) ([]*models.Task, error)
            
            	// Lists all Tasks of the given domain
            	TasksByDomain(logger lager.Logger, domain string) ([]*models.Task, error)
            
            	// Lists all Tasks on the given cell
            	TasksByCellID(logger lager.Logger, cellId string) ([]*models.Task, error)
            
            	// Returns the Task with the given guid
            	TaskByGuid(logger lager.Logger, guid string) (*models.Task, error)
            
            	// Cancels the Task with the given task guid
            	CancelTask(logger lager.Logger, taskGuid string) error
            
            	// Resolves a Task with the given guid
            	ResolvingTask(logger lager.Logger, taskGuid string) error
            
            	// Deletes a completed task with the given guid
            	DeleteTask(logger lager.Logger, taskGuid string) error
            }

              The ExternalTaskClient is used to access Diego's ability to run one-off tasks. More information about this API can be found in the bbs docs:

              https://code.cloudfoundry.org/bbs/tree/master/doc/tasks.md

              type InternalClient

              type InternalClient interface {
              	Client
              
              	ClaimActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey) error
              	StartActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, netInfo *models.ActualLRPNetInfo) error
              	CrashActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, errorMessage string) error
              	FailActualLRP(logger lager.Logger, key *models.ActualLRPKey, errorMessage string) error
              	RemoveActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey) error
              
              	EvacuateClaimedActualLRP(lager.Logger, *models.ActualLRPKey, *models.ActualLRPInstanceKey) (bool, error)
              	EvacuateRunningActualLRP(lager.Logger, *models.ActualLRPKey, *models.ActualLRPInstanceKey, *models.ActualLRPNetInfo) (bool, error)
              	EvacuateStoppedActualLRP(lager.Logger, *models.ActualLRPKey, *models.ActualLRPInstanceKey) (bool, error)
              	EvacuateCrashedActualLRP(lager.Logger, *models.ActualLRPKey, *models.ActualLRPInstanceKey, string) (bool, error)
              	RemoveEvacuatingActualLRP(lager.Logger, *models.ActualLRPKey, *models.ActualLRPInstanceKey) error
              
              	StartTask(logger lager.Logger, taskGuid string, cellID string) (bool, error)
              	FailTask(logger lager.Logger, taskGuid, failureReason string) error
              	RejectTask(logger lager.Logger, taskGuid, failureReason string) error
              	CompleteTask(logger lager.Logger, taskGuid, cellId string, failed bool, failureReason, result string) error
              }

                The InternalClient interface exposes all available endpoints of the BBS server, including private endpoints which should be used exclusively by internal Diego components. To interact with the BBS from outside of Diego, the Client should be used instead.

                func NewClient

                func NewClient(url, caFile, certFile, keyFile string, clientSessionCacheSize, maxIdleConnsPerHost int) (InternalClient, error)

                func NewClientWithConfig

                func NewClientWithConfig(cfg ClientConfig) (InternalClient, error)

                func NewSecureSkipVerifyClient

                func NewSecureSkipVerifyClient(url, certFile, keyFile string, clientSessionCacheSize, maxIdleConnsPerHost int) (InternalClient, error)

                Directories

                Path Synopsis
                cmd
                bbs
                fakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                fake_controllers
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                db
                dbfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                sqldb/fakesqldriver/fakesqldriverfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                sqldb/helpers/helpersfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                sqldb/helpers/monitor/monitorfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                encryptionfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                eventfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                fakes
                This file was generated by counterfeiter
                This file was generated by counterfeiter
                guidproviderfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                fake_controllers
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                middleware/fakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                fakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                metricsfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                migrationfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                fakes
                This file was generated by counterfeiter
                This file was generated by counterfeiter
                serviceclientfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.
                taskworkpoolfakes
                Code generated by counterfeiter.
                Code generated by counterfeiter.