Custom HTTP Provider¶

Rest API

The remote provider is possibly the most versatile solution to automate launching OctoPerf agents / hosts on your own. The principle is simple: OctoPerf sends requests to a remote server (of your own), responsible of starting / stopping the hosts used for load generation.

Prerequisites¶

The remote provider requires:

A remote web server which is accessible from OctoPerf's backend perspective,
The remote web server must implement the Rest API defined subsequently.

Rest APIs¶

The following Rest APIs must be implemented by your web server. This web server will be contacted by OctoPerf backend when hosts running OctoPerf Agents must be started / rebooted / stopped

Response Format¶

All HTTP responses are expected to be of application/json; charset=utf-8 Content-type.

Response Types¶

HTTP Responses are expected to be either:

ValueWrapper<String>: refers to a json response with the following format:

{
  "value": "my-value"
}

The json value field contains the expected returned value.

Void: in that case, the API is simply expected to return an HTTP 200 OK response, no response body is required.

Let's explore the APIs that must be implemented

Variables¶

In the following Rest API documentation, variables are annotated as {myVariable}. The following variables are predefined:

{baseUrl} designates the URL of the remote API. Example: http://api.mycompany.com/octoperf.

Variables show which part of the API contains dynamic data (contextual to the call).

Instances API¶

The instances API must be implemented with the following endpoints:

Endpoint	Description	Expected Response
GET `{baseUrl}/instances/{instanceId}/state?region={region}&zone={zone}`	Return given instance state. Expected states: `running` when the instance is up and running.	`HTTP 200 OK` with body: `{ "value": "running"}`
POST `{baseUrl}/instances`, with `form urlencoded` body: `userData={userData}&region={region}&type={type}`	Create the host with given user-data (script to run on instance startup). Returns the `instanceId` as response.	`HTTP 200 OK` with body: `{ "value": "instanceId"}`
PUT `{baseUrl}/instances/{instanceId}`	Restarts the instance with id `instanceId`.	`HTTP 200 OK`
DELETE `{baseUrl}/instances?instanceId={instanceId}`	Terminates and deletes the instance with id `instanceId`.	`HTTP 200 OK`

The parameters below are explained:

instanceId: unique identifier of a given instance. An instance is a host running the OctoPerf Agent container. Example: i-d23efca0d. The identifier must be unique. The remote server must be capable of looking up an instance with the given instanceId,
region: name of the region. Example: eu-west-1, paris. Regions are configured within the provider through OctoPerf's Web UI. The region name is an hint to know where the instance is supposed to be running,
zone: Zone where the instance is running. Example: a, b or default. Zones are configured within the provider through OctoPerf's Web UI. The region name is an hint to know where the instance is supposed to be running,
type: Type of instance to run. Can be SMALL, MEDIUM, LARGE or XLARGE. The type of instance is configured within the provider through OctoPerf's Web UI. It gives an insight on the type of instance your server is supposed to launch.

Static IPs API¶

Static IPs (which can also be referred as Elastic IPs or Dedicated IPs) are IPs being allocated ahead of time. Those IPs can then be linked to a running instance automatically. When the instance is running, any static IP available within the same region is associated to the running instance.

Endpoint	Description	Expected Response
POST `{baseUrl}/static-ips/allocate` with body `region={region}&zone={zone}`	Allocates a new static IP in the given region.	`HTTP 200 OK` with body: `{ "value": "ipId"}`
PUT `{baseUrl}static-ips/associate` with body `region={region}&zone={zone}&instanceId={instanceId}&id={ipId}`	Associates the static IP with id `ipId` to the instance with id `instanceId`	`HTTP 200 OK` with body: `{ "value": "associationId"}`, where `associationId` is the id of the link between the static IP and the instance. Empty if none.
PUT `{baseUrl}/static-ips/dissociate` with body `region={region}&zone={zone}&instanceId={instanceId}&id={ipId}&associationId={associationId}`	Dissociates the static IP with id `ipId` from instance `instanceId`	`HTTP 200 OK`, no body.
DELETE `{baseUrl}/static-ips/release?region={region}&zone={zone}&id={ipId}`	Releases the static IP.	`HTTP 200 OK`, no body.