hudson.slaves

Class Cloud

java.lang.Object

hudson.model.AbstractModelObject

hudson.model.Actionable

hudson.slaves.Cloud

All Implemented Interfaces:

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

Direct Known Subclasses:

AbstractCloudImpl

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

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

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

Notes for implementers

Automatically delete idle agents

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 an agent is removed

Whether you do auto scale-down or not, you often want to release an external resource tied to a cloud-allocated agent 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.

Views

Since version 2.64, Jenkins clouds are visualized in UI. Implementations can provide top or main view to be presented at the top of the page or at the bottom respectively. In the middle, actions have their summary views displayed. Actions further contribute to sidepanel with box views. All mentioned views are optional to preserve backward compatibility.

Author:

Kohsuke Kawaguchi

See Also:

NodeProvisioner, AbstractCloudImpl

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Cloud.CloudState Parameter object for Cloud.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Nested classes/interfaces inherited from interface jenkins.model.ModelObjectWithContextMenu

ModelObjectWithContextMenu.ContextMenu, ModelObjectWithContextMenu.ContextMenuVisibility, ModelObjectWithContextMenu.MenuItem, ModelObjectWithContextMenu.MenuItemType

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Modifier	Constructor and Description
protected	Cloud(String name)

Method Summary

Modifier and Type	Method and Description
static DescriptorExtensionList<Cloud,Descriptor<Cloud>>	all() Returns all the registered Cloud descriptors.
boolean	canProvision(Cloud.CloudState state) Returns true if this cloud is capable of provisioning new nodes for the given label.
boolean	canProvision(Label label) Deprecated. Use canProvision(CloudState) instead.
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.
String	getUrl() Get URL of the cloud.
Collection<NodeProvisioner.PlannedNode>	provision(Cloud.CloudState state, int excessWorkload) Provisions new Nodes from this cloud.
Collection<NodeProvisioner.PlannedNode>	provision(Label label, int excessWorkload) Deprecated. Use provision(CloudState, int) instead.
static void	registerPermissions()

Methods inherited from class hudson.model.Actionable

addAction, addOrReplaceAction, doContextMenu, getAction, getAction, getActions, getActions, getAllActions, getDynamic, removeAction, removeActions, replaceAction, replaceActions

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

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, checkPermission, hasAnyPermission, hasPermission, hasPermission, hasPermission2

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

@Deprecated
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

getUrl

@NonNull
public String getUrl()

Get URL of the cloud.

Returns:

Jenkins relative URL.

Since:

2.64

getSearchUrl

@NonNull
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 Jenkins.)

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.

provision

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

Deprecated. Use provision(CloudState, int) instead.

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 agents with 1 executor each, or 1 agent 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.

provision

public Collection<NodeProvisioner.PlannedNode> provision(Cloud.CloudState state,
                                                         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:

state - the current state.

excessWorkload - Number of total executors needed to meet the current demand. Always ≥ 1. For example, if this is 3, the implementation should launch 3 agents with 1 executor each, or 1 agent 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

@Deprecated
public boolean canProvision(Label label)

Deprecated. Use canProvision(CloudState) instead.

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

canProvision

public boolean canProvision(Cloud.CloudState state)

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 by default a.getDescriptor() == b.getDescriptor() as well. (In rare cases a single implementation class may be used for instances with distinct descriptors.)

Specified by:

getDescriptor in interface Describable<Cloud>

all

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

Returns all the registered Cloud descriptors.

registerPermissions

@Initializer(before=SYSTEM_CONFIG_LOADED)
 @Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
public static void registerPermissions()