Routing Requests

#340130

Description

A Routing Request represents a request to route a new workload demand entity, typically a VM, to an appropriate hosting venue.

The Routing Request takes into account scalar and non-scalar workload requirements when determining qualified hosting venues, so that memory, CPU, IO and storage are not over committed across all future timeframes.

Hosting Venues

This API supports routing to a mix of full control hosting venues (i.e. infrastructure groups), non-control hosting venues and guest-level hosting venues.

With respect to this API, the difference between these hosting venues is as follows:

Assessing Hosting Venues—For non-control and guest-level hosting venues, only Fit-for-Purpose checks are performed. The hosting venues that pass the Fit-for-Purpose requirements result in a hosting_score of 100% (the mode is assumed capacity_sensitive).
Placement and Option for Placement—The ?recheckHost=true is ignored for non-control and guest-level hosting venues.
Auto-Reconciliation—Only applies to full control hosting venues.

Assessing Hosting Venues and Hosts

When assessing multiple hosting venues, the available capacity of each hosting venue is assessed according to cost, capacity and Fit-for-Purpose, using the same logic as described in Routing Requests–Available Capacity Query. The best placement of the entity is determined by the hosting venue with the highest score (i.e. hosting_score). The same three modes (i.e. ?mode=capacity_sensitive, ?mode=cost_sensitive and ?mode=cost_and_capacity) can be specified with the Routing Request, with default defined by configuration setting API Default Routing Strategy.

For Routing Requests routed for today, once the best hosting venue is determined, the best host and the best datastores associated with the host are selected (determined by the most available capacity in number of slots and metrics).

Assessing Datastore

If the datastore preference is specified in the Workload disk definition, Densify will try to respect the preferred placement according to the best candidate environment and hosting venue selected. If the preferred datastore is not available in the selected hosting venue, does not satisfy the tier condition, or does not have enough capacity, then the next suitable datastore available in the venue will be used. Regardless if the preferred datastore is used during routing, the Datastore Preference value is still preserved in the Workload disk definition after placement.

Forced Placement

A particular hosting venue may not be a candidate for routing when it does not have the capacity, does not pass the Fit-for-Purpose validation or does not have the required storage tier requirements. With the ?force=true option, a Routing Request can be forced to route to that hosting venue. Densify will then select the least full host and datastores (taking datastores with lower storage tier priorities if necessary), even if policy limits are violated or capacity is in the negative.

The routing of disks with ?force=true is performed in the following order:

first routes to the best Fit-for-Purpose and capacity choice with available capacity
then routes to the best capacity choice with available capacity, with a lower storage tier priority
then routes to requested storage tier, regardless of available capacity
then routes to the best capacity choice, regardless of requested storage tier

Placement and Option for Placement

When a Routing Request is PLACED, its Workloads are PLACED (see Placement and Option for Placement for Workloads and State Diagram—Create Scenario).

Similar to the Workload object, the individual get requests GET /routing-requests/<id> and GET /routing-requests/<id>/workloads can be extended with the following option:

?recheckHost=true—to recheck the recommended host and sensor placement for a Workload in PLACED state. If the recommended host/sensor is currently not healthy (i.e. real-time placement is enabled and the monitored host/sensor shows unhealthy), a new placement is provided.

Record Placement

During a re-route cycle, you may want to record the existing datastore that was used before the Workload is unrouted. You can achieve this by using the DELETE operation with the ?record_placement=true option on the following resources:

DELETE /routing-requests/<id>?record_placement=true—Use this operation to unroute the Workloads associated with the specified Route Request and save the current datastore as the preferred datastore for the re-route cycle.
DELETE /routing-requests/<id>/<workload_id>?record_placement=true—Use this operation to unroute the specified Workload associated with the specified Route Request and save the current datastore as the preferred datastore for the re-route cycle.

The default behavior for the DELETE operation without the ?record_placement option or with the ?record_placement=false option is that the preferred datastore (pref_datastore) attribute remains unchanged.

When you use the DELETE operation with ?record_placement=true option on the resources listed above, the following behavior occurs based on the number of disks in a Workload and the preferred datastore attribute for each disk:

record_placement	Preferred Datastore Condition	Preferred Datastore Attribute Result
true	Preferred datastore attribute is not set for all disks in the Workload.	Current datastore used is saved in the preferred datastore (pref_datastore) attribute for each disk.
true	Preferred datastore attribute is set for some disks and not for other disks in the Workload.	Preferred datastore attribute remains unchanged for each disk.
false	Any condition	Preferred datastore attribute remains unchanged for each disk.

