Citrix Application Delivery Management service

Use jobs to upgrade Citrix ADC instances

In Citrix Application Delivery Management (ADM), you can upgrade one or more Citrix ADC instances. You must know the licensing framework and types of licenses before you upgrade an instance.

Prerequisites

Before you upgrade an ADC instance, perform the pre-validation check on the instance that you want to upgrade.

  1. Check for customizations - Back up your customizations and delete them from the instances. You can reapply the backed-up customizations after the instance upgrade.

  2. Check for disk hardware issues - Resolve the hardware issues if any.

ADC high-availability pair

When you upgrade an ADC high-availability pair, note the following:

  • The secondary node is upgraded first.

  • Synchronization and propagation of the nodes are disabled until both the nodes are upgraded successfully.

  • After the successful high-availability pair upgrade, an error message appears in the execution history. This message appears if your nodes in the high-availability pair are on different builds or versions. This message indicates that synchronization between primary and secondary node is disabled.

You can upgrade an ADC high-availability pair in two stages:

  1. Create an upgrade job and run on one of the nodes immediately or schedule later.

  2. Schedule the upgrade job to run on the remaining node later. Ensure to schedule this job after the initial node’s upgrade.

ADC clusters

When you upgrade an ADC cluster, in the pre-upgrade validation stage, the ADM only validates the specified instance. Therefore, check and resolve the following issues on the cluster nodes:

  • Customization
  • Disk usage
  • hardware issues

Create an ADC upgrade job

To create an ADC upgrade job, do the following:

  1. Navigate to Networks > Configuration job > Maintenance Jobs.

    Create maintenance job

  2. In Create Maintenance Jobs, select Upgrade Citrix ADC (Standalone/High-Availability/Cluster) and click Proceed.

    Select upgrade maintenance job

  3. In Select Instance, type a name of your choice for Job Name.

  4. Click Add Instances to add ADC instances that you want to upgrade.

    • To upgrade an ADC high-availability pair, specify the IP address of either the primary or secondary node.

    • To upgrade a cluster, specify the cluster IP address.

    Add instances to upgrade maintenance job

  5. Click Next to start the pre-upgrade validation on the selected instances.

    The Pre-upgrade validation tab displays the failed instances. you can remove the failed instances and click Next.

    Important

    If you specify cluster IP address, the ADM does pre-upgrade validation only on the specified instance not on the other cluster nodes.

  6. Optional, in Custom scripts, specify the scripts to run before and after an instance upgrade. For more information, see Use custom scripts.

  7. In Schedule Task, select one of the following options:

    • Upgrade now: The upgrade job runs immediately.

    • Schedule Later: Select this option to run this upgrade job later. Specify the Execution Date and Start Time when you want to upgrade the instances.

      If you want to upgrade an ADC high-availability pair in two stages, select Perform two stage upgrade for nodes in high-availability.

      Specify the Execution Date and Start Time when you want to upgrade another instance in the high-availability pair.

      ADC high-availability upgrade two stages

      For more information, see ADC high-availability pair.

  8. In Create Job, specify the following details:

    • Select ADC software image: Select an ADC image from the list. This option lists all ADC images that are available in the Citrix Downloads website.

      ADC images

      The ADC software images display the preferred builds with the star icon. And, most downloaded builds with the bookmark icon.

    • Upload ADC software image: You can upload the image from your local computer or the ADC appliance. When you select ADC appliance, the ADM GUI displays the instance files that are present in /var/mps/mps_images. Select the image from the ADM GUI.

    If you schedule the upgrade job, you can specify when you want to upload the image to an instance:

    • Upload now: Select this option to upload the image immediately. However, the upgrade job runs at the scheduled time.

    • Upload at the time of execution: Select this option to upload the image at the time of upgrade job execution.

    When you want to upload the image?

    For more information on other upgrade options, see ADC upgrade options.

  9. Click Create Job.

The upgrade job appears in the Networks > Configuration job > Maintenance Jobs. When you edit an existing job, you can switch to any tabs if the required fields are already filled. For example, if you are in the Select Configuration tab, you can switch to the Job Preview tab.

