Centralized Agent Upgrade Process

As of version 12 of the Automation Engine it is possible to upgrade all CAU-supported agents to a new version with a centralized and easy to use automatic procedure.
In this document you find the background information, requirements and steps you have to follow.

Our consultants are experts in upgrading AE systems. Contact Automic, our experts will be pleased to assist you whenever it is necessary.

In order to print the whole contents of the collapsed pages below, use the button Expand all/Collapse all in the menu bar above.

Centralized Agent Upgrade - Video

The Centralized Agent Upgrade is very secure and easy to do, watch our video here:

https://youtu.be/896wvguA9B8

General Information

ClosedUpgrade Overview

Concept

The Centralized Agent Upgrade (CAU) as of AWA v12 is another automatic upgrade solution:

Procedure Summary

ClosedPreliminary Notes

You have to import the new version binaries into the system client 0000. (The binaries are attached to and delivered with Storage objects).

The CAU itself can be carried out from any client of your system, by any user with the necessary authorizations.

Please refer to the list of CAU enabled agents below to check, if a particular agent or agent can be upgraded by using the CAU.

In order for the CAU to work properly you also have to first manually upgrade your ServiceManager to v12 .

Upgrade Preparation

ClosedSupported Agents

As of v12 the following agents can be upgraded by using the CAU:

Agent type Agent
OS Agents

Windows

UNIX:

  • AIX

  • HPUX

  • LINUX

  • SOLARIS

  • ZLINUX

ClosedPrerequisites

Dos and Donts

Make sure that all binaries attached to Storage objects and thus imported into the system are from trusted sources.
Users that have the privilege to conduct a CAU are potentially able to import malicious files as well.

Use the ServiceManager to start agents for the CAU. That way you make sure that the agents after upgrading will restart automatically.
Using a different method to start agents is possible, but you will have to ensure the restart another way as well, because the agents will not restart automatically.

The Storage objects mentioned above will be delivered via Automic Plugin Manager packages.

Automic strongly recommends you use separate binaries for agents, not shared ones. Otherwise errors may occur.

Do not change the names of these objects. The specific name pattern is used to identify the resources' types and versions.
If the names of these objects do not match the pattern, the agent version is not displayed in the update list.

Do not change the resource content.
It is released by Automic and shouldn't be altered.

Take care of the following:

  1. Automation Engine Installation
  2. The Automation Engine installation has to be installed and / or upgraded (ZDU) in the usual way.

  3. ServiceManager Version
  4. Make sure that you upgrade your ServiceManager to v12 manually first.
    The CAU is possible as of v12, which applies to the ServiceManager as well.

  5. Initial Agent Installation
  6. You have to install an (initial) agent manually in the following cases:

    • There is no agent installed. This constitutes not an upgrade, but the very first installation.
    • There is already an agent installed but it doesn't support CAU.
      The upgrade to v12 has to be done manually, before CAU can be used to upgrade automatically to subsequent versions.
    • You want to do a manual installation for any reasons.
      Automic strongly recommends not to use manual and automated CAU steps at the same time, as errors may occur.
  7. Agent upgrade via CAU - Storage Objects
  8. An agent has already been installed that supports CAU functionality (see table above).

    • The corresponding Storage objects are already available in the Automation Engine:
      Storage object(s) that contain(s) resources of the desired target version, imported to client 0000.
      After a successful import of such a Storage object this new target version is instantly available for the CAU.
    • A Storage object that contains resources of the current version.
      This is necessary in order to be able to revert to the previous version (in effect an 'upgrade' to that version).
  9. Set User Privilege
  10. Any administrator / user who shall be able to execute an upgrade, CAU or ZDU, needs the privilege Execute system upgrades.

  11. Install the Automic Plugin Manager
  12. In order to be able to import the resource packages mentioned above you need to install the Automic Plugin Manager. It is itself a plugin and would be part of your Automic Web Interface installation.

    Details you find in: Installing and Configuring the Plugin

  13. Install the downloaded Packages using the Packs page
  14. Install the packages (packs) you downloaded using the Packs page in your AWI installation. For details refer to: Packs Page