Note: If a preferred datastore is set, then that setting will override the sensor placement strategy (i.e. balanced/fill and spill).

Routing Request and Workloads Treated as One

A Routing Request is treated as a single item. The expected date for placement is taken from the Routing Request and not from the Workloads, even if they differ. The Workloads are still placed according to their expected date.

If any of the Workloads within a request cannot be placed and/or booked (because the capacity could not be reserved or the Fit-for-Purpose failed), then the entire request is rejected.

Sensor Placement Strategy

You have two sensor placement options when routing workloads:

Balancing Strategy—Distributes incoming workloads across all suitable hosting venues with available sensor capacity. Using this option the resource with available sensor capacity that also matches the fit-for-purpose requirements of the incoming workload and has the most available capacity among all matching candidates is selected. Densify attempts to balance workloads across all available hosting venues. This is the default behaviour.
Fill and Spill Strategy—Fills suitable hosting venues with available sensor capacity with incoming workloads until the resource reaches its threshold. When routing, the workloads with matching fit-for-purpose requirements are placed on the resource with the least capacity, first.

You can specify sensor placement strategy when submitting a routing request via the API or you can set the placement strategy globally using a configuration setting. Contact [email protected] for details of configuring the global setting.

Note: If a preferred datastore is set, then that setting will override the sensor placement strategy (i.e. balanced/fill and spill).

The routing request applies the specified sensor placement strategy as follows:

Execute all fit for purpose checks and capacity level checks as usual.
When choosing the best routable device on which to place a booking:

If balance is requested, then sort candidate sensors from most to least available capacity (default implementation).
If fill is requested, then sort candidate sensors from least to most available capacity.

Sensor Lockout

At the end of each control environment refresh, existing data used for routing bookings is purged and recalculated (sensor recalculation). This data includes:

Aggregate infrastructure group-level capacity data, including storage per-tier capacity, cluster_sensor_capacity;
Individual sensor-level capacity;

During the period while this recalculation is performed, routing anomalies can occur. Specifically, while the sensor data is purged and then is temporarily unavailable for a given hosting venue. During routing of incoming workloads, any clusters that are in the state of sensor data recalculation are excluded from consideration as a hosting option.

You can specify sensor lockout behaviour when submitting a routing request via the API or you can set the lockout during recalculation, globally using a configuration setting. Contact [email protected] for details of configuring the global setting.

Auto-Reconciliation

When the actual VM comes online, it is auto-reconciled with the Workload object with the same name as the Workload name. The attributes and Workload Profile are inherited or copied from the Workload to the new VM, if not already specified in the VM. For more details on auto-reconciliation, see section Auto-Reconciliation of Systems of Booking Overview (Help Topic ID 230350).

Postman Collection

Densify provides a Postman collection of sample API requests for working with the supply and demand features of the API. See Postman Collection

Resource

/routing-requests

Supported Operations

Table: Routing Request Supported Operations

Operation	HTTP Method	Input	Output	Description
Get Collection	GET /routing-requests	None	Routing Request Collection of [id, href]	Default Sort By is defined as: ?sort_by=expected_date.
Get Individual	GET /routing-requests/<id>	None	Routing Requests: Resource Elements	Retrieve the Routing Request elements of the specified id. If the Routing Request is in BOOKED status, its Workloads are updated to PLACED if the corresponding expected_date of each Workload is today (expected_date has passed already but corresponding Booking has not EXPIRED).
Get Individual	GET /routing-requests/<id>/workloads	None	Workload Collection of [id, name href]	Retrieve the Workloads of the specified id. This request can also be extended with ?details=true to view all Workload elements. If the Routing Request is in BOOKED status, its Workloads are updated to PLACED if the corresponding expected_date of each Workload is today (or expected_date has passed already but corresponding Booking has not EXPIRED).
Create Individual	POST /routing-requests	Routing Requests: Form Definition	Routing Requests: Resource Elements	To create a Routing Request, you can specify the Workloads in one of two ways: list of Workload ids (and only Workload ids)−with this option, you must create the Workloads using a separate POST and all Workloads must be in UNROUTED state, not included in any other Routing Request specify Workload elements creating the Workloads on-the-fly−with this option, you specify the same elements as you would when creating the Workloads with a separate POST to Workloads Example: Routing a Simple Immediate Placement, Example: Creating a Simple Booking for Mar 20, 2022, Example: Selecting Placement From Multiple Environments
Delete Individual	DELETE /routing-requests/<id>	None	None	When the Routing Request is deleted, the Workloads may or may not be auto-deleted depending on the expected date. See State Diagram—Delete Scenario for details. You can save the current datastore used for each disk in the Workload that is unrouted by using the record_placement=true option. See Record Placement for details.
Delete Workload from Routing Request	DELETE /routing-requests/<id>/<workload_id>	None	None	A Workload can be unlinked from its associated Routing Request, so that it can be re-routed to another location through another Routing Request. The status of such a Workload is updated to UNROUTED. You can save the current datastore used for each disk in the Workload that is unrouted by using the record_placement=true option. See Record Placement for details. If this is the last Workload in the Routing Request, then the Routing Request is also deleted. An error is returned if the specified Workload does not belong to this Routing Request.

