Package 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 Detail

      • configure

        void configure​(com.google.gson.JsonObject configuration)
        throws java.lang.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:
        java.lang.IllegalArgumentException - If the received configuration was invalid.
        CloudPoolException - If the configuration could not be applied.

      • getConfiguration

        java.util.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.

      • 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.

      • setDesiredSize

        java.util.concurrent.Future<?> setDesiredSize​(int desiredSize)
                                       throws java.lang.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. The method returns a Future that the caller can use if it needs to wait for the size update to be applied to the 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.
        Returns:
        A Future that the caller can use to wait for the size update to be applied to the pool.
        Throws:
        java.lang.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​(java.lang.String machineId,
                      boolean decrementDesiredSize)
               throws NotFoundException,
                      NotEvictableException,
                      CloudPoolException,
                      NotStartedException
        Terminates a particular machine pool member. The caller can control if a replacement machine is to be provisioned via the decrementDesiredSize parameter.

        Note: a machine that is protected from removal by a membership status with evictable: false can not be terminated.

        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.
        NotEvictableException - If the specified machine has a MembershipStatus that prevents it from being removed.
        CloudPoolException - If the operation could not be completed.
        NotStartedException - If the CloudPool is not started.

      • setServiceState

        void setServiceState​(java.lang.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.

      • detachMachine

        void detachMachine​(java.lang.String machineId,
                   boolean decrementDesiredSize)
            throws NotFoundException,
                   NotEvictableException,
                   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.

        Note: a machine that is protected from removal by a membership status with evictable: false can not be terminated.

        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.
        NotEvictableException - If the specified machine has a MembershipStatus that prevents it from being removed.
        CloudPoolException - If the operation could not be completed.
        NotStartedException - If the CloudPool is not started.