Jump to: navigation, search


Unified Guest Agent

Agent is a piece of python software installed on Glance image. It should be configured to start on instance boot. After start it listens and executes controller commands inside guest (instance). It can:

  • execute a shell command on a guest
  • move file to/from guest
  • send http request from the guest to designated host/port
  • perform the operations above in both 'call' and 'cast' manner
    • The 'call' and 'cast' differ in that 'call' invocation returns when the operation is completed and it also can return the result of the operation. 'cast' invocation acts in 'fire and forget' manner - it returns once the operation is started.


The supposed audience/contributors are projects which need to do something inside VM while cloud-init is not sufficient for that. That includes: multi-step software installation, reconfiguration on scaling/demand, passing through user commands, etc.

The initiative has two targets:

  • encourage guest code reuse across projects.
  • simplify OpenStack deployment by using the same transport for agent across several projects.

People from the following projects might be interested: Heat, Savanna, Trove, Murano and Solum.


Guest Agent Architecture.svg

Key architectural features are:

  • Support for different Guest OSes
  • Support for different Transports
    • hardware-deployed MQ / Marconi MQ / http / ssh / what else?
  • Parts of API reusable across different projects.
    • The intent is not to provide a single API for all the projects, but rather a set of building blocks of which API could be composed. That way the agent size could be kept small + it allows adding domain-specific API as a separate 'block'.

Task of the transport is to provide means to securely pass messages from controller to the guest and vice versa. The need to support various transport arises from diversity of OpenStack deployments and requirements. Different transports provide different capabilities and lay different requirements on the cloud. It is better seen in examples:

  • hardware-deployed MQ requires cloud to have a queue servers accessible both from controller and VMs.
  • Marconi MQ requires Marconi to be deployed in the cloud, while it is not widely adopted yet.
  • http requires an http endpoint to be deployed and accessible by VMs. The agent can poll the endpoint for tasks. 'Call' operations require the endpoint to accept data from the VMs (sent by POST requests?).
  • ssh is a special case. It does not need an agent on the guest, instead the lib will invoke commands on the guest via ssh. But it requires direct access from controller to guest VMs, which is not always the case.

(devdatta-kulkarni: this option may run into scalability issues on the controller side.)


A number of conversations happened since that original proposal:

- http://lists.openstack.org/pipermail/openstack-dev/2013-December/021476.html

Many people expressed expressed their opinion, but no consensus was reached.The following etherpad tries to summarize proposed options: https://etherpad.openstack.org/p/UnifiedGuestAgent

- http://lists.openstack.org/pipermail/openstack-dev/2014-January/024968.html

An announcement about PoC of os_collect_config migrated to oslo.messaging

- http://lists.openstack.org/pipermail/openstack-dev/2014-March/029194.html

The discussion revealed that many people find oslo.messaging not suitable for agent transport, since it is really hard to provide adequate tenant isolation with it. At the same time Marconi does provide that out of the box.