PDFs


This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.


Skip to end of metadata
Go to start of metadata

On this page:

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 and 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 performance information in Troubleshoot Controller Issues
  • If you have a license for the 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, db.cnf 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 common configuration files in the <controller_home>/backup directory.

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 to learn about issues and enhancements in those releases. 
  • Check the most recent Controller System Requirements and Troubleshoot Controller Issues to determine whether you need to change your performance profile

    You may upgrade your Controller profile using the Controller installer. However, downgrading the Controller profile is not supported through the installer. Please contact Support if you would like to downgrade your Controller profile.

  • Check the Controller's database.log for any errors. You can find the log at <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 have made manual configuration changes to the files, verify the configuration after updating.
  • 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.
  • Ensure you use the latest HA Toolkit from https://github.com/Appdynamics/HA-toolkit/releases/latest.
  • Back up the existing Controller following the steps in the next section.

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 for any reason, you will need to 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: 

      <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. 

Upgrade 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. This response file is at the following location

  •  <Controller_home_directory>/.install4j/response.varfile

If you have made any changes to the settings as originally configured by the installer—such as to the connection port numbers, tenancy mode, or data directory—make the same change 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. 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: 

      <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. Launch the Controller installer. On Windows, be sure to start the Controller installer in an elevated command prompt. For more information on launching the installer on Windows, see Install the Controller.
  3. 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.
  4. 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.
  5. Open a browser and access the AppDynamics user interface:

    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. On the secondary Controller, stop the database process (the application server process should already be stopped):

    /sbin/appdservice appdcontroller-db stop
  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: 

      <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 by right-clicking on the Command Prompt icon in the Windows Start menu and choosing Run as administrator. (For more information on launching the installer on Windows, see Install the Controller.) 
  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:

    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. 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 replicating from an existing Controller, and 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. 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: 

      <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. For more information on launching the installer on Windows, see Install the Controller.
  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:

    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: 

        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):

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

      SHOW SLAVE STATUS\G

       This step should provide you following result:

      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. Upgrade the secondary Controller using the instructions provided in To upgrade the Controller.

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

Both the primary and secondary Controllers are now upgraded.

Troubleshooting the Upgrade

If the upgrade does not succeed for any reason, the installer does not roll back changes on disk. This give you an opportunity to 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*). These log files contains logs written up to the point the installation stopped. Controller log files may contain additional information. 

After diagnosing the issue, you need to 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. You can then apply your troubleshooting remediation changes and restart the update or installation.

A common upgrade issue involves the upgrade process 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. 

  • No labels