PDFs

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Appd tocbox

On this page:

Table of Contents
maxLevel2
minLevel2

Related pages:

To upgrade a Controller instance, you run the installer for the version of the Controller to which you want to upgrade on the Controller machine. The installer detects the Controller installation and upgrades that instance. If there is more than one Controller instance, the installer detects the last one installed.

About the Upgrade

  • You can upgrade across multiple versions at a time; that is, you do not need to run the installer individually for each intermediate version.  
  • If your existing Controller is handling your current load or you are not changing your licensing, you should not need to upgrade your hardware when upgrading the Controller. To determine if you are close to exceeding your Controller's capacity, see Controller Sizing FAQ
  • If you have a license for an older version, the license should work when upgrading the Controller to a new version. However, if you have a temporary license for the old version and now have a new license, the new license will not work on the old Controller. In this case, you should upgrade the Controller to the latest version before applying the license. 
  • An upgrade results in Controller downtime, but it is not necessary to stop agents during the Controller upgrade.
  • If you have configured settings in the domain.xml file or other configuration files manually or by using the Glassfish asadmin utility, verify those changes in the configuration files after the upgrade and re-apply any customizations that were not preserved. After the upgrade, you can find backup copies of the files in the <controller_home>/backup directory.

Upgrade Order

Perform the upgrade in the following order if you did not use the Platform Administration Application to install the Events Service:

  1. Upgrade the Events Service
  2. Upgrade the EUM Server
  3. Upgrade the Controller

Perform the upgrade in the following order if you used the Platform Administration Application to install the Events Service:

  1. Shutdown the EUM Server
  2. Upgrade the Controller
  3. Upgrade the Events Service with the application.
  4. Upgrade the EUM Server.

Note that upgrading platforms that use the Platform Administration Application results in downtime of the EUM Server.

Before Upgrading

  • Review the latest Release Notes and the release notes for any intermediate versions between the current version of your instance and the version you are targeting. 
  • Check the most recent Controller System Requirements and Controller Sizing FAQ to determine whether you need to change your performance profile.
  • Check the Controller's database.log for any errors. You can find the log at the tail of <controller_home>/logs/database.log. There should not be any InnoDB: Error lines in the log. If any errors are found, please reach out to AppDynamics Support before attempting the upgrade. Upgrading the Controller with a corrupt database may put the Controller in a bad state, with a high recovery time.
  • If you changed any Glassfish settings that are not JVM options, note your changes. You may need to configure them after upgrade. The installer recognizes and retains many common customizations to the domain.xml, db.cnf, and other configuration files but is not guaranteed to retain them all. If you made changes to the files, verify the configuration after upgrading.
  • The database user password storage mechanism changed in Release 3.8. If upgrading from 3.7.x or earlier, see the Upgrade the Controller page in the 3.8 documentation for considerations related to the database user password.
  • If upgrading from pre-4.2.1.7 to 4.2.1.7 or later, ensure you install the latest HA Toolkit from https://github.com/Appdynamics/HA-toolkit/releases/latest.

Anchor
backupcontroller
backupcontroller
Back up the Existing Controller

The installer retains agent data, reports, configuration and other types of data through an upgrade, including a copy of commonly modified configuration files under <controller_home>/backup. Nevertheless, to mitigate the risk of data loss in the event of an unexpected failure, be sure to back up the existing installation directory before applying an upgrade to the Controller.  

If the upgrade does not finish successfully, use the backup files to restore the installation to its previous state. Do not attempt to upgrade again without restoring the installation. See Troubleshooting the Upgrade for more information. 

To back up the Controller instance
  1. Stop the Controller application server and database.
    • For Linux, run: 

      No Format
      <controller_home>/bin/controller.sh stop
    • For Windows, the Controller is installed as a service. Start and stop the Controller app server, database and reporting service from the services manager. To do so, from the Services viewer in Administrative Tools, find and stop the services identified as AppDynamics services. In particular, look for and stop if running: 

      • AppDynamics Controller Application Server 

      • AppDynamics Database

      • AppDynamics Reporting Service 

  2. Back up the Controller home by copying the entire Controller home directory to a backup location. Note the following points: 
    • If the data home for the Controller is not under the Controller directory, be sure to back up the database directory as well. 
    • If it's not possible to back up the entire data set, you can selectively back up the most important tables. Use the Metadata Backup SQL script described and attached to the Controller Data Backup and Restore page. 

