com.elastisys.scale.cloudpool.api

Interface CloudPool

All Known Implementing Classes:

CloudPoolClient

public interface CloudPool

A CloudPool is a management interface towards an elastic pool of machines for a particular cloud provider, handling communication with the cloud provider according to its API. The CloudPool provides a cloud-neutral API to clients, such as the autoscaler, with a number of management primitives for the machine pool. In general terms, these primitives allow clients to:

• track the machine pool members and their states
• modify the size of the machine pool (the cloud pool continuously starts/stops machine instances so that the number of machines in the pool matches the desired size set for the pool)

A CloudPool instance is intended to be made network-accessible by a CloudPoolRestApi REST endpoint, which exposes the CloudPool through the elastisys:scale cloud pool REST API).

Implementors should take measures to ensure that implementations are thread-safe, since they may be called by several concurrent threads.

See Also:

CloudPoolRestApi

Method Summary

Modifier and Type	Method and Description
void	attachMachine(String machineId) Attaches an already running machine instance to the pool, growing the pool with a new member.
void	configure(com.google.gson.JsonObject configuration) Updates the configuration for this CloudPool.
void	detachMachine(String machineId, boolean decrementDesiredSize) Removes a member from the pool without terminating it.
com.google.common.base.Optional<com.google.gson.JsonObject>	getConfiguration() Returns the configuration currently set for this CloudPool, if one has been set.
MachinePool	getMachinePool() Returns a list of the members of the cloud pool.
PoolSizeSummary	getPoolSize() Returns the current size of the MachinePool -- both in terms of the desired size and the actual size (as these may differ at any time).
CloudPoolStatus	getStatus() Returns the execution status for the CloudPool.
void	setDesiredSize(int desiredSize) Sets the desired number of machines in the machine pool.
void	setMembershipStatus(String machineId, MembershipStatus membershipStatus) Sets the membership status of a given pool member.
void	setServiceState(String machineId, ServiceState serviceState) Sets the service state of a given machine pool member.
void	start() Starts the CloudPool.
void	stop() Stops the CloudPool.
void	terminateMachine(String machineId, boolean decrementDesiredSize) Terminates a particular machine pool member.

Method Detail

configure

void configure(com.google.gson.JsonObject configuration)
        throws IllegalArgumentException,
               CloudPoolException

Updates the configuration for this CloudPool.

This operation does not change the CloudPool's started state -- if the CloudPool is started it should remain started, and if it is in a stopped state it should remain stopped.

The configuration is passed as a JSON object. It is up to the CloudPool to validate and apply the contents of the configuration as well as to perform whatever changes are needed for the new configuration to take effect.

Parameters:

configuration - The JSON configuration to be set.

Throws:

IllegalArgumentException - If the received configuration was invalid.

CloudPoolException - If the configuration could not be applied.

getConfiguration

com.google.common.base.Optional<com.google.gson.JsonObject> getConfiguration()

Returns the configuration currently set for this CloudPool, if one has been set.

Returns:

A JSON configuration if set, Optional.absent() otherwise.

start

void start()
    throws NotConfiguredException

Starts the CloudPool.

This will set the CloudPool in an activated state where it will start to accept requests to query or modify the machine pool.

If the CloudPool has not been configured the method will fail. If the CloudPool is already started this is a no-op.

Throws:

NotConfiguredException - If the CloudPool has not been configured.

stop

void stop()

Stops the CloudPool.

A stopped CloudPool is in a passivated state and will not accept any requests to query or modify the machine pool.

If the CloudPool is already in a stopped state this is a no-op.

getStatus

CloudPoolStatus getStatus()

Returns the execution status for the CloudPool.

Returns:

getMachinePool

MachinePool getMachinePool()
                    throws CloudPoolException,
                           NotStartedException

Returns a list of the members of the cloud pool.

Note, that the response may include machines in any MachineState, even machines that are in the process of terminating.

The MembershipStatus of a machine in an allocated/started state determines if it is to be considered an active member of the pool.The active size of the machine pool should be interpreted as the number of allocated machines (in any of the non-terminal machine states REQUESTED, PENDING or RUNNING that have not been marked with an inactive MembershipStatus. See Machine.isActiveMember().

The service state should be set to UNKNOWN for all machine instances for which no service state has been reported (see setServiceState(String, ServiceState)).

Similarly, the MembershipStatus should be set to MembershipStatus.defaultStatus() for all machine instances for which no membership status has been reported (see setMembershipStatus(String, MembershipStatus)).

Returns:

A list of cloud pool members.

Throws:

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

getPoolSize

PoolSizeSummary getPoolSize()
                     throws CloudPoolException,
                            NotStartedException

Returns the current size of the MachinePool -- both in terms of the desired size and the actual size (as these may differ at any time).

Returns:

The current PoolSizeSummary.

Throws:

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

setDesiredSize

void setDesiredSize(int desiredSize)
             throws IllegalArgumentException,
                    CloudPoolException,
                    NotStartedException

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 CloudPool implementation should take measures to ensure that requested machines are recognized as pool members. The specific mechanism to mark pool 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.

Parameters:

desiredSize - The desired number of machines in the pool.

Throws:

IllegalArgumentException - If the desired size is illegal.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

terminateMachine

void terminateMachine(String machineId,
                      boolean decrementDesiredSize)
               throws NotFoundException,
                      CloudPoolException,
                      NotStartedException

Terminates a particular machine pool member. The caller can control if a replacement machine is to be provisioned via the decrementDesiredSize parameter.

Parameters:

machineId - The machine to terminate.

decrementDesiredSize - If the desired pool size should be decremented (true) or left at its current size (false).

Throws:

NotFoundException - If the specified machine is not a member of the pool.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

setServiceState

void setServiceState(String machineId,
                     ServiceState serviceState)
              throws NotFoundException,
                     CloudPoolException,
                     NotStartedException

Sets the service state of a given machine pool member. Setting the service state does not have any functional implications on the pool member, but should be seen as way to supply operational information about the service running on the machine to third-party services (such as load balancers).

Parameters:

machineId - The id of the machine whose service state is to be updated.

serviceState - The ServiceState to assign to the machine.

Throws:

NotFoundException - If the specified machine is not a member of the pool.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

setMembershipStatus

void setMembershipStatus(String machineId,
                         MembershipStatus membershipStatus)
                  throws NotFoundException,
                         CloudPoolException,
                         NotStartedException

Sets the membership status of a given pool member.

The membership status for a machine can be set to protect the machine from being terminated (by setting its evictability status) and/or to mark a machine as being in need of replacement by flagging it as an inactive pool member.

Parameters:

machineId - The id of the machine whose status is to be updated.

membershipStatus - The MembershipStatus to set.

Throws:

NotFoundException

CloudPoolException

NotStartedException - If the CloudPool is not started.

attachMachine

void attachMachine(String machineId)
            throws NotFoundException,
                   CloudPoolException,
                   NotStartedException

Attaches an already running machine instance to the pool, growing the pool with a new member. This operation implies that the desired size of the pool is incremented by one.

Parameters:

machineId - The identifier of the machine to attach to the pool.

Throws:

NotFoundException - If the specified machine does not exist.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

detachMachine

void detachMachine(String machineId,
                   boolean decrementDesiredSize)
            throws NotFoundException,
                   CloudPoolException,
                   NotStartedException

Removes a member 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.

Parameters:

machineId - The identifier of the machine to detach from the pool.

decrementDesiredSize - If the desired pool size should be decremented (true) or left at its current size (false).

Throws:

NotFoundException - If the specified machine is not a member of the pool.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.