Upgrade

ClosedUpgrade Procedure

Summary of Steps to Take

As a system administrator working in client 0000 you have to follow these steps:

  1. Download the PM package for the CAU for the desired agent version you want to upgrade to.
  2. Import the PM package into client 0000.
  3. Filter and multi-select all agents to be upgraded in the Agents page of the Administration perspective.
  4. Select the context menu item Upgrade for these agents and specify the desired agent target version.
  5. Look up the CAU related statistics / reports for details if needed, in the Upgrade History page.
  6. Refresh the Agents page to check:
    Successfully upgraded agents will be listed with their new version.

 

Detailed Upgrade Steps

ClosedI. and II. Download and Import Plugin Manager Packages for CAU

The necessary agent resources for the CAU are kept in storage objects (AE object type = STORE).
Therefore you have to make these objects available in the AE before performing CAU actions.

The delivery of these objects is realized via Automic Plugin Manager packages.
These packages are available for each released agent version on the Automic Marketplace.

In case a reversion of the CAU is a possibility, make sure to also import packages for the version you are upgrading from.

To import PM packages for CAU follow these steps:

  1. Download the Plugin Manager package for CAU for the desired target agent version from the Automic Marketplace.
  2. Logon to AWI in client 0000.
  3. Navigate to the Packs view in the Administration perspective.
  4. Import the Plugin Manager package downloaded previously.
  5. Click on Replace, if needed.
    The old version will not be overwritten by Replace, the new agent version will just be added to the already available ones.
  6. After the Plugin Manager package was successfully imported, the new agent target version is available for the CAU.

 Important Notes:

Removing a Plugin Manager package via Plugin Manager plugin will not remove already available agent target versions for CAU.
The versions of all imported packages are accumulated in the AE.

Do not change the names and / or content of Plugin Manager packages or related Storage objects.

If the agent is busy at the time the Automation Engine tries to trigger the upgrade, the agent blocks the upgrade until it is idle again (for example Job objects, script functions or file transfers).

ClosedIII. and IV. Select Agents to be Upgraded and Specify Version

Please follow these steps:

  1. Log in to any client of the system using AWI. (You need the respective permissions to display the Administration perspective.)
  2. Navigate to the Administration perspective.
  3. Click Agents & Groups, then click Agents. In the Agents page select one or more agents you want to upgrade to the new version.
    From the context menu, select Agent Upgrade.

  4. You can also filter for particular agents, using the button Filter in the toolbar at the right hand side of the Agents page.

  5. In the following dialog, if the import of Plugin Manager packages was successful, you can find a list of the new versions of agents you can upgrade to:


    In this image an SQL agent has been selected for upgrade and therefore is listed, but since it is not yet supported by the CAU, a manual upgrade is required.

    The table columns display the following information:
  6. Column Description
    Number of Agents Number of all agents available for the platform in the second column.
    Platform The respective platform of the agents you selected in the Agents page.
    Target Version

    The target versions available for that agent type, ordered in descending order, so the latest version is shown at the top.

    If there is more than one version available for that platform, a drop down arrow at the end of the row indicates that you can select the appropriate version there.

  7. If desired, enter a custom upgrade text in the field below the list. This text will be part of the related CAU statistic record name.
  8. Select the appropriate option, Agents with ServieManager Link Only or All Selected Agents.
    Difference:
    The option Agents with ServieManager Link Only starts the upgrade only for agents that have been started via ServiceManager.
    The option All Selected Agents starts the upgrade of all agents you selected in the previous dialog, if they are CAU compatible, regardless of a link to the ServiceManager.
    If none of the selected agents is linked to the ServiceManager, the option Agents with ServieManager Link Only will be hidden.
  9. Click Upgrade, if you are ready to perform the upgrade.
    Afterward a dialog will pop up showing a message regarding the upgrade status for all selected agents per platform:


    This dialog is just an information about the start of the upgrade.
    For detailed reports refer to the Upgrade History page (see steps V. and VI. below).

