README
¶
BBS Server 
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
- Download a zip archive of the latest protobuf release from here.
- Unzip the archive in
/usr/local
. 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:
- protoc
> v3.5.0
- ruby protobuf gem
> 3.6.12
Run the following commands from the models
directory to generate .pb.rb
files for the BBS models:
gem install protobuf
cp $(which protoc-gen-ruby){,2}
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
- First setup your GOPATH and install the necessary dependencies for running tests.
- Setup a MySQL server or a postgres server. Please follow these instructions.
- Run the tests from the root directory of the bbs repo:
SQL_FLAVOR=mysql ginkgo -r -p -race
Documentation
¶
Index ¶
Constants ¶
const ( ContentTypeHeader = "Content-Type" XCfRouterErrorHeader = "X-Cf-Routererror" ProtoContentType = "application/x-protobuf" KeepContainer = true DeleteContainer = false DefaultRetryCount = 3 )
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 ¶
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 ¶
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 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:
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
|
|
fakes
Code generated by counterfeiter.
|
Code generated by counterfeiter. |
fake_controllers
Code generated by counterfeiter.
|
Code generated by counterfeiter. |
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. |