Clean up the ADC disk space

If you face the insufficient disk space issue while upgrading an ADC instance, clean up the disk space from the ADM GUI itself.

  1. In the Pre-upgrade validation tab, select the instance that has the disk space issue.

  2. Select Check Disk Space.

    This pane displays the instance’s disk that has low space. It also displays how much memory is used and available on the disk.

  3. In the Check Disk Space pane, select the instance that requires cleanup.

  4. Click Disk Cleanup.

    Disk cleanup

  5. Select the files that you want to erase.

  6. Click Delete

Use custom scripts

You can specify custom scripts while you create an ADC upgrade job. The custom scripts are used to check the changes before and after an ADC instance upgrade. For example:

  • The instance version before and after the upgrade.

  • The status of interfaces, high-availability nodes, virtual servers, and services before and after upgrade.

  • The statistics of virtual servers and services.

  • The dynamic routes.

Specify the custom scripts to run in the following stages:

  • Pre upgrade: The specified script runs before upgrading an instance.

  • Post upgrade pre failover (applicable for HA): This stage only applies to the high-availability deployment. The specified script runs after upgrading the nodes, but before their failover.

  • Post upgrade (applicable for standalone) / Post upgrade post failover (applicable for HA): The specified script runs after upgrading an instance in the standalone deployment. In the high-availability deployment, the script runs after upgrading the nodes and their failover.

Note

  • Ensure to enable script or commands execution at the required stages. Otherwise, the specified scripts do not run.

  • The diff report is generated only if you specify the same script in the pre-upgrade and post-upgrade stages. Therefore, ensure to select Use same script as Pre-upgrade in the post-upgrade stages. See, Download a consolidated diff report of an ADC upgrade job.

You can import a script file or type commands directly in the ADM GUI.

  • Import commands from file: Select the command input file from your local computer.
  • Type commands: Enter commands directly on the GUI.

In the post upgrade stages, you can use the same script specified in the pre-upgrade stage.

Custom scripts

ADC upgrade options

While you create an ADC upgrade job, you can select the following options in the Create Job tab:

  • Clean software image from Citrix ADC on successful upgrade - Select this option to clear the uploaded image in the ADC instance after the instance upgrade.

  • Backup the ADC instances before starting the upgrade.: Creates a backup of the selected ADC instances.

  • Maintain the primary and secondary status of high-availability nodes after upgrade: Select this option if you want the upgrade job to initiate a failover after each node’s upgrade. In this way, the upgrade job maintains the primary and secondary status of the nodes.

  • Save ADC configuration before starting the upgrade - Saves the running ADC configuration before upgrading the ADC instances.

  • Enable ISSU to avoid network outage on ADC HA pair - ISSU ensures the zero downtime upgrade on an ADC high-availability pair. This option provides a migration functionality that honors the existing connections during upgrade. So, you can upgrade an ADC high-availability pair without downtime. Specify the ISSU migration timeout in minutes.

  • Receive Execution Report through email - Sends the execution report in email. To add an email distribution list, see Create an email distribution list.

  • Receive Execution Report through slack - Sends the execution report in slack. To add a Slack profile, see Create a Slack profile.

Create upgrade job and upload image to ADC

Download a consolidated diff report of an ADC upgrade job

In Citrix ADM, you can download a diff report of an ADC upgrade job. To do so, the upgrade job must have custom scripts. A diff report contains the differences between the outputs of the pre-upgrade and post-upgrade script. With this report, you can determine what changes occurred on the ADC instance post upgrade.

Note

The diff report is generated only if you specify the same script in the pre-upgrade and post-upgrade stages.

To download a diff report of an upgrade job, do the following:

  1. Navigate to Networks > Configuration Jobs > Maintenance Jobs.

  2. Select the upgrade job for which you want to download a diff report.

  3. Click Diff Reports.

  4. In Diff Reports, download a consolidated diff report of the selected upgrade job.

    In this page, you can download any of the following diff reports type:

    • Pre vs Post upgrade pre failover diff report
    • Pre vs Post upgrade diff report

    Download a diff report of an ADC upgrade job

Use jobs to upgrade Citrix ADC instances