Resource Elements

Table: Routing Request Resource Elements

Element	Type	Create/ Mod- (Req)	Sort By	Filter	Description
id, href	strings				See ID, Name and Self Reference (id, name, href).
control_environment	href				This is the link to the associated Control Environment where the workloads are placed. Set if and only if the Routing Request has been routed (i.e. status is BOOKED or PLACED).
expected_date	number	C	S	F	The date that the request is to be routed and the system(s) will arrive, in UTC. The time portion is ignored. If the expected_date is not specified, then the request is for immediate placement (i.e. Today’s timeframe). The expected_date must be the same or later than that specified expected_date of all its Workloads. If not, an error is thrown. The expected_date should be within the supported Timeline Definition of the Control Console.
infrastructure_group	href			F	This is the link to the associated Infrastructure Group object where the workloads are placed. Set if and only if the Routing Request has been routed (i.e. status is BOOKED or PLACED). ?force=true can be appended to the URI to force the routing to the specified hosting venue (see Forced Placement for details). The resulting Routing Request will show a status of PLACED with a status reason of "Force to place". The capacity for the hosting venue will be decremented, but not for the Control Environment.
requester	string	C	S	F	The user who routed this request. If not set for a routing request, is automatically set to the current user. If set to "__Unknown__" (case insensitive), the request is rejected.
status	string			F	The status of the request. This can be one of: "ANALYZING"—initial state when the Routing Request is defined and before it is fully processed "PLACED"—on the day that the Routing Request is to be fulfilled, the status of the Routing Request changes to PLACED and the Workloads are updated to have links to the host where they should be placed "BOOKED"—all Workloads specified in the Routing Request have been routed and space has been reserved, for the date specified by expected_date in the future "REJECTED"—no Workloads in the Routing Request were routed as space could not be reserved or the Fit-for-Purpose validation failed for at least one Workload
status_details	Complex, as specified in the description				Status details returned for a Routing Request in any status except "ANALYZING". This element is returned only if available, for Routing Requests created or updated. igs_in_scope—number of Infrastructure Groups that are in scope igs_ffp—number of Infrastructure Groups in scope that are Fit-for-Purpose igs_ffp_not_accepting_workloads—number of Infrastructure Groups in scope that are Fit-for-Purpose but not accepting workloads (i.e. closed or never been refreshed) igs_ffp_no_capacity—number of Infrastructure Groups that are Fit-for-Purpose and accepting workloads (i.e. open and refreshed) but have no capacity (i.e. "slots"<=0) ig_rejection_details—for the Infrastructure Groups counted in igs_ffp_no_capacity, this returns an array of each Infrastructure Group and the timeframe of the timeline that it has no capacity (referenced by the short_name of the Timeline Tags). Note that the timeframe returned is the first returned by the API, not necessarily the first timeframe chronologically ordered in which there is no capacity. This array is returned only when the Routing Request is REJECTED. Here is an example of what is returned: "status_details": { "igs_in_scope": 5, "igs_ffp": 5, "igs_ffp_not_accepting_workloads": 1, "igs_ffp_no_capacity": 2, "ig_rejection_details": [ { "timeline_without_capacity": "60" "infrastructure_group": { "id": "0cf490b8-bec5-488c-a793-a1cd7fb1be6e", "name": "Cluster 4", "href": "/infrastructure-groups/0cf490b8-bec5-488c-a793-a1cd7fb1be6e" } }, // ... SNIP of 2nd IG rejection details ... ] }
status_reason	string			F	Explanation of the status. This field is populated only when the status is REJECTED (or PLACED for one reason as noted below), and can take on the following values: "Cannot find Qualified Infrastructure Group"−e.g. insufficient scalar and non-scalar workloads to compare against the Infrastructure Groups or an Infrastructure Group is "UNAVAILABLE" "Cannot find Infrastructure Group Fit-for-Purpose"−all Infrastructure Groups are not Fit-for-Purpose "Force to place"−when ?force=true "No data for the expected date selected" e.g. expected_date is too far in the future and there is no timeframe available "Cannot find Qualified Infrastructure Group, Force to place" "Cannot find Qualified Infrastructure Group, No data for the expected date selected" "Force to place, No data for the expected date selected" "Cannot find Qualified Infrastructure Group, Force to place, No data for the expected date selected"
workloads	[id, name, href]	CM			A link to each Workload that is part of this Routing Request placement or available capacity query.

Form Definition

If you want to specify how the workload should be placed, then you can use a routing request form. You then need to provide one or more of the following additional details.

Table: Routing Request Form Definition

Element	Type	Req	Description
scopes	[control_environment, infrastructure_groups[name]] Where infrastructure_groups[name] is optional		Represents the environments and hosting venues where you want the workload router to restrict the search. If not specified, all environments will be candidates for routing. For example, to specify the Boston environment, and either the Prod or Dev hosting venues of the New York environment: "scopes": [ { "control_environment": "Boston" }, { "control_environment": "New York", "infrastructure_groups":["Prod","Dev"] } ]
required_sensor_types	"required_sensor_types": ["datastore","ipaddresspools"]		You can specify sensor lockout behaviour when submitting a routing request to prevent incoming workloads from being placed while the sensor data is purged,recalculated and is temporarily unavailable for a given hosting venue. The parameter value is set as "required_sensor_types": ["datastore","ipaddresspools"]. See Sensor Lockout and Example: Enabling Sensor Lockout.
sensor_placement_strategy	"sensor_placement_strategy": ["datastore-balance","ipaddresspools-fill"]		Select a sensor placement strategy for routed workloads.Only routable sensor types can be specified. Valid placement strategies are balance or fill. Multiple sensor types can be specified as a comma separated list. If an invalid sensor type or placement strategy is specified, the parameter is ignored and the default placement strategy is used. The parameter value is set as <sensor type>-<placement strategy>, i.e. sensor_placement_strategy=datastores-fill,ip_address_pools-balance. See Sensor Placement Strategy and Example: Selecting Sensor Placement Strategy.
workloads	[Workloads: Resource Elements]	P	An array of Workload definitions for each system to be placed. This could either be the list of existing Workload ids or the Workload definition itself. See Workloads for details on defining the Workload. Note: The list of Workload IDs must be specified for the available-capacity-query to evaluate the Fit-for-Purpose. Fit-for-Purpose validation returns all PASS results when Workload definitions are used.

Examples

The following examples show the various types of routing requests.

Example: Routing a Simple Immediate Placement

The following example shows you the most basic method to route a request:

Example: Creating a Simple Booking for Mar 20, 2022

The following example shows you the most basic method to route a booking request on a specific date:

Example: Creating a Simple Booking for Mar 20, 2016

Request:

POST /routing-requests/

{

"expected_date": 1458518806000,

"workloads": [

{

"name": "group-vm-01",

"catalog_spec": "lin-medium-4gb",

"workload_profile": "Medium_Utilization"

{

"name": "group-vm-02",

"catalog_spec": "lin-medium-4gb",

"workload_profile": "Medium_Utilization"

{

"name": "group-vm-03",

"catalog_spec": "lin-medium-4gb",

"workload_profile": "Medium_Utilization"

{

"name": "group-vm-04",

"catalog_spec": "lin-medium-4gb",

"workload_profile": "Medium_Utilization"

}

]

}

Example: Selecting Placement From Multiple Environments

The following example shows you how to select a placement from multiple environments:

Example: Selecting Sensor Placement Strategy

The following example shows you how to define a sensor placement strategy:

Example: Enabling Sensor Lockout

The following example shows you how to enable sensor lockout to avoid placing workloads on hosting venues for which accurate sensor data is temporaily unavailable: