Before reading this page, it is highly recommended you read Distributed Architecture page.
|Table of Contents|
What are Agents?
Agents are build machines that are responsible for building and running actions. The Continua CI environment can be broken into two parts, the Continua Server and Continua Agents. The server stores all build data and controls and directs the build workflow, while the agents are solely responsible for running individual builds. All builds are broken up into Stages and these stages are individually sent to an agent to execute the stage's build steps. Note that this means that each stage of a build will not necessarily run on the same agent. For more information on the Continua architecture see the Distributed Architecture page.
Agents allow you to run multiple builds concurrently across your network. Note that builds can run concurrently, not stages on a single build. Stages will always run sequentially.
The standard Continua installer also includes the agent installer. With the default free license, Continua comes with 1 agent which must be installed locally on the Continua Server. Note that with the default free license, only one build can be executed at any one time. Additional licenses must be purchased before concurrent builds are enabled.
If your Continua environment includes multiple concurrent builds then additional agents can be installed on your network. An unlimited number of agents can be installed on your network once your Continua CI environment has been licensed for multiple concurrent builds.
How Does Continua Decide Which Agent Will Run a Particular Build?
Every stage that is executed as part of the build process must be build by an agent, however each stage within a build process are self contained and are treated individually. This means that as a build executes, its stages may be built on different agents. The Distributed Architecture concepts page has more information on how each stage is processed by the server and agent.
When a stage is ready to execute, the Continua server must select an agent to run the current stage. When selecting an agent the server will always choose an agent that is capable of running every single action in that stage. Continua uses Agent Properties (which are automatically created by Property Collectors) to determine whether an agent can execute each action.
For example, say you have a stage that runs an NUnit action which is set to use NUnit version 2.6.2. Once this stage is ready to execute, the server will find all agents that have NUnit 2.6.2 installed by checking whether the agent has the nunit.2.6.2.path property (Check out the Agent Properties page for more information). This property provides the path to the installed NUnit executable on the agent. If an agent does not have this property then NUnit 2.6.2 cannot be found on the agent. Any agent that does not have this property will never be able to run this stage until NUnit 2.6.2 is installed.
Once the server has all the agents that can run the current stage, it will then try to assign the stage to an agent that is currently available. If all your agents are available then it will arbitrarily pick an agent to run that stage.
Concurrent stages allow you to specify how many stages a particular agent can run concurrently. More information on concurrent stages can be found at the bottom of this page.
If you have multiple builds running over multiple agents, Continua will attempt to send the current stage to the agent that is running the least amount of stages.
Viewing All Agents
All Continua agents can be viewed through the administration section on the Agents page (as shown below). This page shows you all agents that are currently registered with Continua CI and each agent can be viewed individually to provide more detailed information regarding that agent.
Viewing A Specific Agent
A specific agent can be viewed by navigating to the Agents page (described above) and selecting a particular agent by clicking [View]. This will take you to the agent detail page (as shown below). This page provides detailed information on a particular agent including the Agent Compatibility Matrix, Agent Properties and Agent Conditions.
Adding an Agent
An unlimited number of agents can be added to Continua once your Continua CI environment has been enabled for multiple concurrent builds. A machine on your network can become an agent by running the Continua CI Agent Installer on that machine. This installer is bundled with the Continua CI server installer and it can be accessed through the Agents page in the Administration section. The download links are found at the top of this page and these links provide you with both the 32 and 64-bit installers.
Once you have the agent installer, you will need to run it on the machine that will become an agent. Check out the Agent Installation page for more details on installing agents.
Once the Agent installer has finished, the ContinuaCIAgent service will start automatically. Once this service is running, your agent will automatically be added to your Continua CI environment and it will now be viewable through the Agents page.
Agents can be in one of the following states:
Online agents have successfully registered with the Continua Server and are ready to start running builds.
Offline agents have not contacted the Continua Server for some time and are essentially a dead agent. Offline agents will remain offline until the agent manages to contact the Continua CI server.
Agents can be offline for the following reasons:
- The agent machine is currently off.
- The ContinuaCIAgent service is not running or was uninstalled from the agent.
- The ContinuaCIAgent service is not configured correctly and it is not pointing to the Server's correct port. By default, Continua listens for agents on port 9000.
Unauthorised agents have successfully registered with Continua however they are not yet authorised to execute builds. This prevents unauthorised users from installing agents on other machines as an administrator needs to manually authorise each agent.
All agents must be authorised before they can execute builds.
Agents can be authorised and unauthorised through the agents page on the administration menu.
Deleting an Agent
Agents can be removed from Continua CI by uninstalling the Continua CI Agent Service from the target machine.
Once this service has been uninstalled, it can no longer communicate with the Continua CI server, however Continua will still contain a reference to that agent until it has been deleted from Continua CI. All deleted agents will be displayed as Offline until they are removed from Continua (as shown below). Offline agents can be deleted using the [Delete] link. Once an agent has been uninstalled and deleted then it has been completely removed from Continua CI.
Authorising & Unauthorising Agents
Agents can be authorised and unauthorised through the Agents page in the administration section of Continua. Unauthorised agents can be authorised through the [Authorise] link while online agents can be unauthorised through the [Unauthorise] link.
Note that offline agents cannot be authorised or unauthorised. Only agents that are currently connected to the server can authorised and unauthorised.
Agent Version Compatibility
As agents are installed independently of the Continua server, they can run a different version of Continua than the server. It is highly recommended that whenever you update the Continua server that you also update all of your agents. Each server upgrade that is released also includes the agent upgrade which will always be the same version number as the Continua Server.
An agent's version compatibility can be checked through the Agents page in the administration section. This page lists each agent and its compatibility via the Compat. column (as shown below). Hovering over the compatibility logo will provide more information regarding the version compatibility of a particular build.
Each agent running in Continua will have one of the following version compatibilities:
The agent is running the same version as the Continua Server.
The agent is running an older version than the Continua Server however the agent is still compatible with the server. It is recommended that you upgrade your agents to the same version as your server, however builds can still be run on this server.
The agent is running an older version than the Continua Server and it is no longer compatible with the server. Builds will no longer work on this agent until it is upgraded to the same version as the server. An agent will only become incompatible if a later release includes changes to the agent code as well as the server.
If you are having issues connecting your agent to the server then read through our Agent Troubleshooting page.
Conditions allow you to define rules that restrict when an agent can be used to execute a build. Check out the Agent Conditions page for more information.
Agent properties store information about the agent that can then be used in builds, finding build tools, etc. Most properties are automatically generated with Property Collectors however custom properties can also be created. Check out the Agent Properties page for more information.
The number of concurrent stages on an agent define how many stages an agent can process at any one time. For example, if you have 5 builds queued and an agent set to 3 concurrent builds then 3 builds will be sent to the agent while the remaining 2 builds will remain on the queue.
Reducing the number of concurrent stages on an agent can help reduce the strain on a particular agent and can force builds to run on other agents instead.
You can set the concurrent stages limit to unlimited by specifying 0 stages.
Note that concurrent stages can only be used once Continua CI has been licensed and concurrent builds have been enabled. If you are running the free edition of Continua then the local agent can only ever run 1 build at a time. Also, the number of concurrent builds as defined by your license takes precedence over an agent's concurrent stages. For example, if your license grants you 5 concurrent builds then each agent will be automatically capped at 5 concurrent stages. Note that your concurrent builds, as specified by your license, cap the total number of builds running across all agents at any one time. So given that your license grants you 5 concurrent builds and you have 2 agents, both with their concurrent stages set to 5, you will never be able to run more than 5 builds at any one time between both agents, regardless of the agent's concurrent stages limit.
Each Agent comes with a compatibility list that shows whether the agent is capable of running each stage. Check out the Agent Compatibility Matrix page for more information.