Upgrading the Controller

The following steps describe how to upgrade the Controller on Windows and Linux. 

You use the Controller installer in GUI mode, console mode, or silent mode to perform the upgrade. To use silent mode, pass the response file that the installer generated at first installation to the installer. You can find the response file in the following location

  •  <Controller_home_directory>/.install4j/response.varfile

If you made any changes to the settings listed in the response file—such as to the connection port numbers, tenancy mode, or data directory—make those changes in the response file before starting the upgrade. 

You must also add the existing root user password to the file, rootUserPassword and rootUserRePassword. If you do not, the installer prompts you to add the password.  

To upgrade the Controller
  1. Download the latest release from AppDynamics Download Center.
    If you prefer to use the Linux shell, see Downloading from the Linux Shell.
  2. If they are running, stop the Controller application server and database. The Controller cannot be running during the upgrade. No data is collected from the time you shut down and start the new version of the Controller.
    • For Linux, run: 

      No Format
      <controller_home>/bin/controller.sh stop
    • For Windows, the Controller is installed as a service. Start and stop the Controller app server, database and reporting service from the services manager. To do so, from the Services viewer in Administrative Tools, find and stop the services identified as AppDynamics services. In particular, look for and stop if running:  

      • AppDynamics Controller Application Server 

      • AppDynamics Database

      • AppDynamics Reporting Service  

  3. Launch the Controller installer. On Windows, be sure to start the Controller installer in an elevated command prompt.
  4. Confirm that the installation directory is the same as the previous Controller installation directory on this machine. The Controller will automatically migrate the data only when the existing installation directory is specified. Once the installer detects the old version of the Controller in that location, it will perform an upgrade instead of doing a fresh install.
    The installer completes the upgrade and restarts the Controller.
  5. If you made any manual changes to the configuration files listed, re-apply those changes to the equivalent files in the upgraded instance. The installer does not automatically propagate changes you have made to those files.
  6. Open a browser and access the AppDynamics user interface:

    No Format
    http://<Controller_Host>:<Controller_Port>/controller

    If the UI does not display the new Controller, refresh your browser cache to view the new UI. 

To upgrade a Controller in HA mode with the HA Toolkit

If you have two AppDynamics Controllers deployed in a high availability arrangement, you must upgrade both the primary and the secondary Controller.

If administering high availability with the HA toolkit, follow these steps:

  1. Download the latest release from AppDynamics Download Center.
    If you prefer to use the Linux shell, see Downloading from the Linux Shell.
  2. On the secondary Controller, stop the database process (the application server process should already be stopped):

    No Format
    /sbin/appdservice appdcontroller-db stop
  3. Stop the primary Controller application server and database. The Controller cannot be running during the upgrade. No data is collected from the time you shut down and start the new version of the Controller.
    1. For Linux, run: 

      No Format
      <controller_home>/bin/controller.sh stop
    2. For Windows, the Controller is installed as a service. Start and stop the Controller app server, database and reporting service from the services manager. To do so, from the Services viewer in Administrative Tools, find and stop the services identified as AppDynamics services. In particular, look for and stop if running:  

      • AppDynamics Controller Application Server

      • AppDynamics Database

      • AppDynamics Reporting Service

  4. Launch the Controller installer. On Windows, be sure to start the Controller installer in an elevated command prompt.
  5. Confirm that the installation directory is the same as the previous Controller installation directory on this machine. The Controller will automatically migrate the data only when the existing installation directory is specified. Once the installer detects the old version of the Controller in that location, it will perform an upgrade instead of doing a fresh install.
    The installer completes the upgrade and restarts the Controller.
  6. If you made any manual changes to the configuration files listed, re-apply those changes to the equivalent files in the upgraded instance. The installer does not automatically propagate changes you have made to those files.
  7. Open a browser and access the AppDynamics user interface:

    No Format
    http://<Controller_Host>:<Controller_Port>/controller

    If the UI does not display the new Controller, refresh your browser cache to view the new UI. 

  8. Use the replicate.sh script to propagate changes from the primary to the secondary Controller. The steps are the same as they are for setting up replication for an existing Controller described in Using the High Availability (HA) Toolkit. Since you replicate from an existing Controller, an incremental (imperfect) replication is recommended to minimize downtime. 
