Using uninventory_deleted JBoss ON CLI script to permanently remove deleted resources from inventory

Updated

This article explains how and why to use the Red Hat JBoss Operations Network (ON) 3.3 uninventory_deleted utility.

Table of Contents

Some resource types in JBoss ON inventory support the DELETE inventory operation. This operation will typically remove the physical deployment or component from its parent resource and mark its inventory status as DELETED. Because the resource is not actually removed from inventory, all of its history, connection settings, alert definitions, and all other related content can later be restored if the resource is ever redeployed.

In some instances, you may want the resource to be completely removed from inventory in addition to being undeployed. Because the resource is in a deleted state, it is no longer available in the user-interface (UI) and therefore, the only way to permanently remove the deleted resource is by using the JBoss ON Remote API or Command-Line Interface (CLI).

JBoss ON 3.3 Update-08 (3.3.8) includes the uninventory_deleted.js JBoss ON CLI script which can be used to list and permanently remove resources that are in a deleted state.

Why is the uninventory_deleted utility needed?

When the DELETE inventory operation is performed on a resource, the resource is not actually removed from the JBoss ON system. Only the physical deployment or component the resource represents is removed or undeployed.

For example, if you have a WAR deployed to a JBoss EAP 6 standalone server and invoke the delete inventory operation on the resource that represents the WAR, a undeploy request is sent to the WAR's JBoss EAP server. If the undeploy request is successful, the resource that represents the WAR gets its inventory status changed from COMMITTED to DELETED. The resource's associated data such as metrics, alerts, operation history, the actual binary data file of the WAR, and various configurations and configuration histories will remain in the JBoss ON system.

The only noticeable changes in the JBoss ON system when a resource is deleted include

  • The resource will no longer appear in the inventory pages of the JBoss ON user-interface (UI).
  • The resource's managing agent will no longer perform management or monitoring tasks for the resource.

Because the resource's data remains, you can later redeploy the resource and its associated data will once again become available in the UI. However, if you do not want the data to remain, you will need to use the This content is not included.ResourceManager.uninventoryResources(resourceIds[]) remote API call to permanently remove the resource.

The uninventory_deleted utility makes locating and performing the ResourceManager.uninventoryResources(resourceIds[]) operation easier.

When should I use the uninventory_deleted utility?

If a resource has been deleted from inventory, all of its associated data and content will remain in the JBoss ON server's data store. If you know that you want all previous history and knowledge of the resource to go away, you will want to use the uninventory_deleted utility to locate and then permanently remove the deleted resources.

Where do I get the uninventory_deleted utility?

Beginning with JBoss ON 3.3 Update-08 (3.3.8), the utility is available in the misc/uninventory_deleted directory of the update archive. For example:

unzip jon-server-3.3-update-08.zip -d /tmp
ls /tmp/jon-server-3.3.0.GA-update-08/misc/uninventory_deleted

How do I use the uninventory_deleted utility?

Using the uninventory_deleted utility to permanently remove resources requires that you know the identifiers or ids of the resources that should be removed. In addition to providing the remove functionality, the utility also provides a list command that will provide you with details regarding which resources in the JBoss ON system are in the deleted state.

WARNING: Once a resource has been removed, its history and all related content, including its child resources and their history will be lost. The only way to undo the process is to restore the entire JBoss ON database from a backup.

Prerequisites

  • The uninventory_deleted utility will require access to the JBoss ON Command-Line Interface (CLI). If you have not already installed the CLI, see Installing The JBoss ON CLI for instructions on where to obtain the CLI and how to perform the installation.

  • The complete path to where JBoss ON (CLI) is installed. For example, /opt/jboss/on/rhq-remoting-cli.

    For the purpose of this guide, this path will be referred to as $JON_CLI_HOME.

      JON_CLI_HOME="/opt/jboss/on/rhq-remoting-cli"

  • The complete path to the uninventory_deleted.js script. For example, /tmp/jon-server-3.3.0.GA-update-08/misc/uninventory_deleted/uninventory_deleted.js.

    For the purpose of this guide, this path will be referred to as $JON_CLI_SCRIPT.

      JON_CLI_SCRIPT="/tmp/jon-server-3.3.0.GA-update-08/misc/uninventory_deleted/uninventory_deleted.js"

  • The JBoss ON server's host name or IP address and port number. For example, jboss-on.example.com on port 7080. This will normally be the same host and port used from your web browser.

    For the purpose of this guide, the server host name and port will be referred to as $JON_HOST and $JON_PORT respectively.

      JON_HOST=jboss-on.example.com
  JON_PORT=7080

  • The user name and password for a JBoss ON user who has the superuser role. For example, rhqadmin. This could be any user, who is assigned any role that includes the Manage Security permission, such as the role Super User Role.

    For the purpose of this guide, the user name and password will be referred to as $JON_USER and $JON_PASSWORD respectively.

      JON_USER=myusername
  JON_PASSWORD=mysecretpassword

