CAU - Upgrade Procedure
As a system administrator working in client 0000 you use CAU to upgrade the agents.
This page includes the following:
The steps to follow are:
Download the PM package for the CAU for the desired agent version you want to upgrade to.
Import the PM package into client 0000.
Filter and multi-select all agents to be upgraded in the Agents page of the Administration perspective. Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.
Select the context menu item Upgrade for these agents and specify the desired agent target version.
Look up the CAU related statistics / reports for more information, in the Upgrade History page.
Refresh the Agents page to check:
Successfully upgraded agents will be listed with their new version.
Downloading and Importing 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.
You can get these objects via Plugin Manager packages, which are available for each released agent version on https://marketplace.automic.com/.
To import CAU pack versions older than the installed ones, make sure you delete the current CAU pack version first.
Make sure you also download Packs for the version from which you are upgrading, just in case you need to revert to it.
To Import PM Packages for CAU
- Download the Plugin Manager package for CAU for the desired target agent version from https://marketplace.automic.com/.
- Logon to AWI in client 0000.
- Navigate to the Packs view in the Administration perspective.
- Import the Plugin Manager package downloaded previously.
- Click on Replace, if needed.
- After the Plugin Manager package was successfully imported, the new agent target version is available for the CAU.
- Removing a Plugin Manager package via Plugin Manager plug-in 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).
Selecting Agents to be Upgraded and Specify Version
In the Agents page of the Administration perspective, select one or more agents you want to upgrade to the new version and select Agent Upgrade from the context menu.
Upon accessing the Agents list, the filter pane is open by default. This allows you to immediately perform a search using the Agent Name field, thus simplifying the work with the list.
If the import of Plugin Manager packages was successful, you find a list of the new versions of agents you upgrade to. The list displays the following information:
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. A dropdown arrow at the end of the row indicates that you can select the appropriate version there.
Optionally, enter a custom upgrade text in the field below the list. This text will be part of the related CAU statistic record name.
Select the appropriate option, Agents with ServiceManager Link Only or All Selected Agents.
Agents with ServiceManager Link Only starts the upgrade only for agents that have been started via Service Manager. This option guarantees that the agents are restarted after the upgrade.
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.
- Java agents: CAU is available for Java agents as of v12.3. They must be started by a Service Manager of v12.3 or later in order to be upgradeable via CAU.
- OS agents: If the agent is not started by a Service Manager, the agent will end and the binaries will be upgraded, but it cannot start automatically after the process. Upgrade statistics records will remain active until the agent has been started again.
If none of the selected agents is linked to the ServiceManager, the option Agents with ServiceManager Link Only is hidden.
Click Upgrade, if you are ready to perform the upgrade. A dialog displays the upgrade status for all selected agents per platforms.
For detailed reports, see Upgrade History.
Upon starting the upgrade, the Upgrade History page displays detailed information and reports. For more information, see Upgrade History.
The Upgrade History page of the Agents & Groups section in the Administration perspective displays a list of all agents that are currently being upgraded or whose upgrades have recently finished. If the page is empty, no upgrades have been started or run yet.
The status is also displayed to provide more information. For example, Waiting for host means that the agent is busy so the upgrade has been postponed to wait for the agent to become available.
The Upgrade History displays the following information:
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.
RunID: 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 and End Time: Start and end time of the run or the individual agent upgrade.
Runtime: The upgrade's duration.
The following actions are available in the context menu for agent listings.
Open Report: Opens the detailed report of that agent's upgrade.
Skip Upgrade: As long as an agent waits for an upgrade to be started (if the agent is down or still busy processing workload tasks, for example), you can use this action to skip the upgrade.
Execute Objects on Upgrade
You can configure the necessary AE system modules to execute objects on the CAU's completion automatically.
Note: You have to be logged in into system client 0000 to be able to configure the necessary variables and keys.
Execute on Upgrade - Configuration
In order to configure the automatic execution of objects after the CAU has been completed, the system variables UC_HOSTCHAR_DEFAULT and UC_EX_HOSTCHAR have to be edited or created. For more information, see UC_HOSTCHAR_DEFAULT - Host Characteristics and UC_EX_HOSTCHAR - Assigning Agents to Host Characteristics.
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:
- In the Process Assembly, find the HOST_VARIABLES folder. The system variable UC_HOSTCHAR_DEFAULT is located inside it. Double click the variable to open and edit it.
- In the Variable page you will see a list of keys you can edit.
Find the EXECUTE_ON_DEPLOYMENT_RUN and EXECUTE _ON_DEPLOYMENT_AGENT keys.
- 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.
- 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.
- 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.
Using Scripts and 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# - RunId of the CAU run (the parent of the agent upgrade)
- &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# - RunId of the CAU run (the parent of the agent upgrade)
This script reads all variables from the read buffer and uses / prints them (single agent deployment):
: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 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.
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 &LINE#=GET_PROCESS_LINE(&HND#)
: PRINT &LINE#
After the agent upgrade has run, the Automation Engine triggers a cleanup of all binaries that are now not needed anymore. This means, the agent that has been upgraded re-connects to the AE. If its target version agrees with the CAU record of the AE, the AE sends a cleanup message to the agent.
The agent then removes the binary file of the previous version from the system.
Note: 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.
Skipping the 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.
You can skip the upgrade in two different ways:
Create a script using the Script function MODIFY_SYSTEM.
In the Upgrade History page of the Agents & Groups section in the Administration perspective, find the agents with the status Waiting for host. Select and right-click the agent or agents you do not want to upgrade and and from the context menu, choose Skip upgrade.
Reverting 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.
To Revert to a Previous Version
- Import the corresponding packages into the system to make them available for reverting to a previous version.
- Select the agent version you want to revert to and finish the upgrade procedure as described.
- To check the details of the previous version, open the Upgrade History page. Follow the steps described above in Checking Reports and Upgrade History.
System Behavior during a Centralized Agent Upgrade (CAU)
When you select the Latest option for CAU, the latest upgrade resources available in AE are applied. If the agent runs already in an even newer version it is downgraded to the latest version available in the AE.
The CAU can be used to downgrade an agent as well. From a technical point of view it is an upgrade to a previous version, no source / target version checks are performed to prevent a downgrade.
The CAU can be triggered for agents that are not connected to the AE, too.
The AE remembers the desired upgrade and triggers it as soon as the agent gets connected to the AE and is available for operation.
Even for agents that have never been connected to AE (no current version info available) the upgrade can be triggered. They will be upgraded when they connect to AE for the very first time.
Agent connects with wrong target version after upgrade.
If the CAU has been already successfully performed for an agent and the agent connects to the AE with a wrong target version subsequently, the CAU is repeated.
This means, an upgrade is forced to bring the agent to the last target version that was selected in the last CAU action.
In this case in the Upgrade History of system client 0000 the entries titled "REPAIR" will show up to indicate that the agent was repaired by a forced upgrade to the desired target version.
When using cluster agents:
Agent 1 that was upgraded successfully is terminated. The redundant agent 2 starts up with the same agent name but the old version.
Consequently agent 2 will be upgraded to the same version as agent 1.
When performing CAU the AE basically triggers all selected agents to perform an upgrade. If an upgrade cannot be triggered immediately the agent remains in the status Waiting for Host regarding this upgrade.
If an agent remains in this status the pending upgrade can be skipped by the user via web interface and / or script function.
If an agent already performs the actual upgrade (downloading and replacing files, restart,...) the upgrade cannot be skipped anymore.
An agent cannot be upgraded and run agent jobs at the same time.
If an agent is busy (e.g. executing a job or a file transfer) the upgrade process is put on hold until the agent is idle again and ready to perform the upgrade.
While an agent is performing an upgrade it is suspended and tasks to be executed change to the status Waiting for Host
Script functions: Some server-side script functions request data from agents. These script functions are suspended during the agent upgrade and resumed after the upgrade is completed.
There are two different report types available in the CAU context.
CAU: AE reports triggering an upgrade for each agent, as well as the end status, or a skipped upgrade process.
DEPLOY: An agents reports all steps during an upgrade such as downloading / upgrading binary resources as well as its final termination for restart.