Bug 849750 - [doc] Clarify agent removal paths
[doc] Clarify agent removal paths
Product: JBoss Operations Network
Classification: JBoss
Component: Documentation (Show other bugs)
JON 3.1.0
Unspecified Unspecified
unspecified Severity high
: CR01
: JON 3.1.1
Assigned To: Deon Ballard
Mike Foley
Depends On:
  Show dependency treegraph
Reported: 2012-08-20 14:42 EDT by Deon Ballard
Modified: 2013-09-11 06:58 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2013-09-11 06:58:06 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description Deon Ballard 2012-08-20 14:42:03 EDT
Right now there is no "clean" way to remove an agent in certain circumstances. If an agent is configured, but nothing is imported, then the discovery queue is not cleared out if the agent is subsequently deleted. Also, if an agent is created and then removed, it is difficult to re-create the agent properly; there can be conflicts because of a missing security token or naming conflicts.

This is tangential to bug 828904, but that bug shows the related question of a ghost discovery queue.

So, there needs to be a better procedure described for (1) removing an agent from the topology and (2) restoring an agent.

Affected doc:
* Install guide: https://access.redhat.com/knowledge/docs/en-US/JBoss_Operations_Network/3.1/html/Installation_Guide/uninstall.html#uninstall-agent
* FAQ: https://access.redhat.com/knowledge/docs/en-US/JBoss_Operations_Network/3.1/html/Frequently_Asked_Questions/index.html#qa29 (and possibly others) 
* Server/agent guide: https://access.redhat.com/knowledge/docs/en-US/JBoss_Operations_Network/3.1/html/Admin_Configuring_JON_Servers_and_Agents/agent-config.html#registering-agent

Details for the docs:
There are two paths that can be taken, and they are mutually exclusive.

P A T H   # 1
* the agent persisted config should be purged
* the agent's inventory should be purged
* the agent / platform has been removed from the JON inventory

Use --fullcleanconfig to force the agent to reconfigure itself and re-register with the server.

Potential error:
* If the agent is still in the inventory, this fails with an invalid security token.

P A T H   # 2
* the agent persisted config should be purged
* the agent's inventory should NOT be purged
* the agent / platform REMAINS IN the JON inventory
* the agent name remains the same

Use --cleanconfig to force the agent to reconfigure itself and re-register with the server.

Potential error:
* If the agent name changes (like, a re-install that doesn't use the default), it fails because the security token is validated against the agent's name.

R E C O M M E N D E D   C H A N G E S
1. Update the "uninstall an agent" section so that the agent can be uninstalled cleanly.

2. Update all FAQs that deal with reconfiguring an agent.

3. Expand both the agent install section (install guide) and agent re-registration section (server/agent guide) to better describe the two different re-registration paths.
Comment 1 Larry O'Leary 2012-08-20 15:01:56 EDT
For the scenario mentioned in PATH #1:

The user must:
1.  Confirm the agent that is to be removed has been shutdown
    Failure to do this may result in the agent being re-registered or its inventory being re-discovered while performing the following steps.

2.  If the platform for this agent has not yet been added to inventory, do so
    This is necessary because in order to remove the agent from the JON server's agent topology, the platform must be removed from inventory. It is the action of removing the platform from inventory which de-registers the agent and removes it from the topology.

3.  From the inventory page, locate the platform managed by this agent, and remove it from inventory
    It is this action that actually removes the agent from the JON server's agent topology.

4.  Re-install the agent using the --fullcleanconfig command-line argument 
    This is required even if the agent installer has been re-executed or the agent has been installed in a new directory. This ensures that the previous agent's configuration and its security token are discarded from the persisted Java Preferences stored within the user's account.
    This also relates to the "Potential error" mentioned it the PATH #1.
Comment 2 John Sanda 2012-08-29 21:44:18 EDT
The CR1 build is available at
https://brewweb.devel.redhat.com/buildinfo?buildID=231258. Moving to ON_QA.

Note You need to log in before you can comment on or make changes to this bug.