bbs

README

BBS Server

API to access the database for Diego.

API

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

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

Code Generation

You need the 3.0 version of the protoc compiler. If you're a Homebrew user on Mac OS X, you get that by running:

brew install protobuf --devel

If you already have an older version of protobuf installed, you will have to uninstall it first: brew uninstall protobuf

You also need the gogoproto compiler in you path:

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

We generate code from the .proto (protobuf) files. We also generate a set of fakes from the interfaces we have. To do so, just use go generate.

go generate ./...

Documentation

Index

• Constants
• Variables
• func BBSLockSchemaPath() string
• func CellSchemaPath(cellID string) string
• func CellSchemaRoot() string
• type Client
  • func NewClient(url string) Client
  • func NewSecureClient(url, caFile, certFile, keyFile string, ...) (Client, error)
  • func NewSecureSkipVerifyClient(url, certFile, keyFile string, clientSessionCacheSize, maxIdleConnsPerHost int) (Client, error)
• type ExternalActualLRPClient
• type ExternalClient
• type ExternalDesiredLRPClient
• type ExternalDomainClient
• type ExternalEventClient
• type ExternalTaskClient
• type ServiceClient
  • func NewServiceClient(client consuladapter.Client, clock clock.Clock) ServiceClient

Constants

const (
	ContentTypeHeader    = "Content-Type"
	XCfRouterErrorHeader = "X-Cf-Routererror"
	ProtoContentType     = "application/x-protobuf"
	KeepContainer        = true
	DeleteContainer      = false
)

const (
	// Ping
	PingRoute = "Ping"

	// Domains
	DomainsRoute      = "Domains"
	UpsertDomainRoute = "UpsertDomain"

	// Actual LRPs
	ActualLRPGroupsRoute                     = "ActualLRPGroups"
	ActualLRPGroupsByProcessGuidRoute        = "ActualLRPGroupsByProcessGuid"
	ActualLRPGroupByProcessGuidAndIndexRoute = "ActualLRPGroupsByProcessGuidAndIndex"

	// Actual LRP Lifecycle
	ClaimActualLRPRoute  = "ClaimActualLRP"
	StartActualLRPRoute  = "StartActualLRP"
	CrashActualLRPRoute  = "CrashActualLRP"
	FailActualLRPRoute   = "FailActualLRP"
	RemoveActualLRPRoute = "RemoveActualLRP"
	RetireActualLRPRoute = "RetireActualLRP"

	// Evacuation
	RemoveEvacuatingActualLRPRoute = "RemoveEvacuatingActualLRP"
	EvacuateClaimedActualLRPRoute  = "EvacuateClaimedActualLRP"
	EvacuateCrashedActualLRPRoute  = "EvacuateCrashedActualLRP"
	EvacuateStoppedActualLRPRoute  = "EvacuateStoppedActualLRP"
	EvacuateRunningActualLRPRoute  = "EvacuateRunningActualLRP"

	// Desired LRPs
	DesiredLRPsRoute               = "DesiredLRPs_r1"
	DesiredLRPSchedulingInfosRoute = "DesiredLRPSchedulingInfos"
	DesiredLRPByProcessGuidRoute   = "DesiredLRPByProcessGuid_r1"

	DesiredLRPsRoute_r0             = "DesiredLRPs"             // Deprecated
	DesiredLRPByProcessGuidRoute_r0 = "DesiredLRPByProcessGuid" // Deprecated

	// Desire LRP Lifecycle
	DesireDesiredLRPRoute = "DesireDesiredLRP"
	UpdateDesiredLRPRoute = "UpdateDesireLRP"
	RemoveDesiredLRPRoute = "RemoveDesiredLRP"

	// LRP Convergence
	ConvergeLRPsRoute = "ConvergeLRPs"

	// Tasks
	TasksRoute         = "Tasks_r1"
	TaskByGuidRoute    = "TaskByGuid_r1"
	DesireTaskRoute    = "DesireTask"
	StartTaskRoute     = "StartTask"
	CancelTaskRoute    = "CancelTask"
	FailTaskRoute      = "FailTask"
	CompleteTaskRoute  = "CompleteTask"
	ResolvingTaskRoute = "ResolvingTask"
	DeleteTaskRoute    = "DeleteTask"
	ConvergeTasksRoute = "ConvergeTasks"

	TasksRoute_r0      = "Tasks"      // Deprecated
	TaskByGuidRoute_r0 = "TaskByGuid" // Deprecated

	// Event Streaming
	EventStreamRoute_r0        = "EventStream_r0" // Deprecated
	DesiredLRPEventStreamRoute = "DesiredLRPEventStreamRoute"
	ActualLRPEventStreamRoute  = "ActualLRPEventStreamRoute"
	TaskEventStreamRoute       = "TaskEventStreamRoute"

	// Cell Presence
	CellsRoute = "Cells_r1"
)

