This reference does not cover the protobuf payload supplied to each endpoint. Instead, it illustrates calls to the API via the Golang bbs.InternalClient interface. Each method on that InternalClient interface takes a lager.Logger as the first argument to log errors generated within the client. This first Logger argument will not be duplicated on the descriptions of the method arguments.

For detailed information on the types referred to below, see the godoc documentation for the BBS models.

ActualLRP APIs

ClaimActualLRP

The cell calls ClaimActualLRP to report to the BBS that it has claimed an ActualLRP instance.

BBS API Endpoint

POST an ClaimActualLRPRequest to /v1/actual_lrps/claim and receive an ActualLRPLifecycleResponse.

Golang Client API

ClaimActualLRP(logger lager.Logger, processGuid string, index int, instanceKey *models.ActualLRPInstanceKey)

Inputs

• processGuid: The GUID of the corresponding DesiredLRP.
• index int: Index of the ActualLRP.
• instanceKey *models.ActualLRPInstanceKey: InstanceKey for the ActualLRP to claim.
  • InstanceGuid string: The GUID of the instance to claim.
  • CellID string: ID of the Cell claiming the ActualLRP.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.ClaimActualLRP(logger, "some-guid", 0, &models.ActualLRPInstanceKey{
	InstanceGuid: "some-instance-guid",
	CellId: "some-cellID",
)
if err != nil {
    log.Printf("failed to claim actual lrp: " + err.Error())
}

StartActualLRP

The cell calls StartActualLRP to report to the BBS that it has started an ActualLRP instance.

BBS API Endpoint

POST an StartActualLRPRequest to /v1/actual_lrps/start.r1 and receive an ActualLRPLifecycleResponse.

Deprecated Endpoints

POST an StartActualLRPRequest to /v1/actual_lrps/start and receive an ActualLRPLifecycleResponse.

Golang Client API

StartActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, netInfo *models.ActualLRPNetInfo, internalRoutes []*models.ActualLRPInternalRoute, metricTags map[string]string) error

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the ActualLRP to start.
  • InstanceGuid string: The GUID of the instance to start.
  • CellID string: ID of the Cell starting the ActualLRP.
• netInfo *models.ActualLRPNetInfo: ActualLRPNetInfo containing updated networking information for the ActualLRP.
• internalRoutes []*models.ActualLRPInternalRoute: ActualLRPInternalRoute containing updated internal routes for the ActualLRP.
• metricTags map[string]string: containing updated metric tags for the ActualLRP.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.StartActualLRP(logger, &models.ActualLRPKey{
	   ProcessGuid: "some-guid",
	   Index: 0,
	   Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
	},
	&models.ActualLRPNetInfo{
	    Address: "1.2.3.4",
	    models.NewPortMapping(10,20),
	    InstanceAddress: "2.2.2.2",
	},
	[]*models.ActualLRPInternalRoute{
	    {Hostname: "some-internal-route.apps.internal"},
	},
	map[string]string{"app_name": "some-app-name"},
)
if err != nil {
    log.Printf("failed to start actual lrp: " + err.Error())
}

CrashActualLRP

The cell calls CrashActualLRP to report to the BBS that an ActualLRP instance it was running has crashed.

BBS API Endpoint

POST an CrashActualLRPRequest to /v1/actual_lrps/crash and receive an ActualLRPLifecycleResponse.

Golang Client API

CrashActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, errorMessage string) error

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the ActualLRP to crash.
  • InstanceGuid string: The GUID of the instance to crash.
  • CellID string: ID of the Cell crashing the ActualLRP.
• errorMessage string: The error message describing the reason for the crash.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.CrashActualLRP(logger, &models.ActualLRPKey{
	   ProcessGuid: "some-guid",
	   Index: 0,
	   Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
	},
	"Crashed Reason",
)
if err != nil {
    log.Printf("failed to crash actual lrp: " + err.Error())
}

FailActualLRP

The auctioneer calls FailActualLRP to report to the BBS that it has failed to place an ActualLRP instance.

BBS API Endpoint

POST an FailActualLRPRequest to /v1/actual_lrps/fail and receive an ActualLRPLifecycleResponse.

Golang Client API

FailActualLRP(logger lager.Logger, key *models.ActualLRPKey, errorMessage string) error

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• errorMessage string: The error message describing the reason for the placement failure.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.FailActualLRP(logger, &models.ActualLRPKey{
	   ProcessGuid: "some-guid",
	   Index: 0,
	   Domain: "some-domain",
	},
	"Failure Reason",
)
if err != nil {
    log.Printf("failed to fail actual lrp: " + err.Error())
}

RemoveActualLRP

The cell calls RemoveActualLRP to remove from the BBS an ActualLRP instance it has claimed but for which it no longer has a container.

BBS API Endpoint

POST an RemoveActualLRPRequest to /v1/actual_lrps/remove and receive an ActualLRPLifecycleResponse.

Golang Client API

RemoveActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey) error

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index (the domain is ignored).
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the ActualLRP to remove. If present, must match the key in the BBS record. If nil, the ActualLRP is removed without requiring a match.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.RemoveActualLRP(logger, &models.ActualLRPKey{ProcessGuid: "some-guid", Index: 0}, &models.ActualLRPInstanceKey{
	InstanceGuid: "some-instance-guid",
	CellId: "some-cellID",
)
)
if err != nil {
    log.Printf("failed to remove an actual lrp: " + err.Error())
}

