033-api-lrps.md

title	expires_at	tags
LRP API Reference	never	diego-release bbs

Long Running Processes API Reference

This reference does not cover the protobuf payload supplied to each endpoint. Instead, it illustrates calls to the API via the Golang bbs.Client interface. Each method on that Client 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

ActualLRPs

Returns all ActualLRPs matching the given ActualLRPFilter.

BBS API Endpoint

POST an ActualLRPsRequest to /v1/actual_lrps/list and receive an ActualLRPsResponse.

Golang Client API

ActualLRPs(lager.Logger, models.ActualLRPFilter) ([]*models.ActualLRP, error)

Inputs

• models.ActualLRPFilter:
  • Domain string: If non-empty, filter to only ActualLRPs in this domain.
  • CellId string: If non-empty, filter to only ActualLRPs with this cell ID.
  • ProcessGuid string: If non-empty, filter to only ActualLRPs with this process GUID.
  • Index *int32: If non-nil, filter to only ActualLRPs with this instance index.

Output

• []*models.ActualLRP: Slice of *models.ActualLRP.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
actualLRPs, err := client.ActualLRPs(logger, &models.ActualLRPFilter{
    Domain:      "some-domain",
    CellId:      "some-cell",
    ProcessGuid: "some-process-guid",
    Index:       &someIndex,
    })
if err != nil {
    log.Printf("failed to retrieve actual lrps: " + err.Error())
}

ActualLRPGroups

Deprecated in favor of ActualLRPs.

Returns all ActualLRPGroups matching the given ActualLRPFilter.

BBS API Endpoint

POST an ActualLRPGroupsRequest to /v1/actual_lrp_groups/list and receive an ActualLRPGroupsResponse.

Golang Client API

ActualLRPGroups(lager.Logger, models.ActualLRPFilter) ([]*models.ActualLRPGroup, error)

Inputs

• models.ActualLRPFilter:
  • Domain string: If non-empty, filter to only ActualLRPGroups in this domain.
  • CellId string: If non-empty, filter to only ActualLRPs with this cell ID.

Output

• []*models.ActualLRPGroup: Slice of ActualLRPGroups. Either the Instance or the Evacuating *models.ActualLRP may be present depending on the state of the LRP instances.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
actualLRPGroups, err := client.ActualLRPGroups(logger, &models.ActualLRPFilter{
    Domain: "some-domain",
    CellId: "some-cell",
    })
if err != nil {
    log.Printf("failed to retrieve actual lrps: " + err.Error())
}

ActualLRPsByProcessGuid

Deprecated in favor of ActualLRPs with an ActualLRPFilter.

Returns all ActualLRPGroups for the given process guid.

BBS API Endpoint

POST an ActualLRPGroupsByProcessGuidRequest to /v1/actual_lrp_groups/list_by_process_guid and receive an ActualLRPGroupsResponse.

Golang Client API

ActualLRPGroupsByProcessGuid(logger lager.Logger, processGuid string) ([]*models.ActualLRPGroup, error)

Inputs

• processGuid string: The process guid of the LRP.

Output

• []*models.ActualLRPGroup: Slice of ActualLRPGroups. Either the Instance or the Evacuating *models.ActualLRP may be present depending on the state of the LRP instances.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
actualLRPGroups, err := client.ActualLRPGroupsByProcessGuid(logger, "my-guid")
if err != nil {
    log.Printf("failed to retrieve actual lrps: " + err.Error())
}

ActualLRPGroupByProcessGuidAndIndex

Deprecated in favor of ActualLRPs with an ActualLRPFilter.

Returns the ActualLRPGroup with the given process guid and instance index.

BBS API Endpoint

POST an ActualLRPGroupByProcessGuidAndIndexRequest to /v1/actual_lrp_groups/get_by_process_guid_and_index and receive an ActualLRPGroupResponse.

Golang Client API

ActualLRPGroupByProcessGuidAndIndex(logger lager.Logger, processGuid string, index int) (*models.ActualLRPGroup, error)

Inputs

• processGuid string: The process guid to retrieve.
• index int: The instance index to retrieve.

Output

• *models.ActualLRPGroup: ActualLRPGroup for this LRP at this index. Either the Instance or the Evacuating *models.ActualLRP may be present depending on the state of the LRP instances.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
actualLRPGroup, err := client.ActualLRPGroupByProcessGuidAndIndex(logger, "my-guid", 0)
if err != nil {
    log.Printf("failed to retrieve actual lrps: " + err.Error())
}

RetireActualLRP

Stops the ActualLRP matching the given ActualLRPKey, but does not modify the desired state.

BBS API Endpoint

POST a RetireActualLRPRequest to /v1/actual_lrps/retire and receive an ActualLRPLifecycleResponse.