const (
	CellSchemaKey    = "cell"
	BBSLockSchemaKey = "bbs_lock"
)

Variables

var Routes = rata.Routes{

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

	{Path: "/v1/domains/list", Method: "POST", Name: DomainsRoute},
	{Path: "/v1/domains/upsert", Method: "POST", Name: UpsertDomainRoute},

	{Path: "/v1/actual_lrp_groups/list", Method: "POST", Name: ActualLRPGroupsRoute},
	{Path: "/v1/actual_lrp_groups/list_by_process_guid", Method: "POST", Name: ActualLRPGroupsByProcessGuidRoute},
	{Path: "/v1/actual_lrp_groups/get_by_process_guid_and_index", Method: "POST", Name: ActualLRPGroupByProcessGuidAndIndexRoute},

	{Path: "/v1/actual_lrps/claim", Method: "POST", Name: ClaimActualLRPRoute},
	{Path: "/v1/actual_lrps/start", Method: "POST", Name: StartActualLRPRoute},
	{Path: "/v1/actual_lrps/crash", Method: "POST", Name: CrashActualLRPRoute},
	{Path: "/v1/actual_lrps/fail", Method: "POST", Name: FailActualLRPRoute},
	{Path: "/v1/actual_lrps/remove", Method: "POST", Name: RemoveActualLRPRoute},
	{Path: "/v1/actual_lrps/retire", Method: "POST", Name: RetireActualLRPRoute},

	{Path: "/v1/actual_lrps/remove_evacuating", Method: "POST", Name: RemoveEvacuatingActualLRPRoute},
	{Path: "/v1/actual_lrps/evacuate_claimed", Method: "POST", Name: EvacuateClaimedActualLRPRoute},
	{Path: "/v1/actual_lrps/evacuate_crashed", Method: "POST", Name: EvacuateCrashedActualLRPRoute},
	{Path: "/v1/actual_lrps/evacuate_stopped", Method: "POST", Name: EvacuateStoppedActualLRPRoute},
	{Path: "/v1/actual_lrps/evacuate_running", Method: "POST", Name: EvacuateRunningActualLRPRoute},

	{Path: "/v1/desired_lrps/list.r1", Method: "POST", Name: DesiredLRPsRoute},
	{Path: "/v1/desired_lrps/get_by_process_guid.r1", Method: "POST", Name: DesiredLRPByProcessGuidRoute},
	{Path: "/v1/desired_lrp_scheduling_infos/list", Method: "POST", Name: DesiredLRPSchedulingInfosRoute},

	{Path: "/v1/desired_lrps/list", Method: "POST", Name: DesiredLRPsRoute_r0},
	{Path: "/v1/desired_lrps/get_by_process_guid", Method: "POST", Name: DesiredLRPByProcessGuidRoute_r0},

	{Path: "/v1/desired_lrp/desire", Method: "POST", Name: DesireDesiredLRPRoute},
	{Path: "/v1/desired_lrp/update", Method: "POST", Name: UpdateDesiredLRPRoute},
	{Path: "/v1/desired_lrp/remove", Method: "POST", Name: RemoveDesiredLRPRoute},

	{Path: "/v1/lrps/converge", Method: "POST", Name: ConvergeLRPsRoute},

	{Path: "/v1/tasks/list.r1", Method: "POST", Name: TasksRoute},
	{Path: "/v1/tasks/get_by_task_guid.r1", Method: "POST", Name: TaskByGuidRoute},

	{Path: "/v1/tasks/list", Method: "POST", Name: TasksRoute_r0},
	{Path: "/v1/tasks/get_by_task_guid", Method: "GET", Name: TaskByGuidRoute_r0},

	{Path: "/v1/tasks/desire", Method: "POST", Name: DesireTaskRoute},
	{Path: "/v1/tasks/start", Method: "POST", Name: StartTaskRoute},
	{Path: "/v1/tasks/cancel", Method: "POST", Name: CancelTaskRoute},
	{Path: "/v1/tasks/fail", Method: "POST", Name: FailTaskRoute},
	{Path: "/v1/tasks/complete", Method: "POST", Name: CompleteTaskRoute},
	{Path: "/v1/tasks/resolving", Method: "POST", Name: ResolvingTaskRoute},
	{Path: "/v1/tasks/delete", Method: "POST", Name: DeleteTaskRoute},

	{Path: "/v1/tasks/converge", Method: "POST", Name: ConvergeTasksRoute},

	{Path: "/v1/events", Method: "GET", Name: EventStreamRoute_r0},
	{Path: "/v1/desired_lrp_events", Method: "GET", Name: DesiredLRPEventStreamRoute},
	{Path: "/v1/actual_lrp_events", Method: "GET", Name: ActualLRPEventStreamRoute},
	{Path: "/v1/task_events", Method: "GET", Name: TaskEventStreamRoute},

	{Path: "/v1/cells/list.r1", Method: "GET", Name: CellsRoute},
}