To upgrade a Controller in HA mode without the HA Toolkit

If you are not using the HA toolkit, follow the general steps below. It is recommended that you perform these steps in consultation with AppDynamics support:

  1. Download the latest release from AppDynamics Download Center.
    If you prefer to use the Linux shell, see Downloading from the Linux Shell.
  2. Stop the primary Controller application server and database. The Controller cannot be running during the upgrade. No data is collected from the time you shut down and start the new version of the Controller.
    • For Linux, run: 

      No Format
      <controller_home>/bin/controller.sh stop
    • For Windows, the Controller is installed as a service. Start and stop the Controller app server, database and reporting service from the services manager. To do so, from the Services viewer in Administrative Tools, find and stop the services identified as AppDynamics services. In particular, look for and stop if running:  

      • AppDynamics Controller Application Server 

      • AppDynamics Database

      • AppDynamics Reporting Service  

  3. Launch the Controller installer. On Windows, be sure to start the Controller installer in an elevated command prompt.
  4. Confirm that the installation directory is the same as the previous Controller installation directory on this machine. The Controller will automatically migrate the data only when the existing installation directory is specified. Once the installer detects the old version of the Controller in that location, it will perform an upgrade instead of doing a fresh install.
    The installer completes the upgrade and restarts the Controller.
  5. If you made any manual changes to the configuration files listed, re-apply those changes to the equivalent files in the upgraded instance. The installer does not automatically propagate changes you have made to those files.
  6. Open a browser and access the AppDynamics user interface:

    No Format
    http://<Controller_Host>:<Controller_Port>/controller

    If the UI does not display the new Controller, refresh your browser cache to view the new UI. 

  7. Verify on the secondary Controller that all the data has been replicated correctly.
    1. Open a command line utility and go to the <controller_home>/bin directory.
    2. Log into the secondary Controller database:
      • For Linux, run: 

        No Format
        controller.sh login-db
      • For Windows, run the following command in an elevated command prompt (right-click on the Command Prompt icon in the Windows Start menu and choose Run as administrator):

        No Format
        controller.bat login-db
    3. Execute following command:

      No Format
      SHOW SLAVE STATUS\G

       This step should provide you following result:

      No Format
      Seconds_Behind_Master: $Number_Of_Seconds_Behind_Master

      If you get a non-zero number for this test, wait until the number becomes zero.

  8. Perform a failover to the secondary Controller, so that the primary app server is shut down and the secondary app server is started. The commands for starting and stopping the app server are in Start or Stop the Controller.   

  9. Perform steps 1 through 7 for the secondary Controller..

  10. Shut down the secondary Controller app server and start the primary app server.  

Both the primary and secondary Controllers are now upgraded. 

Anchor
troubleshooting
troubleshooting

Troubleshooting the Upgrade

If the upgrade does not succeed, the installer does not roll back changes on disk. Diagnose and troubleshoot the issue before reattempting the installation or upgrade. 

To troubleshoot the issue, check the installation log at <controller_home>/.install4j/installation.log. You can also check temporary installer logs in the system tmp directory (on Linux: /tmp/i4j*; on Windows: %temp%\i4j*). The log files contains logs written up to the point the installation stopped. Controller log files may contain additional information. 

After diagnosing the issue, manually revert the installation back to its state prior to starting the upgrade. Replace the existing Controller directory and data home directories with the backup directories you created before starting the upgrade. Then, apply your troubleshooting remediation changes and restart the update or installation.

A common upgrade issue involves the upgrade timing out.The installer attempts to restart the Controller and database after applying an update or installation. For large databases and depending on the system resources, this can take a considerable amount of time. If the Controller installer cannot finish starting up the Controller within a set time-out period (30 minutes by default), it exits the installation or upgrade.

You can increase the default time out period for system startup in the installer. Set the ad-timeout-in-min property to the new time in minutes in the response.varfile under Controller_home/.install4j directory or from the command line as an argument to the installer.