Agent Installation Methods

Agent Installation Methods

You are here:
< Back


One of the most important aspects in Cloudify topology design is the installation of Cloudify’s agents. This document aims to detail the differences between the various installation methods, prerequisites, and common pitfalls.

Agent — Yes or No?

Before deciding on an agent installation method, it’s worth considering whether an agent installation is really required, or beneficial.
The agent has two roles:

  • Locally executing operations (including scripts and plugins) on the machine and communicating termination states to the Cloudify Manager.
  • Collecting metrics and reporting them back to the remote Cloudify Manager.

If collecting metrics is not required (or is done by some external measures), then the only factor remaining is whether running tasks, locally on a remote machine, is needed.

  • If the user’s topology only requires running scripts on remote machines, then using Fabric may be an acceptable approach. However:
    • Fabric is only applicable for Linux platforms.
    • Fabric requires the remote machine to have an SSH port open. This may not be possible in certain organizations, due to security concerns.
    • For using Fabric, the manager must have routable traffic to the remote machine. In certain multi-cloud environments, this may not be possible.
  • If the user has (or is planning on having) agent-side plugins, then installing an agent is a must.

Disabling Agent Installation

To disable the agent’s installation altogether, specify the value “none” for “installation_method“:

    install_method: none

Common Considerations

The Agent’s User

Regardless of the agent installation method being chosen, the agent’s service must run under some user account on the remote VM.
The identity of this user is specified by the user key of the agent_config property:

    user: centos

Agent → Manager Communication

Regardless of the chosen installation method, eventually the agent requires access to the manager, through the following ports:

  • 5671, for RabbitMQ
  • 53229, for the manager’s file server
  • 53333, for the REST API

A critical point here is the address by which the agent reaches the manager.
When the agent is being configured, one of the configured elements is the IP address by which the agent is supposed to contact the manager. Unless special configuration is done, that IP address will be the manager’s private IP address — exactly the same IP address that had been given to the private_ip input during bootstrap. That would require that the agent’s networking environment is configured with routable traffic to the manager. In the case when the manager’s private IP and the agent’s private IP are on the same subnet, this is not a problem because traffic from the agent can reach the manager with no problem; however, in a multi-cloud environment, or in an environment when the manager’s private IP address is not routable from the remote VM, additional configuration is necessary.
This is accomplished by defining management networks. See Multiple Management Networks Support for more information.

The remote Installation Method

The oldest, and the default, method for agent installation is the remote method. In this method, agent installation is performed as follows:

  1. The manager connects to the remote machine (via SSH for Linux, or via plain-text WinRM for Windows)
  2. The agent download script is uploaded to the remote machine, and then executed.
    1. Remember: this script runs on the remote machine. It access the manager’s file server for obtaining the agent installation package.
  3. The agent installation script is uploaded to the remote machine, and then executed.
  4. The agent is now installed and configured.


        user: <agent-user>
        key_filename: <path-to-private-key>


  • This method requires SSH (Linux) or unencrypted WinRM (Windows) available on the remote VM.
    • In most default Windows images, WinRM is turned off by default. To enable it, you will need to inject some userdata (or equivalent, depending on your IaaS). You can get a sample script from the official documentation site:
  • The remote VM must be associated with a keypair.
  • The manager must have access to the private key of the keypair associated with the remote VM.
  • The value of the user sub-property is used not only for identifying the user that will be running the agent’s service, but also the user account with which the manager will connect to the remote VM for installing the agent.
  • By default, the IP address used by the manager to connect to the remote machine, is the IP address received from the IaaS plugin after creating the VM — which is the VM’s private IP. Therefore, the manager must have routable access to the remote VM.

The init_script Installation Method

This method is relatively new. It is not the default installation method, but it is the preferred one.
In this method, the manager doesn’t require SSH or WinRM access to the remote VM. This greatly simplifies agent installation in multi-cloud environments, as there is no requirement to set up privately routable access from the manager to the agent (agent → manager access is still required).

  1. The manager injects the agent’s download and configuration scripts into the VM’s startup script sequence.
    1. The specifics of how this is done depends on the IaaS plugin.
  2. During startup, the VM ends up executing the manager’s download and configuration scripts.
  3. The agent is now installed and configured.


        install_method: init_script
        user: <agent-user>


  • The remote VM does not need to be associated with a keypair.
  • The manager does not need to have access to the private key of the keypair associated with the remote VM (if any).
  • Currently, this method is supported through the following IaaS plugins:
    • OpenStack
    • AWS
    • GCP
    • Azure


    Back to top