EvacuateClaimedActualLRP

The cell calls EvacuateClaimedActualLRP to evacuate an ActualLRP it has claimed but not yet started.

BBS API Endpoint

POST an EvacuateClaimedActualLRPRequest to /v1/actual_lrps/evacuate_claimed and receive an EvacuationResponse.

Golang Client API

EvacuateClaimedActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey) (bool, error)

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the claimed ActualLRP to evacuate.

Output

• bool: Flag indicating whether to keep the container. If true, keep the container. If false, destroy it.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
keepContainer, err := client.EvacuateClaimedActualLRP(logger, &models.ActualLRPKey{
	       ProcessGuid: "some-guid",
	       Index: 0,
	       Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
)
if err != nil {
    log.Printf("failed to evacuate claimed actual lrp: " + err.Error())
}

EvacuateCrashedActualLRP

The cell calls EvacuateCrashedActualLRP to report that an ActualLRP has crashed during evacuation.

BBS API Endpoint

POST an EvacuateCrashedActualLRPRequest to /v1/actual_lrps/evacuate_crashed and receive an EvacuationResponse.

Golang Client API

EvacuateCrashedActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, errorMessage string) (bool, error)

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the crashed ActualLRP to evacuate.
• errorMessage string: The error message describing the reason for the crash.

Output

• bool: Flag indicating whether to keep the container. If true, keep the container. If false, destroy it.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
keepContainer, err := client.EvacuateCrashedActualLRP(logger, &models.ActualLRPKey{
	       ProcessGuid: "some-guid",
	       Index: 0,
	       Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
	"some error message",
)
if err != nil {
    log.Printf("failed to evacuate crashed actual lrp: " + err.Error())
}

EvacuateStoppedActualLRP

The cell calls EvacuateStoppedActualLRP to report that an ActualLRP has stopped during evacuation.

BBS API Endpoint

POST an EvacuateStoppedActualLRPRequest to /v1/actual_lrps/evacuate_stopped and receive an EvacuationResponse.

Golang Client API

EvacuateStoppedActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey) (bool, error)

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the stopped ActualLRP to evacuate.

Output

• bool: Flag indicating whether to keep the container. If true, keep the container. If false, destroy it.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
keepContainer, err := client.EvacuateStoppedActualLRP(logger, &models.ActualLRPKey{
	       ProcessGuid: "some-guid",
	       Index: 0,
	       Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
	"some error message",
)
if err != nil {
    log.Printf("failed to evacuate stopped actual lrp: " + err.Error())
}

EvacuateRunningActualLRP

The cell calls EvacuateRunningActualLRP to evacuate an ActualLRP it has started.

BBS API Endpoint

POST an EvacuateRunningActualLRPRequest to /v1/actual_lrps/evacuate_running.r1 and receive an EvacuationResponse.

Deprecated Endpoints

POST an EvacuateRunningActualLRPRequest to /v1/actual_lrps/evacuate_running and receive an EvacuationResponse.

Golang Client API

EvacuateRunningActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey, netInfo *models.ActualLRPNetInfo, internalRoutes []*models.ActualLRPInternalRoute, metricTags map[string]string) (bool, error)

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the running ActualLRP to evacuate.
• netInfo *models.ActualLRPNetInfo: ActualLRPNetInfo containing updated networking information for the ActualLRP.
• internalRoutes []*models.ActualLRPInternalRoute: ActualLRPInternalRoute containing updated internal routes for the ActualLRP.
• metricTags map[string]string: containing updated metric tags for the ActualLRP.

Output

• bool: Flag indicating whether to keep the container. If true, keep the container. If false, destroy it.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
keepContainer, err := client.EvacuateRunningActualLRP(logger, &models.ActualLRPKey{
	       ProcessGuid: "some-guid",
	       Index: 0,
	       Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
	},
	&models.ActualLRPNetInfo{
	    Address: "1.2.3.4",
	    models.NewPortMapping(10,20),
	    InstanceAddress: "2.2.2.2",
	},
	[]*models.ActualLRPInternalRoute{
	    {Hostname: "some-internal-route.apps.internal"},
	},
	map[string]string{"app_name": "some-app-name"},
)
if err != nil {
    log.Printf("failed to evacuate running actual lrp: " + err.Error())
}

RemoveEvacuatingActualLRP

The cell calls EvacuateRunningActualLRP to remove an evacuating ActualLRP for which it no longer has a container.

BBS API Endpoint

POST an RemoveEvacuatingActualLRPRequest to /v1/actual_lrps/remove_evacuating, and receive an RemoveEvacuatingActualLRPResponse.

Golang Client API

RemoveEvacuatingActualLRP(logger lager.Logger, key *models.ActualLRPKey, instanceKey *models.ActualLRPInstanceKey) error

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.
• instanceKey *models.ActualLRPInstanceKey: ActualLRPInstanceKey for the evacuating ActualLRP to remove.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.RemoveEvacuatingActualLRP(logger, &models.ActualLRPKey{
	       ProcessGuid: "some-guid",
	       Index: 0,
	       Domain: "some-domain",
	},
	&models.ActualLRPInstanceKey{
	    InstanceGuid: "some-instance-guid",
	    CellId: "some-cellID",
	"some error message",
)
if err != nil {
    log.Printf("failed to remove evacuating actual lrp: " + err.Error())
}