AnthillPro agents are light-weight Java processes that are installed on machines throughout your networks. Once installed on a machine, the agent allows AnthillPro to run commands on the machine, move files to and from the machine, and work with other tools installed on the machine.
In general, an agent is responsible for running builds, deploying projects, and/or driving third-party tools. When installing agents, keeping in mind what processes you want AnthillPro to perform, and where you want those processes to take place, can be a helpful guide. Following is a quick synopsis of the most common agent-usage scenarios and where agents are typically installed:
For builds. Agents are typically installed on every build machine. This allows you to maximize resources and enables simultaneous builds on different agents. If you have a project that requires a specific tool or platform to build, you can use, for example, an agent filter to specify which machine or set of machines to use.
For deployments. Many users install an agent on the deployment target machines -- particularly when a deployment requires running commands on a specific machine. Where a remote deployment is run, an agent is often placed on a machine that has access to the various target machines. In either case, the agent acts as a gateway for deployments.
For driving third-party tools. AnthillPro integrates with numerous tools and normally communicates with those tools through its agents. AnthillPro agents are responsible for triggering automated testing, creating an issue in your tracking tool, etc., on behalf of the server. In some instances, the agent must be installed on the same machine as the tool it is driving (where necessary, this is noted in the user documentation). Most third-party tools can be driven remotely through web services or API calls. The agent calling those tools would simply need to have access to those web services or APIs.
Once an installed agent has been started, the agent opens a socket connection to the server (securable by configuring SSL for server-agent communication) based on the information you gave during installation. The agent also utilizes AnthillPro's web services. For agents on a different network than the server, it may be necessary to punch some holes in a firewall to establish the connection. If the number of agents needing firewall exceptions grows inconveniently large, the Agent Relay can help. Once agent communication is established, the agent will be visible through the web UI (Agents > Agent), where it will need to be configured.
| If you are unfamiliar with AnthillPro Environments, it may be helpful to review that material to gain a better understanding of how AnthillPro Agents are managed and used. In short, Agents are pooled into environments. In AnthillPro, environments denote similar, high-level purposes of machines, often corresponding to groupings like "Shared Build Farm" or "My Department QA Lab." In turn, environments are pooled into groups usually corresponding to the different applications under development that use different sets of machines. Understanding how AnthillPro approaches environment management is necessary when configuring an agent. |
Agent configuration consists of assigning an agent to at least one environment (as well as adding properties and entering the load-balancing rules when appropriate). An agent not part of an environment will have few, if any, jobs assigned to it. AnthillPro also allows you to assign an agent to multiple environments. During agent configuration, the system administrator defines which environments are legal for an agent. For example, if an agent is assigned to both the DEV and QA environments, the agent can perform work on behalf of projects in either environment -- this allows you to better distribute workloads throughout the system. When performing work, AnthillPro uses the administrator configured agent filters in conjunction with load balancing to assign jobs to appropriate agents within the environment.
In addition to system-created meta-data, every AnthillPro Agent may include properties assigned by an administrator. These properties are typically used to denote capabilities. Many users set a property that denotes if and where a particular tool is installed (say Visual Studio); or, the dedicated purpose of the machine (web server or database server). This meta-information can be used to help determine what work is performed on which agent. For example, if a deployment to the QA lab involves both web servers and database servers with different processes run on each, the user-defined agent properties are used to ensure that the deployment is run successfully.
| For those with a large number of agents, you can use the Filter and Status fields to make searching for agents easier. Once the search is complete, you can then perform an Action on the returned list by selecting the appropriate agent(s). |
Agent filters are used to select the appropriate agent(s) that will execute a job. Agent filters are scoped by environments, so they can only select an agent within the environments available to a workflow. For example, if you want a build to run on an agent within the "DEV" environment, you would use the Any Agent Filter. When the job is performed, AnthillPro will assign the build to the least busy agent in that environment. See Configure and Edit Agent Filters.
There are three different types of agent filters in AnthillPro:
Any Agent Filter returns all online agents in the environment. The agents returned are ordered by a combination of their current load and throughput metric, and then the server selects the agent(s) to use based on their loads.
Fixed Agent Filter returns a specified agent. Use of this agent filter is discouraged because the job will fail if the agent is not available in the selected environment. However, for new users, the fixed agent filter can help with getting started if it takes the place of a more elegant, but more time consuming and difficult to create, Scripted Agent Filter.
Scripted Agent Filter programmatically selects the agent(s) appropriate for a job. Usually this is used to check variables on agents. For example, to find agents with a specific tool installed or used for a special purpose. When executed, the filter receives a collection of agents and is responsible for trimming that list to only appropriate agents. An example of Scripted Agent Filter usage can be seen in the Iterate a Job section.
Agent properties allow the user to configure a build or other process using parameters with values dependent on the agent on which the build (or process) is actually executed. For example, an agent property can be used to specify that an agent's local settings be used during a build, etc. One thing to keep in mind is that agent properties are resolved at run time (i.e., when the build is actually run), and on the Agent on which the build is running. See Agent Properties for more.
Implicit properties have a designation indicating where they come from. All environment properties as well as all Java system properties on an agent are automatically loaded and made available as agent properties. You can add new agent properties through the user interface on the central server. These properties are immediately usable, just like the implicit environment and system properties.
Consider the situation where you are configuring a build and need to use a specific version of Ant. You have a Linux machine and a Windows machine, both with AnthillPro agents, that could end up running the build. Further, Ant is installed in different locations on the Linux and Windows machines. You need to use an agent property to configure the build.
Using agent properties, you can define a variable named
user/ANT_HOME_1_6_5 on both agents. On the Windows agent,
the value of the property would be user/ANT_HOME_1_6_5 =
C:\apache\apache-ant-1.6.5. On the Linux agent, the value of
the property would be user/ANT_HOME_1_6_5 =
/opt/apache/apache-ant-1.6.5.
By configuring the AnthillPro agent property as above, either agent would be able to perform the job. The job itself would use a special syntax instruct AnthillPro to run the Ant located at property: ${user/ANT_HOME_1_6_5}.
Agent Environment Variables (not to be confused with AnthillPro
Environment Properties) are set at the time of agent installation, and
are stored on the central server. The agent-installation reads the
environment variables of the machine the agent is being installed on
and then sets the variables. Once set, AnthillPro will not check to
see if any of the environment variables have changed. If you change
one of the environment variables that the agent uses, it may cause the
agent to fail. For example, if you change the env/Path
variable on the machine, the agent will continue to use the original
setting. In this case, you may need to modify the agent's environment
variable to reflect the changes you made in order for the agent to
work. This can be done on the Agent's Environment tab by clicking the Edit icon of
the variable and making changes.
When configuring the central server to use an agent, you can assign a throughput metric. The throughput metric is an arbitrary integer indicating the relative throughput of one agent relative to another. For example, if one agent is running on a four CPU machine and a second is running on a single CPU machine, then the throughput metric of the first agent may be four and the throughput metric of the second agent may be one. AnthillPro considers current job loads and throughput when delegating jobs to agents.
Administrators configuring Agents can also set an absolute maximum number of jobs a particular agent can execute. If all agents selected by a filter are at their maximum, the next job will enter a priority queue waiting for ability.
Consider two agents. The first, "Quad" has a throughput of 9 and a max jobs setting of 6. The second, "Dual" has a throughput of 5 and a max of 4. If eleven jobs are generated quickly, they will be assigned something like:
User access to an agent is managed on the Security tab, as well as assigning permissions using AnthillPro's security system. Administrators can define what roles have access to read, write, or determine security for agents. You need administrative permissions to set agent security.