Golang Client API

RetireActualLRP(logger lager.Logger, key *models.ActualLRPKey) error

Inputs

• key *models.ActualLRPKey: ActualLRPKey for the instance. Includes the LRP process guid, index, and LRP domain.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.RetireActualLRP(logger, &models.ActualLRPKey{
    ProcessGuid: "some-process-guid",
    Index: 0,
    Domain: "cf-apps",
})
if err != nil {
    log.Printf("failed to retire actual lrps: " + err.Error())
}

DesiredLRP APIs

DesiredLRPs

Lists all DesiredLRPs that match the given DesiredLRPFilter.

BBS API Endpoint

POST a DesiredLRPsRequest to /v1/desired_lrps/list.r3 and receive a DesiredLRPsResponse with V3 DesiredLRPs.

Deprecated Endpoints

• POST a DesiredLRPsRequest to /v1/desired_lrps/list.r2 and receive a DesiredLRPsResponse with V2 DesiredLRPs.
• POST a DesiredLRPsRequest to /v1/desired_lrps/list.r1 and receive a DesiredLRPsResponse with V1 DesiredLRPs.
• POST a DesiredLRPsRequest to /v1/desired_lrps/list and receive a DesiredLRPsResponse with V0 DesiredLRPs.

Golang Client API

DesiredLRPs(logger lager.Logger, filter models.DesiredLRPFilter) ([]*models.DesiredLRP, error)

Inputs

• filter models.DesiredLRPFilter: DesiredLRPFilter to restrict the DesiredLRPs returned.
  • Domain string: If non-empty, filter to only DesiredLRPs in this domain.
  • ProcessGuids []string: If non-empty, filter to only DesiredLRPs with ProcessGuid in the given slice.

Output

• []*models.DesiredLRP: List of DesiredLRPs.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
desiredLRPS, err := client.DesiredLRPs(logger, &models.DesiredLRPFilter{
    Domain: "cf-apps",
})
if err != nil {
    log.Printf("failed to retrieve desired lrps: " + err.Error())
}

DesiredLRPByProcessGuid

Returns the DesiredLRP with the given process guid.

BBS API Endpoint

POST a DesiredLRPByProcessGuidRequest to /v1/desired_lrps/get_by_process_guid.r3 and receive a DesiredLRPResponse with a V3 DesiredLRP.

Deprecated Endpoints

• POST a DesiredLRPByProcessGuidRequest to /v1/desired_lrps/get_by_process_guid.r2 and receive a DesiredLRPResponse with a V2 DesiredLRP.
• POST a DesiredLRPByProcessGuidRequest to /v1/desired_lrps/get_by_process_guid.r1 and receive a DesiredLRPResponse with a V1 DesiredLRP.
• POST a DesiredLRPByProcessGuidRequest to /v1/desired_lrps/get_by_process_guid and receive an DesiredLRPResponse with a V0 DesiredLRP.

Golang Client API

DesiredLRPByProcessGuid(logger lager.Logger, processGuid string) (*models.DesiredLRP, error)

Inputs

• processGuid string: The GUID for the DesiredLRP.

Output

• *models.DesiredLRP: The requested DesiredLRP.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
desiredLRP, err := client.DesiredLRPByProcessGuid(logger, "some-processs-guid")
if err != nil {
    log.Printf("failed to retrieve desired lrp: " + err.Error())
}

DesiredLRPSchedulingInfos

Returns all DesiredLRPSchedulingInfos that match the given DesiredLRPFilter.

BBS API Endpoint

POST a DesiredLRPsRequest to /v1/desired_lrp_scheduling_infos/list and receive a DesiredLRPSchedulingInfosResponse.

Golang Client API

DesiredLRPSchedulingInfos(logger lager.Logger, filter models.DesiredLRPFilter) ([]*models.DesiredLRPSchedulingInfo, error)

Inputs

• filter models.DesiredLRPFilter: DesiredLRPFilter to restrict the DesiredLRPs returned.
  • Domain string: If non-empty, filter to only DesiredLRPs in this domain.
  • ProcessGuids []string: If non-empty, filter to only DesiredLRPs with ProcessGuid in the given slice.

Output

• []*models.DesiredLRPSchedulingInfo: List of DesiredLRPSchedulingInfo records.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
info, err := client.DesiredLRPSchedulingInfos(logger, &models.DesiredLRPFilter{
    Domain: "cf-apps",
})
if err != nil {
    log.Printf("failed to retrieve desired lrp scheduling info: " + err.Error())
}

DesiredLRPSchedulingInfoByProcessGuid

Returns the DesiredLRPSchedulingInfo with the given process guid.

BBS API Endpoint

