co.cask.cdap.runtime.spi.provisioner

Interface Provisioner

public interface Provisioner

A Provisioner is responsible for creating and deleting clusters for program runs. Each method may be retried in case of a failure, so must be implemented in an idempotent way.

Method Summary

Modifier and Type	Method and Description
Cluster	createCluster(ProvisionerContext context) Request to create a cluster.
void	deleteCluster(ProvisionerContext context, Cluster cluster) Request to delete a cluster.
Capabilities	getCapabilities() Returns Capabilities of this provisioner.
Cluster	getClusterDetail(ProvisionerContext context, Cluster cluster) Get details about the cluster.
ClusterStatus	getClusterStatus(ProvisionerContext context, Cluster cluster) Get the status of the cluster.
PollingStrategy	getPollingStrategy(ProvisionerContext context, Cluster cluster) Get the PollingStrategy to use when polling for cluster creation or deletion.
ProvisionerSpecification	getSpec() Return the specification for the provisioner.
default void	initialize(ProvisionerSystemContext systemContext) Initialize the provisioner.
default void	initializeCluster(ProvisionerContext context, Cluster cluster) Responsible for any additional initialization steps for the cluster.
void	validateProperties(Map<String,String> properties) Check that the specified properties are valid.

Method Detail

getSpec

ProvisionerSpecification getSpec()

Return the specification for the provisioner.

Returns:

the provisioner specification

initialize

default void initialize(ProvisionerSystemContext systemContext)

Initialize the provisioner. This method is guaranteed to be called before any other method is called. It will only be called once for the lifetime of the provisioner. If this method throws a runtime exception, the provisioner will not be available for use. This can cause clusters that were created by the provisioner to be stranded in an orphaned state. As such, provisioners should be careful to only throw exceptions when there is absolutely nothing that can be done. For example, if an optional property is set to an invalid value, that property should be ignored. An exception should not be thrown in that case.

Parameters:

systemContext - the system context that can be used to initialize the provisioner

validateProperties

void validateProperties(Map<String,String> properties)

Check that the specified properties are valid. If they are not, an IllegalArgumentException should be thrown.

Parameters:

properties - properties to validate

Throws:

IllegalArgumentException - if the properties are invalid

createCluster

Cluster createCluster(ProvisionerContext context)
               throws Exception

Request to create a cluster. The cluster does not have to be operational before the method returns, but it must be at least in the processes of being created. Must be implemented in an idempotent way, otherwise there may be resource leaks. This means the implementation must first check if the cluster exists before trying to create it, otherwise multiple clusters may be created for a single program run. The cluster returned will be passed to subsequent calls.

Parameters:

context - provisioner context

Returns:

information about the cluster

Throws:

RetryableProvisionException - if the operation failed, but may succeed on a retry

Exception - if the operation failed in a non-retryable fashion

getClusterStatus

ClusterStatus getClusterStatus(ProvisionerContext context,
                               Cluster cluster)
                        throws Exception

Get the status of the cluster. If it does not exist, ClusterStatus.NOT_EXISTS should be returned. This is used to poll for status after createCluster(ProvisionerContext) or deleteCluster(ProvisionerContext, Cluster) is called.

Parameters:

context - provisioner context

cluster - the cluster to get the status of

Returns:

the status of the cluster

Throws:

RetryableProvisionException - if the operation failed, but may succeed on a retry

Exception - if the operation failed in a non-retryable fashion

getClusterDetail

Cluster getClusterDetail(ProvisionerContext context,
                         Cluster cluster)
                  throws Exception

Get details about the cluster. If the cluster does not exist, a cluster with status ClusterStatus.NOT_EXISTS should be returned. This is called after a cluster has been created, but before it has been initialized.

Parameters:

context - provisioner context

cluster - the cluster to get

Returns:

details about the cluster

Throws:

RetryableProvisionException - if the operation failed, but may succeed on a retry

Exception - if the operation failed in a non-retryable fashion

initializeCluster

default void initializeCluster(ProvisionerContext context,
                               Cluster cluster)
                        throws Exception

Responsible for any additional initialization steps for the cluster. This method will be called after the cluster is created and goes into RUNNING status. This method might get called multiple times in case of failure, hence it is advised to have it be implemented in an idempotent way. By default this method is an no-op.

Parameters:

context - provisioner context

cluster - the cluster to operate on

Throws:

RetryableProvisionException - if the operation failed, but may succeed on a retry

Exception - if the operation failed in a non-retryable fashion

deleteCluster

void deleteCluster(ProvisionerContext context,
                   Cluster cluster)
            throws Exception

Request to delete a cluster. The cluster does not have to be deleted before the method returns, but it must at least be in the process of being deleted. Must be implemented in an idempotent way.

Parameters:

context - provisioner context

cluster - the cluster to delete

Throws:

RetryableProvisionException - if the operation failed, but may succeed on a retry

Exception - if the operation failed in a non-retryable fashion

getPollingStrategy

PollingStrategy getPollingStrategy(ProvisionerContext context,
                                   Cluster cluster)

Get the PollingStrategy to use when polling for cluster creation or deletion. The cluster status is guaranteed to be ClusterStatus.CREATING or ClusterStatus.DELETING.

Parameters:

context - provisioner context

cluster - the cluster to poll status for

getCapabilities

Capabilities getCapabilities()

Returns Capabilities of this provisioner. Capabilities allow plugins requiring special Requirements to be run in the provisioner if all the requirements are met. If a program requires a requirement that is not supported by the provisioner, the platform will fail the program run before provisioning begins.

Returns:

Capabilities of this provisioner