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

  • Field Details

    • name

      public 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 Details

    • Cloud

      protected Cloud(String name)

  • Method Details

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

      By default looks for a nested class (conventionally named DescriptorImpl) implementing Descriptor and marked with Extension.

      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(org.kohsuke.accmod.restrictions.DoNotUse.class) public static void registerPermissions()

    • getIcon

      public String getIcon()

    • getIconClassName

      public String getIconClassName()

    • getIconAltText

      public String getIconAltText()

    • doDoDelete

      public org.kohsuke.stapler.HttpResponse doDoDelete() throws IOException
      Deletes the cloud.
      Throws:
      IOException

    • doConfigSubmit

      @POST public org.kohsuke.stapler.HttpResponse doConfigSubmit(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException, Descriptor.FormException
      Accepts the update to the node configuration.
      Throws:
      IOException
      jakarta.servlet.ServletException
      Descriptor.FormException

    • reconfigure

      public Cloud reconfigure(@NonNull org.kohsuke.stapler.StaplerRequest2 req, net.sf.json.JSONObject form) throws Descriptor.FormException
      Throws:
      Descriptor.FormException
      Since:
      2.475

    • reconfigure

      @Deprecated public Cloud reconfigure(@NonNull org.kohsuke.stapler.StaplerRequest req, net.sf.json.JSONObject form) throws Descriptor.FormException
      Deprecated.
      use reconfigure(StaplerRequest2, JSONObject)
      Throws:
      Descriptor.FormException