POST a DesiredLRPByProcessGuidRequest to /v1/desired_lrp_scheduling_infos/get_by_process_guid and receive a DesiredLRPSchedulingInfoByProcessGuidResponse with a DesiredLRPSchedulingInfo.

Golang Client API

DesiredLRPSchedulingInfoByProcessGuid(ctx context.Context, logger lager.Logger, processGuid string) (*models.DesiredLRPSchedulingInfo, error)

Inputs

• processGuid string: The GUID for the DesiredLRPSchedulingInfo.

Output

• *models.DesiredLRPSchedulingInfo: The requested DesiredLRPSchedulingInfo.
• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
schedInfo, err := client.DesiredLRPBySchedulingInfoProcessGuid(logger, "some-processs-guid")
if err != nil {
    log.Printf("failed to retrieve desired lrp scheduling info: " + err.Error())
}

DesiredLRPRoutingInfos

Returns all DesiredLRPs with only the routing info, that matches the given DesiredLRPFilter.

BBS API Endpoint

POST a DesiredLRPsRequest to /v1/desired_lrp_routing_infos/list and receive a DesiredLRPsResponse.

Golang Client API

DesiredLRPRoutingInfos(ctx context.Context, logger lager.Logger, filter models.DesiredLRPFilter) ([]*models.DesiredLRP, error)

Inputs

• filter models.DesiredLRPFilter: DesiredLRPFilter to restrict the DesiredLRPs returned.
  • Domain string: If non-empty, filter to only DesiredLRPs in this domain.
  • ProcessGuids []string: If non-empty, filter to only DesiredLRPs with ProcessGuid in the given slice.

Output

• []*models.DesiredLRP: List of DesiredLRPS records.
• Returned fields:

".process_guid",
".domain",
".log_guid",
".instances",
".routes",
".modification_tag_epoch",
".modification_tag_index",
".run_info",

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
routingInfos, err := client.DesiredLRPRoutingInfos(logger, &models.DesiredLRPFilter{
    Domain: "cf-apps",
})
if err != nil {
    log.Printf("failed to retrieve desired lrp routing info: " + err.Error())
}

DesireLRP

Create a DesiredLRP and its corresponding associated ActualLRPs.

BBS API Endpoint

POST a DesireLRPRequest to /v1/desired_lrp/desire.r1 and receive a DesiredLRPLifecycleResponse.

Deprecated Endpoints

• POST a DesireLRPRequest with a V0 or V1 DesiredLRP to /v1/desired_lrp/desire and receive a DesiredLRPLifecycleResponse.

Golang Client API

DesireLRP(logger lager.Logger, desiredLRP *models.DesiredLRP) error

Inputs

• desiredLRP *models.DesiredLRP: DesiredLRP to create.

Output

• error: Non-nil if an error occurred.

Example

See the LRP Examples page.

UpdateDesiredLRP

Updates the DesiredLRP with the given process GUID.

BBS API Endpoint

POST a UpdateDesiredLRPRequest to /v1/desired_lrp/update and receive a DesiredLRPLifecycleResponse.

Golang Client API

UpdateDesiredLRP(logger lager.Logger, processGuid string, update *models.DesiredLRPUpdate) error

Inputs

• processGuid string: The GUID for the DesiredLRP to update.
• update *models.DesiredLRPUpdate: DesiredLRPUpdate struct containing fields to update, if any.
  • Instances *int32: Optional. The number of instances.
  • MetricTags map[string]*MetricTagValue: Optional. Map of metric tags.
  • Routes *Routes: Optional. Map of routing information.
  • Annotation *string: Optional. The annotation string on the DesiredLRP.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
instances := 4
annotation := "My annotation"
err := client.UpdateDesiredLRP(logger, "some-process-guid", &models.DesiredLRPUpdate{
    Instances: &instances,
    MetricTags: map[string]*models.MetricTagValue{"source_id": {Static: "some-guid"}},
    Routes: &models.Routes{},
    Annotation: &annotation,
})
if err != nil {
    log.Printf("failed to update desired lrp: " + err.Error())
}

RemoveDesiredLRP

Removes the DesiredLRP with the given process GUID.

BBS API Endpoint

POST a RemoveDesiredLRPRequest to /v1/desired_lrp/remove and receive a DesiredLRPLifecycleResponse.

Golang Client API

RemoveDesiredLRP(logger lager.Logger, processGuid string) error

Inputs

• processGuid string: The GUID for the DesiredLRP to remove.

Output

• error: Non-nil if an error occurred.

Example

client := bbs.NewClient(url)
err := client.RemoveDesiredLRP(logger, "some-process-guid")
if err != nil {
    log.Printf("failed to remove desired lrp: " + err.Error())
}