Functions

func BBSLockSchemaPath

func BBSLockSchemaPath() string

func CellSchemaPath

func CellSchemaPath(cellID string) string

func CellSchemaRoot

func CellSchemaRoot() string

Types

type Client

type Client interface {
	ExternalClient

	ClaimActualLRP(processGuid string, index int, instanceKey *models.ActualLRPInstanceKey) error
	StartActualLRP(key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, netInfo *models.ActualLRPNetInfo) error
	CrashActualLRP(key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, errorMessage string) error
	FailActualLRP(key *models.ActualLRPKey, errorMessage string) error
	RemoveActualLRP(processGuid string, index int) error

	EvacuateClaimedActualLRP(*models.ActualLRPKey, *models.ActualLRPInstanceKey) (bool, error)
	EvacuateRunningActualLRP(*models.ActualLRPKey, *models.ActualLRPInstanceKey, *models.ActualLRPNetInfo, uint64) (bool, error)
	EvacuateStoppedActualLRP(*models.ActualLRPKey, *models.ActualLRPInstanceKey) (bool, error)
	EvacuateCrashedActualLRP(*models.ActualLRPKey, *models.ActualLRPInstanceKey, string) (bool, error)
	RemoveEvacuatingActualLRP(*models.ActualLRPKey, *models.ActualLRPInstanceKey) error

	ConvergeLRPs() error

	ConvergeTasks(kickTaskDuration, expirePendingTaskDuration, expireCompletedTaskDuration time.Duration) error
	StartTask(taskGuid string, cellID string) (bool, error)
	FailTask(taskGuid, failureReason string) error
	CompleteTask(taskGuid, cellId string, failed bool, failureReason, result string) error
	ResolvingTask(taskGuid string) error
	DeleteTask(taskGuid string) error

	SubscribeToEvents() (events.EventSource, error)
}

The Client 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 ExternalClient should be used instead.

func NewClient

func NewClient(url string) Client

func NewSecureClient

func NewSecureClient(url, caFile, certFile, keyFile string, clientSessionCacheSize, maxIdleConnsPerHost int) (Client, error)

func NewSecureSkipVerifyClient

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

type ExternalActualLRPClient

