Index: continuum-docs/src/site/apt/administrator_guides/distributed-builds.apt =================================================================== --- continuum-docs/src/site/apt/administrator_guides/distributed-builds.apt (revision 734319) +++ continuum-docs/src/site/apt/administrator_guides/distributed-builds.apt (working copy) @@ -2,24 +2,176 @@ Distributed Builds ------------------ +Introduction -Understanding Distributed Builds + The Distributed Builds is an extension to the base Continuum + functionalities that gives us the ability to process multiple independent + builds beyond the capacity of a single server's processing power. It also + enables us to execute builds on multiple different platforms while + retaining a unified view of all project builds. - When the 'Distributed Builds' option in General Configuration is enabled, the Continuum instance will become the - Master and will delegate all builds to configured Build Agents. +* Understanding Distributed Builds - There is a one to many relationship between the master and the agents. A master may have many agents, but each - agent only has one master. +Architecture - Communication happens over XML-RPC, first with the Master contacting an agent to supply the necessary info and invoke - a build, and then with the agent later contacting the master to return the build results. + Continuum follows a Client-Server model using XML-RPC as the protocol. + However, since it uses a bi-directional XML-RPC implementation, we instead + distinguish the components by calling them Master and Slave Build Agents. - An agent may be installed on the same server as the master, or on a separate server. + The Master Build Agent is a Continuum instance that has the ability to + delegate the builds to registered Slave Build Agents. - More than one agent may be installed on a server. + The Slave Build Agent is a standalone Jetty-bundled webapp that + listens for any build requests from the Master Build Agent it is + assigned to. - TODO: When a build is enqueued, the choice of which agent to use is defined by ____. + There is a one-to-many relationship between the Master and the Slaves. + A Master may have many Slaves, but each Slave can only have one Master. - TODO: How are multi-module projects handled? + TODO: insert image here - TODO: How are releases handled? +Behavior + + Distributed Builds happen at the project group level of Continuum. + When the entire project group is built in the Master, independent projects + (single project or multi-module project) are distributed to any available + registered Slave. A Slave is said to be available when it is currently not + building anything as it can only attend to a single build request from the + Master. + + In a project group containing a mix of projects, the distribution of work + goes through the following steps: + + [[1]] In the Master, a build in the project group is triggered. + + [[2]] Every independent project within the project group is identified, + whether as a single project or a multi-module project. Projects with + inter-dependencies cannot be distributed separately, so multi-module + projects are delegated to a Slave as one build. + + [[3]] For each independent project, the Master iterates over the list of + registered Slaves and queries each if available. The query is an XML-RPC + <<>> followed by an <<>> invocation. + + [[4]] If a Slave is available, the Master collects the information + necessary for the build (SCM url, project id, etc.) and passes it when + invoking <<>>. + + [[5]] In the Slave, the build request is processed: the build is queued and + executed. Upon execution, the Slave first performs an SCM checkout then + the actual build follows. The SCM checkout will result in invoking a + <<>> callback method in the Master. + + [[6]] At this point, when the build is running, the Master can invoke + <<>> which returns a transient build result, and + <<>> that updates the build output viewed in the Master. + + [[7]] After the build, the Slave returns the complete build result to the + Master by invoking the callback method <<>>, which the + Master aggregates to provide a unified view of projects + + [] + + TODO: insert sequence diagram here + +* Setup + +Configuring the Master Build Agent to use Distributed Builds + + The Master Build Agent is simply the Continuum instance, so just perform + the following steps in the web interface. + + Click the <> link under the <> section. + +[../images/configuration-menu.png] Configuration + + Check the <> checkbox in the <> section. + +[../images/enable-distributed-builds.png] Enable Distributed Builds + + Now that the Master is enabled, Slaves can now be registered as described {{{./build-agents.html}here}}. + + Once done, all project groups have the ability to distribute builds. + +Installing and Configuring the Slave Build Agent + + The Slave Build Agent is available as a separate standalone Jetty-bundled + webapp. Installing it is as simple as extracting it to a preferred + directory. To run the Slave, the startup script is available in + <<<$CONTINUUM_BUILDAGENT_HOME/bin/continuum-buildagent>>> (or + <<<%CONTINUUM_BUILDAGENT_HOME%\\bin\\continuum-buildagent.bat>>> + in Windows). + + The Slave runs on a specific port (defaulting to 8181), so it is possible + to install multiple Slaves in one machine. It may also be possible to + install Slaves in the same machine as the Master. To configure the Slave + to run using a different port, edit the + <<<$CONTINUUM_BUILDAGENT_HOME/conf/jetty.xml>>>. + + Another configuration file to look at is the + <<<$CONTINUUM_BUILDAGENT_HOME/conf/continuum-buildagent.xml>>>. It may be + required to manually pre-configure the Slave for now, as there is no web + interface to configure it yet. Here is a sample configuration: + ++-------------------------------------------------- + + /home/user/apache-continuum-buildagent-1.3.1-SNAPSHOT/buildOutputDirectory + /home/user/apache-continuum-buildagent-1.3.1-SNAPSHOT/workingDirectory + http://localhost:8080/master-xmlrpc + + + Maven 2 Home + maven2 + /home/user/apache-maven-2.0.9 + + + ++-------------------------------------------------- + + A minimal configuration may have the following fields: + + * <<>> - similar to the build output directory of Continuum + + * <<>> - similar to the working directory of Continuum + + * <<>> - the url pointing to the XML-RPC context of the Master Build Agent + + * <<>> - similar to the installations in Continuum + +* Limitations + + * the Slave selection policy is currently following a fixed informal next-available policy; a Slave cannot be assigned to a specific project build + + * only system administrator can enable/disable distributed builds + + * releases are not supported + + * credentials (s.a. svn credentials) are passed along if specified, but if server cache is used it will need to be done individually on the slaves + + * there is no tracking of scm changes + + * the Slave needs a configuration web interface + +* Future Enhancements + + * Remote builders + + * Builders can be installed on remote machines, a Continuum manager will send actions to run to builders. An action can be something to run on all builders, on some of them or eventually only to an available builder if we don't want to run more than one build. Actions can be sent with JMS and builders can apply some filters if they don't want to receive all actions. With that, we can do some parallel builds but the dependency tree must be respected for the build order. To work correctly with dependencies, each builders must use a central local repository. Maybe we can use an internal Archiva. + + * With Continuum builders configured to receive all commands, users can run multi-platform build for each build definition execution + + * With Continuum builders configured to receive only some project types, users can use a different builder by project group. In this case, the build of all projects will be done quickly because commands are balanced on few servers + + * With Continuum builders configured to build something when it is available, users can install few builders on several machine to balance the charge. In this case, it will be possible to run some parallel builds. + + * When the builder work will be done, a message will be sent to the manager to notify the end of the process. + + * With JMS used for the communication, we can add some listeners to create reports/statistics, log some informations + + * Policy-based distribution + + * Next available + + * Load balanced + + * Targetted environment matching