ClosedV. and VI. Check Reports and Upgrade History

Immediately after the upgrade has been started, you can look up any detailed information and reports in the Upgrade History page.

  1. Still in the Administration perspective, select the Upgrade History page in Agents & Groups.
    This page will be empty, displaying a message to that effect, if no upgrades have been started or run yet.
  2. In the Upgrade History page you can see a list of all agents that are currently being upgraded or whose upgrades have recently finished.
    In addition their status is displayed, for example Waiting for host. This means, the agent is busy so the upgrade has been postponed to wait for the agent to become available.
    Example of the Upgrade History page display:




    Initially only the upgrade runs as a whole are visible.
    Use the arrow icon at the left of each row to expand the display to the child/children (agent or agents individual deployment) of an upgrade run.
    Table details: See below.
  3. Use the context menu of any of the displayed agents and its option Open Report, which in turn will open the detailed report of that agent's upgrade.

    The Upgrade History table shows the following information:
  4. Column Description
    Name Name of the CAU run, can be configured in the Custom Upgrade Text field when you select the target version.
    Status Status of the run - or the child, which would be an agent or agents individual deployment, depending on the selection you made when choosing the agents to be upgraded.
    RundID RunID of the CAU run or the individual agent deployment.
    Parent (only filled, if child is displayed) Shows the CAU run which is parent of an individual agent's deployment.
    User User name of the user executing the CAU.
    Agent (only filled, if child is displayed) Agent name of the individual agent being upgraded.
    Target Version New version to be upgraded to.
    Start Time/End Time Start and end time of the run or the individual agent upgrade.
    Runtime The upgrade's duration.

ClosedExecute Objects on Upgrade

You can configure the necessary AE system modules to execute objects on the CAU's completion automatically.

You have to be logged in into system client 0000 to be able to configure the necessary variables and keys.

ClosedExecute on Upgrade - Configuration

In order to configure the automatic execution of objects after the CAU has been completed, the system variables UC_HOSTCHAR_DEFAULT - Host Characteristics and - for a particular agent - the UC_EX_HOSTCHAR - Assigning Agents to Host Characteristics variable have to be edited or created.

You first have to create the object or objects to be executed after the upgrade has been finished.
Afterward you set the values in the respective UC_HOSTCHAR_DEFAULT key, following these steps:

  1. In the Process Assembly perspective find the HOST_VARIABLES folder. The system variable UC_HOSTCHAR_DEFAULT is located inside it. Double click the variable to open and edit it.
  2. In the Variable page you will see a list of keys you can edit.
    Find the keys EXECUTE_ON_DEPLOYMENT_RUN and EXECUTE _ON_DEPLOYMENT_AGENT.
    • If you want to execute an object of your choice after the entire deployment run has been finished, use EXECUTE_ON_DEPLOYMENT_RUN.
    • If you want to execute an object of your choice after a particular agent upgrade has been finished, use EXECUTE_ON_DEPLOYMENT_AGENT.
  3. This step applies to both keys:
    On the right hand side in the table use the column Value 1 to enter the name of the object that should be executed after the upgrade.
    In case you want to execute more than one object, use the object defined here in the necessary Automation Engine setup to trigger consecutive object executions.
  4. Save the system variable.

In order to read or print the report contents of CAU runs, you can use script functions and available script variables. Find examples here:

ClosedUsing Scripts and Script Variables

Available Script Variables

There are script variables available that you can use in scripts in the Process page of an object you referenced to read the respective values, namely:

