hudson.slaves
Class Cloud

java.lang.Object
  hudson.model.AbstractModelObject
      hudson.slaves.Cloud

All Implemented Interfaces:

ExtensionPoint, Describable<Cloud>, ModelObject, SearchableModelObject, SearchItem, AccessControlled

Direct Known Subclasses:

AbstractCloudImpl

public abstract class Cloud
extends AbstractModelObject
implements ExtensionPoint, Describable<Cloud>, AccessControlled

Creates Nodes to dynamically expand/shrink the slaves attached to Hudson.

Put another way, this class encapsulates different communication protocols needed to start a new slave programmatically.

Notes for implementers

Automatically delete idle slaves

Nodes provisioned from a cloud do not automatically get released just because it's created from Cloud. Doing so requires a use of RetentionStrategy. Instantiate your Slave subtype with something like CloudSlaveRetentionStrategy so that it gets automatically deleted after some idle time.

Freeing an external resource when a slave is removed

Whether you do auto scale-down or not, you often want to release an external resource tied to a cloud-allocated slave when it is removed.

To do this, have your Slave subtype remember the necessary handle (such as EC2 instance ID) as a field. Such fields need to survive the user-initiated re-configuration of Slave, so you'll need to expose it in your Slave configure-entries.jelly and read it back in through DataBoundConstructor.

You then implement your own Computer subtype, override Slave.createComputer(), and instantiate your own Computer subtype with this handle information.

Finally, override Computer.onRemoved() and use the handle to talk to the "cloud" and de-allocate the resource (such as shutting down a virtual machine.) Computer needs to own this handle information because by the time this happens, a Slave object is already long gone.

Author:

Kohsuke Kawaguchi

See Also:

NodeProvisioner, AbstractCloudImpl

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

static DescriptorList<Cloud>	ALL Deprecated. as of 1.286 Use all() for read access, and Extension for registration.
String	name Uniquely identifies this Cloud instance among other instances in Jenkins.clouds.
static Permission	PROVISION Permission constant to control mutation operations on Cloud.

Constructor Summary

protected

Cloud(String name)

Method Summary

static DescriptorExtensionList<Cloud,Descriptor<Cloud>>	all() Returns all the registered Cloud descriptors.
abstract boolean	canProvision(Label label) Returns true if this cloud is capable of provisioning new nodes for the given label.
void	checkPermission(Permission permission) Convenient short-cut for getACL().checkPermission(permission)
ACL	getACL() Obtains the ACL associated with this object.
Descriptor<Cloud>	getDescriptor() Gets the descriptor for this instance.
String	getDisplayName()
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
boolean	hasPermission(Permission permission) Convenient short-cut for getACL().hasPermission(permission)
abstract Collection<NodeProvisioner.PlannedNode>	provision(Label label, int excessWorkload) Provisions new Nodes from this cloud.

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, getSearchName, makeSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

public final String name

Uniquely identifies this Cloud instance among other instances in Jenkins.clouds. This is expected to be short ID-like string that does not contain any character unsafe as variable name or URL path token.

ALL

public static final DescriptorList<Cloud> ALL

Deprecated. as of 1.286 Use all() for read access, and Extension for registration.

All registered Cloud implementations.

PROVISION

public static final Permission PROVISION

Permission constant to control mutation operations on Cloud. This includes provisioning a new node, as well as removing it.

Constructor Detail

Cloud

protected Cloud(String name)

Method Detail

getDisplayName

public String getDisplayName()

Specified by:

getDisplayName in interface ModelObject

getSearchUrl

public String getSearchUrl()

Description copied from interface: SearchItem

Returns the URL of this item relative to the parent SearchItem.

Specified by:

getSearchUrl in interface SearchItem

Returns:

URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Hudson.)

getACL

public ACL getACL()

Description copied from interface: AccessControlled

Obtains the ACL associated with this object.

Specified by:

getACL in interface AccessControlled

Returns:

never null.

checkPermission

public final void checkPermission(Permission permission)

Description copied from interface: AccessControlled

Convenient short-cut for getACL().checkPermission(permission)

Specified by:

checkPermission in interface AccessControlled

hasPermission

public final boolean hasPermission(Permission permission)

Description copied from interface: AccessControlled

Convenient short-cut for getACL().hasPermission(permission)

Specified by:

hasPermission in interface AccessControlled

provision

public abstract Collection<NodeProvisioner.PlannedNode> provision(Label label,
                                                                  int excessWorkload)

Provisions new Nodes from this cloud.

NodeProvisioner performs a trend analysis on the load, and when it determines that it really needs to bring up additional nodes, this method is invoked.

The implementation of this method asynchronously starts node provisioning.

Parameters:

label - The label that indicates what kind of nodes are needed now. Newly launched node needs to have this label. Only those Labels that this instance returned true from the canProvision(Label) method will be passed here. This parameter is null if Hudson needs to provision a new Node for jobs that don't have any tie to any label.

excessWorkload - Number of total executors needed to meet the current demand. Always >= 1. For example, if this is 3, the implementation should launch 3 slaves with 1 executor each, or 1 slave with 3 executors, etc.

Returns:

NodeProvisioner.PlannedNodes that represent asynchronous Node provisioning operations. Can be empty but must not be null. NodeProvisioner will be responsible for adding the resulting Nodes into Hudson via Jenkins.addNode(Node), so a Cloud implementation just needs to return NodeProvisioner.PlannedNodes that each contain an object that implements Future. When the Future has completed its work, Future#get will be called to obtain the provisioned Node object.

canProvision

public abstract boolean canProvision(Label label)

Returns true if this cloud is capable of provisioning new nodes for the given label.

getDescriptor

public Descriptor<Cloud> getDescriptor()

Description copied from interface: Describable

Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass()==b.getClass() then a.getDescriptor()==b.getDescriptor() must hold.

Specified by:

getDescriptor in interface Describable<Cloud>

all

public static DescriptorExtensionList<Cloud,Descriptor<Cloud>> all()

Returns all the registered Cloud descriptors.