Basic usage

Use the JBoss ON CLI to execute the uninventory_deleted.js CLI script passing it a command and any necessary options.

"$JON_CLI_HOME"/bin/rhq-cli.sh -u "$JON_USER" -p "$JON_PASSWORD" -s "$JON_HOST" -t "$JON_PORT" -f "$JON_CLI_SCRIPT" <COMMAND> <OPTIONS>

Listing deleted resources

To determine which resources are in a deleted state and eligible for permanent removal, you can execute the uninventory_deleted.js CLI script without any arguments.

"$JON_CLI_HOME"/bin/rhq-cli.sh -u "$JON_USER" -p "$JON_PASSWORD" -s "$JON_HOST" -t "$JON_PORT" -f "$JON_CLI_SCRIPT"

This will output a list in a comma-separated value (CSV) format.

Login successful
Found [2] deleted resources, processing...
resource_id, resource_name, resource_ancestry
10250,my-application.ear, 10624_:_10112_:_EAP 7 (127.0.0.1:19990)_::_10003_:_10001_:_avalanche
10252,my-other-app.ear, 10624_:_10112_:_EAP 7 (127.0.0.1:19990)_::_10003_:_10001_:_avalanche

If you do not want the list printed to the screen, you can use the list command followed by a file name to have it written to a file.

"$JON_CLI_HOME"/bin/rhq-cli.sh -u "$JON_USER" -p "$JON_PASSWORD" -s "$JON_HOST" -t "$JON_PORT" -f "$JON_CLI_SCRIPT" list myfile.csv

Each row of the output will represent a resource, which is in the deleted state. The columns from each row are

  • resource_id is the numeric resource identifier that will be required when performing the remove operation.
  • resource_name is the name of the resource as it originally appeared in inventory. This is for reference only and will assist you in finding specific resources that you would like to permanently remove.
  • resource_ancestry is the parent and grand-parent hierarchy of the resource. This is for reference only and provides the resource's lineage to more uniquely identify the resource's location within inventory.

If you see any resources that you would like to permanently remove, you should make note of their resource ids from the first column of the output.

In the example output, there are two resources that had previously been deleted. One named my-application.ear with the resource id of 10250 and the other with the name my-other-app.ear with the resource id of 10252.

Permanently removing deleted resources

Once you have determined which resources should be permanently removed and retrieved their resource id using the list command, you can use the uninventory command, passing it one or more ids to be permanently removed. For example, if we want to remove my-application.ear, we will need to pass its resource id of 10250 to the uninventory command.

"$JON_CLI_HOME"/bin/rhq-cli.sh -u "$JON_USER" -p "$JON_PASSWORD" -s "$JON_HOST" -t "$JON_PORT" -f "$JON_CLI_SCRIPT" uninventory 10250

As the command is executed, status information is displayed. For example

Querying [1] resources to determine their current status.
Sent UNINVENTORY request to JBoss ON Server for [1] resources. [0] resources remaining.
Completed processing...

You can also pass multiple resource ids to the uninventory command in the form of a space separated list. For example, if you wanted to permanently remove both my-application.ear and my-other-app.ear, we would pass both resource ids to the uninventory command.

"$JON_CLI_HOME"/bin/rhq-cli.sh -u "$JON_USER" -p "$JON_PASSWORD" -s "$JON_HOST" -t "$JON_PORT" -f "$JON_CLI_SCRIPT" uninventory 10250 10252

Finally, if you want to remove all resources, which are in the deleted state, you can use the i-am-sure-to-uninventory-all-deleted-resources command. Remember, this operation cannot be undone. If you decide to use this command, you should be absolutely positive that all resources in a deleted state should be permanently removed from the system.

Getting help

Usage information can be displayed by invoking uninventory_deleted.js with the help command.

"$JON_CLI_HOME"/bin/rhq-cli.sh -u "$JON_USER" -p "$JON_PASSWORD" -s "$JON_HOST" -t "$JON_PORT" -f "$JON_CLI_SCRIPT" help

If anything is unclear or if you need additional assistance, please This content is not included.create a support case.

Product(s)
Category
Tags
Article Type