Custom HTTP Provider¶
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 anHTTP 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}®ion={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 giveninstanceId
,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
ordefault
. 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 beSMALL
,MEDIUM
,LARGE
orXLARGE
. 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. |