Package hudson.slaves

Class 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

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

      • 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

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

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