type ExternalActualLRPClient interface {
	// Returns all ActualLRPGroups matching the given ActualLRPFilter
	ActualLRPGroups(models.ActualLRPFilter) ([]*models.ActualLRPGroup, error)

	// Returns all ActualLRPGroups that have the given process guid
	ActualLRPGroupsByProcessGuid(processGuid string) ([]*models.ActualLRPGroup, error)

	// Returns the ActualLRPGroup with the given process guid and instance index
	ActualLRPGroupByProcessGuidAndIndex(processGuid string, index int) (*models.ActualLRPGroup, error)

	// Shuts down the ActualLRP matching the given ActualLRPKey, but does not modify the desired state
	RetireActualLRP(key *models.ActualLRPKey) error
}

The ExternalActualLRPClient is used to access and retire Actual LRPs

type ExternalClient

type ExternalClient interface {
	ExternalTaskClient
	ExternalDomainClient
	ExternalActualLRPClient
	ExternalDesiredLRPClient
	ExternalEventClient

	// Returns true if the BBS server is reachable
	Ping() bool

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

The External Client 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 ExternalDesiredLRPClient

type ExternalDesiredLRPClient interface {
	// Lists all DesiredLRPs that match the given DesiredLRPFilter
	DesiredLRPs(models.DesiredLRPFilter) ([]*models.DesiredLRP, error)

	// Returns the DesiredLRP with the given process guid
	DesiredLRPByProcessGuid(processGuid string) (*models.DesiredLRP, error)

	// Returns all DesiredLRPSchedulingInfos that match the given DesiredLRPFilter
	DesiredLRPSchedulingInfos(models.DesiredLRPFilter) ([]*models.DesiredLRPSchedulingInfo, error)

	// Creates the given DesiredLRP and its corresponding ActualLRPs
	DesireLRP(*models.DesiredLRP) error

	// Updates the DesiredLRP matching the given process guid
	UpdateDesiredLRP(processGuid string, update *models.DesiredLRPUpdate) error

	// Removes the DesiredLRP matching the given process guid
	RemoveDesiredLRP(processGuid string) error
}

The ExternalDesiredLRPClient is used to access and manipulate Disired LRPs.

type ExternalDomainClient

type ExternalDomainClient interface {
	// Lists the active domains
	Domains() ([]string, error)

	// Creates a domain or bumps the ttl on an existing domain
	UpsertDomain(domain string, ttl time.Duration) error
}

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

type ExternalEventClient

type ExternalEventClient interface {
	// Returns an EventSource for watching changes to DesiredLRPs
	SubscribeToDesiredLRPEvents() (events.EventSource, error)

	// Returns an EventSource for watching changes to ActualLRPs
	SubscribeToActualLRPEvents() (events.EventSource, error)

	// Returns an EventSource for watching changes to Tasks
	SubscribeToTaskEvents() (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(guid, domain string, def *models.TaskDefinition) error

	// Lists all Tasks
	Tasks() ([]*models.Task, error)

	// Lists all Tasks of the given domain
	TasksByDomain(domain string) ([]*models.Task, error)

	// Lists all Tasks on the given cell
	TasksByCellID(cellId string) ([]*models.Task, error)

	// Returns the Task with the given guid
	TaskByGuid(guid string) (*models.Task, error)

	// Cancels the Task with the given task guid
	CancelTask(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://github.com/cloudfoundry-incubator/bbs/tree/master/doc/tasks.md

type ServiceClient

type ServiceClient interface {
	CellById(logger lager.Logger, cellId string) (*models.CellPresence, error)
	Cells(logger lager.Logger) (models.CellSet, error)
	CellEvents(logger lager.Logger) <-chan models.CellEvent
	NewCellPresenceRunner(logger lager.Logger, cellPresence *models.CellPresence, retryInterval, lockTTL time.Duration) ifrit.Runner
	NewBBSLockRunner(logger lager.Logger, bbsPresence *models.BBSPresence, retryInterval, lockTTL time.Duration) (ifrit.Runner, error)
	CurrentBBS(logger lager.Logger) (*models.BBSPresence, error)
	CurrentBBSURL(logger lager.Logger) (string, error)
}

func NewServiceClient

func NewServiceClient(client consuladapter.Client, clock clock.Clock) ServiceClient