HostManager Agent

The HostManager Agent helps to manage the many Agent instances that need to run on a single host machine, providing a way to start and stop Agents without connecting to the host system.

For a complete discussion of this Agent and how to best use it, see Centralized Management.

usage: agent.py [-h] [--initial-state {up,down}]
                [--docker-compose DOCKER_COMPOSE]
                [--docker-service-prefix DOCKER_SERVICE_PREFIX]
                [--docker-compose-bin DOCKER_COMPOSE_BIN] [--quiet]

Agent Options

--initial-state

Possible choices: up, down

Force a single target state for all agents, on start-up.

--docker-compose

Comma-separated list of docker-compose files to parse and manage.

--docker-service-prefix

Prefix, to be used in combination with instance-id, for recognizing docker services that correspond to entries in site config.

Default: “ocs-”

--docker-compose-bin

Path to docker-compose binary. This will be interpreted as a path relative to current working directory. If not specified, will try to use which docker-compose.

--quiet

Suppress output to stdout/stderr.

Default: False

Configuration File Examples

Note that the HostManager Agent usually runs on the native system, and not in a Docker container. (If you did set up a HostManager in a Docker container, it would only be able to start/stop agents within that container.)

OCS Site Config

Here’s an example configuration block:

{'agent-class': 'HostManager',
 'instance-id': 'hm-mydaqhost1'}

By convention, the HostManager responsible for host <hostname> should be given instance-id hm-<hostname>.

Description

Please see Centralized Management.

Agent API

class ocs.agents.host_manager.agent.HostManager(agent, docker_composes=[], docker_service_prefix='ocs-')[source]

This Agent is used to start and stop OCS-relevant services on a particular host. If the HostManager is launched automatically when a system boots, it can then be used to start up the rest of OCS on that host (either automatically or on request).

manager(requests=[], reload_config=True)[source]

Process - The “manager” Process maintains a list of child Agents for which it is responsible. In response to requests from a client, the Process will launch or terminate child Agents.

Parameters:

requests (list) – List of agent instance target state requests; e.g. [(‘instance1’, ‘down’)]. See description in update() Task.
reload_config (bool) – When starting up, discard any cached database of tracked agents and rescan the Site Config File. This is mostly for debugging.

Notes

If an Agent process exits unexpectedly, it will be relaunched within a few seconds.

When this Process is started (or restarted), the list of tracked agents and their status is completely reset, and the Site Config File is read in.

Once this process is running, the target states for managed Agents can be manipulated through the update() task.

Note that when a stop is requested on this Process, all managed Agents will be moved to the “down” state and an attempt will be made to terminate them before the Process exits.

The session.data is a dict, and entry ‘child_states’ contains a list with the managed Agent statuses. For example:

{'child_states': [
  {'next_action': 'up',
   'target_state': 'up',
   'stability': 1.0,
   'agent_class': 'Lakeshore372Agent',
   'instance_id': 'thermo1'},
  {'next_action': 'down',
   'target_state': 'down',
   'stability': 1.0,
   'agent_class': 'ACUAgent',
   'instance_id': 'acu-1'},
  {'next_action': 'up',
   'target_state': 'up',
   'stability': 1.0,
   'agent_class': 'FakeDataAgent[d]',
   'instance_id': 'faker6'},
  ],
}

If you are looking for the “current state”, it’s called “next_action” here.

The agent_class may include a suffix [d] or [d?], indicating that the agent is configured to run within a docker container. (The question mark indicates that the HostManager cannot actually identify the docker-compose service associated with the agent description in the SCF.)

update(requests=[], reload_config=False)[source]

Task - Update the target state for any subset of the managed agent instances. Optionally, trigger a full reload of the Site Config File first.

Parameters:

requests (list) – Default is []. Each entry must be a tuple of the form (instance_id, target_state). The instance_id must be a string that matches an item in the current list of tracked agent instances, or be the string ‘all’, which will match all items being tracked. The target_state must be ‘up’ or ‘down’.
reload_config (bool) – Default is False. If True, the site config file and docker-compose files are reparsed in order to (re-)populate the database of child Agent instances.

Examples

update(requests=[('thermo1', 'down')])
update(requests=[('all', 'up')])
update(reload_config=True)

Notes

Starting and stopping agent instances is handled by the manager() Process; if that Process is not running then no action is taken by this Task and it will exit with an error.

The entries in the requests list are processed in order. For example, if the requests were [(‘all’, ‘up’), (‘data1’, ‘down’)]. This would result in setting all known children to have target_state “up”, except for “data1” which would be given target state of “down”.

If reload_config is True, the Site Config File will be reloaded (as described in _reload_config()) before any of the requests are processed.

Managed docker-compose.yaml files are reparsed, continously, by the manager process – no specific action is taken with those in this Task. Note that adding/changing the list of docker-compose.yaml files requires restarting the agent.

Supporting APIs

HostManager._reload_config(session)[source]

This helper function is called by both the manager Process at startup, and the update Task.

The Site Config File is parsed and used to update the internal database of child instances. Any previously unknown child Agent is added to the internal tracking database, and assigned whatever target state is specified for that instance. Any previously known child Agent instance is not modified.

If any child Agent instances in the internal database appear to have been removed from the SCF, then they are set to have target_state “down” and will be deleted from the database when that state is reached.