elastisys:scale cloud adapter REST API documentation (version 2.0)¶

Get machine pool¶

• Method: GET /pool

• Description: Retrieves the current machine pool members.

  Note that the returned machines may be in any machine state (REQUESTED, RUNNING, TERMINATED, etc). The machines that are considered part of the active pool are machines in machine states REQUESTED, PENDING or RUNNING and that are not in service state OUT_OF_SERVICE. The service state should be reported as UNKNOWN for machine instances that have not had any service state reported (see Set service state).

• Input: None

• Output:

  • On success: HTTP response code 200 with a Machine pool message
  • On error: HTTP response code 500 with an Error response message

Get pool size¶

• Method: GET /pool/size

• Description: Returns the current size of the machine pool – both in terms of the desired size and the actual size (as these may differ at any time).

• Input: None

• Output:

  • On success: HTTP response code 200 with a Pool size message
  • On error: HTTP response code 500 with an Error response message

Set desired size¶

• Method: POST /pool/size

• Description: Sets the desired number of machines in the machine pool. This method is asynchronous and returns immediately after updating the desired size. There may be a delay before the changes take effect and are reflected in the machine pool.

  Note: the cloud adapter should take measures to ensure that requested machines are recognized as pool members. The specific mechanism to mark group members, which may depend on the features offered by the particular cloud API, is left to the implementation but could, for example, make use of tags.

• Input: The desired number of machine instances in the pool as a Set desired size message.

• Output:

  • On success: HTTP response code 200 without message content.

  • On error:

    • on illegal input: code 400 with an Error response message
    • otherwise: HTTP response code 500 with an Error response message

Terminate machine¶

• Method: POST /pool/<machineId>/terminate

• Description: Terminates a particular machine pool member with id <machineId>. The caller can control if a replacement machine is to be provisioned via the decrementDesiredSize parameter.

• Input: A Terminate machine message.

• Output:

  • On success: HTTP response code 200 without message content.

  • On error:

    • on illegal input: code 400 with an Error response message
    • if the machine is not a pool member: code 404 with an Error response message
    • otherwise: HTTP response code 500 with an Error response message

Set service state¶

• Method: POST /pool/<machineId>/serviceState

• Description: Sets the service state of a machine pool member with id <machineId>. Setting the service state has no side-effects, unless the service state is set to OUT_OF_SERVICE, in which case a replacement machine will (eventually) be launched since out-of-service machines are not considered effective members of the pool. An out-of-service machine can later be taken back into service by another call to this method to re-set its service state.

  The specific mechanism to mark group members, which may depend on the features offered by the particular cloud API, is left to the implementation but could, for example, make use of tags.

• Input: A Set service state message.

• Output:

  • On success: HTTP response code 200 without message content.

  • On error:

    • on illegal input: code 400 with an Error response message
    • if the machine is not a pool member: code 404 with an Error response message
    • otherwise: HTTP response code 500 with an Error response message

Detach machine¶

• Method: POST /pool/<machineId>/detach

• Description: Removes a particular machine pool member with id <machineId> from the pool without terminating it. The machine keeps running but is no longer considered a pool member and, therefore, needs to be managed independently. The caller can control if a replacement machine is to be provisioned via the decrementDesiredSize parameter.

• Input: A Detach machine message.

• Output:

  • On success: HTTP response code 200 without message content.

  • On error:

    • on illegal input: code 400 with an Error response message
    • if the machine is not a pool member: code 404 with an Error response message
    • otherwise: HTTP response code 500 with an Error response message

Attach machine¶

• Method: POST /pool/<machineId>/attach

• Description: Attaches an already running machine with a given <machineId> to the machine pool, growing the pool with a new member. This operation implies that the desired size of the group is incremented by one.

• Input: None

• Output:

  • On success: HTTP response code 200 without message content.

  • On error:

    • on illegal input: code 400 with an Error response message
    • if the machine does not exist: code 404 with an Error response message
    • otherwise: HTTP response code 500 with an Error response message

Set desired size message¶

Sample document:

{ "desiredSize": 3 }

States that we want three machine instances in the pool.

Error response message¶

The message is a human-readable error message intended for presentation, whereas the detail attribute holds error details (such as a stack trace).

This is a sample error message:

{
  "message": "failure to process pool get request",
  "detail": "... long stacktrace ..."
}

Machine pool message¶

The machine pool schema has the following structure:

{
  "timestamp": <iso-8601 datetime>,
  "machines": [ <machine> ... ]
}

Here, every <machine> is also a json document with the following structure:

{
  "id": <string>,
  "machineState": <machine state>,
  "serviceState": <service state>,
  "launchtime": <iso-8601 datetime>,
  "publicIps": [<ip-address>, ...],
  "privateIps": [<ip-address>, ...],
  "metadata": <jsonobject>
}

The attributes are to be interpreted as follows:

• id: The identifier of the machine.
• machineState: The execution state of the machine. See the machine state table for the range of possible values.
• serviceState: The operational state of the service running on the machine. See the service state table for the range of possible values.
• launchtime: The launch time of the machine if it has been launched. If the machine is in a state where it hasn’t been launched yet (REQUESTED state) this attribute may be left out or set to null.
• publicIps: The list of public IP addresses associated with this machine. Depending on the state of the machine, this list may be empty.
• privateIps: The list of private IP addresses associated with this machine. Depending on the state of the machine, this list may be empty.
• metadata: Additional cloud provider-specific meta data about the machine. This field is optional (may be null).

Below is a sample machine pool document:

{
  "timestamp": "2013-11-07T13:50:00.000Z",
  "machines": [
    {
      "id": "i-123456",
      "machineState": "RUNNING",
      "serviceState": "IN_SERVICE",
      "launchtime": "2013-11-07T14:50:00.000Z",
      "publicIps": ["54.211.230.169"],
      "privateIps": ["10.122.122.69"],
      "metadata": {
        "scaling-group": "mygroup"
      }
    },
    {
      "id": "i-123457",
      "machineState": "PENDING",
      "serviceState": "BOOTING",
      "launchtime": "2013-11-07T13:49:50.000Z",
      "publicIps": [],
      "privateIps": [],
      "metadata": {
        "scaling-group": "mygroup",
      }
    }
  ]
}

Pool size message¶

The attributes are to be interpreted as follows:

• desiredSize: The last desired size set for the machine pool (see Set desired size).
• allocated: The number of allocated machines in the pool (in one of machine states REQUESTED, PENDING, RUNNING)
• outOfService: The number of machines in the pool that are marked with a OUT_OF_SERVICE service state.

Example:

{ "desiredSize": 3, "allocated": 4, "outOfService": 1 }

Terminate machine message¶

The attributes are to be interpreted as follows:

• decrementDesiredSize: true if the desired pool size should be decremented, false otherwise.

Example where a replacement machine is desired:

{ "decrementDesiredSize": false }

Detach machine message¶

The attributes are to be interpreted as follows:

• decrementDesiredSize: true if the desired pool size should be decremented, false otherwise.

Example where a replacement machine is desired:

{ "decrementDesiredSize": false }

Set service state message¶

The attributes are to be interpreted as follows:

• serviceState: The service state to set.

Example where a replacement machine is desired:

{ "serviceState": "IN_SERVICE" }