Use with EXECUTE_ON_DEPLOYMENT_RUN, so the variables listed will return the values as described here:

  • &UC_EX_CAU_NAME# - Custom text of agent upgrade
  • &UC_EX_CAU_RUNID#  - Top statistics RunId of deployment
  • &UC_EX_CAU_STATUS#  -  Status of whole CAU run (it can be ENDED_OK or ENDED_NOT_OK)

Use with EXECUTE_ON_DEPLOYMENT_AGENT, which will return the following values:

  • &UC_EX_HOST# - Agent / host name. (For compatibility reasons the variable name without "#" works as well here.)
  • &UC_EX_CAU_NAME#  - Custom text of an agent upgrade run.
  • &UC_EX_DEPLOYMENT_RUNID#  - RunId of a child / agent upgrade
  • &UC_EX_DEPLOYMENT_STATUS#  - Status (number) of child / agent upgrade
  • &UC_EX_CAU_RUNID#  - Top statistics RunId of deployment

Script Examples:

This script reads all variables from the read buffer and uses / prints them (single agent deployment):

:READ &UC_EX_CAU_NAME#,,
:READ &UC_EX_CAU_RUNID#,,
:READ &UC_EX_HOST#,,
:READ &UC_EX_DEPLOYMENT_RUNID#,,
:READ &UC_EX_DEPLOYMENT_STATUS#,,

 

:P "CAU RUN INFORMATION:"
:P "CAU custom text=",&UC_EX_CAU_NAME#
:P "CAU runID=",&UC_EX_CAU_RUNID#

 

:P "AGENT DEPLOYMENT INFORMATION:"
:P "Agent=",&UC_EX_HOST#
:P "Agent deployment runID=",&UC_EX_DEPLOYMENT_RUNID#
:P "Agent deployment status=",&UC_EX_DEPLOYMENT_STATUS#

 

Use PREP_PROCESS and this example script for a CAU report (an entire CAU run):

For a whole CAU run use "CAU" as parameter report type in PREP_PROCESS_REPORT.

:SET &HND#=PREP_PROCESS_REPORT(,&UC_EX_DEPLOYMENT_RUNID,"CAU")

:PROCESS &HND#

:SET &RET#=GET_PROCESS_LINE(&HND#)

:PRINT &RET#

:ENDPROCESS

 

Use PREP_PROCESS and this example script for a "REP" report (single agent deployment):

For processing the detailed report of a single agent upgrade use "REP" as parameter report type in PREP_PROCESS_REPORT.

:SET &HND#=PREP_PROCESS_REPORT(,&UC_EX_DEPLOYMENT_RUNID#,"REP")

:PROCESS &HND#

:   SET &LINE#=GET_PROCESS_LINE(&HND#)

:          PRINT &LINE#

:ENDPROCESS

ClosedCleanup Trigger

Because of this cleanup function which will be triggered on the agent's re-connect, it is necessary that you provide the binaries as CAU packages of previous versions in case you want to revert the CAU. Take care to import them should they not be present in the system yet.

Skip Upgrade

ClosedSkip Upgrade

It is possible to skip the upgrade of agents that you initially registered for an upgrade, if they are in the status Waiting for host.

Two possibilities exist to skip the upgrade:

Upgrade Skip in AWI:

  1. In the web interface, navigate to the Administration perspective, as also described above and open the Upgrade History page.
  2. Find the agents which are in the status Waiting for host, choose one or more whose upgrade you want to skip.
  3. Right-click a selected agent or agents (multi-select is possible, using the STRG or SHIFT key) and from the context menu, choose Skip upgrade:


Revert to Previous Version

ClosedHow to Revert to a Previous Version

You may want to revert the agent's upgrade in case your preferences or system occurrences make it seem appropriate.
This function is technically an upgrade to another agent version.
Therefore you just have to follow the steps described above for the CAU itself.

What you have to do

Background Information

ClosedSystem Behavior during a Centralized Agent Upgrade (CAU)