Use the Update Agent Software feature to update the Horizon Agent Installer for Dedicated Desktop - Traditional Clone assignments.

Note: You can also update agent software for a Dedicated Desktop - Instant Clone assignment by updating the image and pushing changes to the assignment. This process is described in Update Agent Software for an Image.
Attention: The process described below does not work for assignments containing desktops with different operating systems. If you attempt to use this process to update an assignment with multiple operating systems, it results in an error.

At a high level, the system's agent update capability works as follows:

  • The system makes regular contact with the VMware CDS software distribution network to see if a new version of the Horizon Agents Installer is available. It downloads the new version to a file share that you have set up on a local machine. The update file is then automatically imported into the system and made available to assignments.
  • After a new version is downloaded, the Assignments page reflects that an update is available. A blue dot appears next to the name of those dedicated VDI desktop assignments that have the agent-related software at a level prior to the new version.
  • You select the dedicated VDI assignment and start the agent update wizard. Besides selecting the agent version, in the agent update wizard, you can optionally specify the following items.
    • What percentage of the assignment's VMs to keep available for users during the update.
    • Whether the system skips updating VMs that have a logged-in user.
    • Whether the system automatically retries updating any skipped VMs.
    • Whether to keep a rollback copy of each VM so that you can roll back to the previous agent version in the case of an agent update failure.
  • After you submit the update task in the wizard's last step, the system begins updating the desktops.
    • The update process on each desktop VM begins with a preflight check to confirm that the VM is in a healthy state. This includes confirming that there is sufficient disk space (at least 300 MB free) and that there is no Microsoft Windows update actively in-progress, pending reboot due to Windows updates that is not cleared by two reboots, or pending reboot due to a VMware-specific application installation that is not cleared by two reboots.
    • When updating the assignment, the system updates a batch of VMs in parallel. By default, the system uses 30 VMs for each batch until the remaining number of VMs to update is less than 30. At that point, that final set is for updating those remaining VMs. It takes approximately 30-45 minutes to fully update a VM, although the amount of time required can vary depending on the load and whether the rollback option is enabled or not. The batch size cannot be larger than 30. If the assignment has 30 or fewer desktops, all desktops in the assignment are updated together. Your VMware representative can adjust the batch size if you request it.

      The number of in-progress VMs depends on whether you specified to have a percentage of the VMs to be kept available during the update. When you set an availability percentage, the system adjusts the set of in-progress VMs to meet the availability percentage.

      Note: When you view update progress on the Monitor > Activity page, the number of VMs in progress can be larger than the expected number based on the batch size. This occurs because the system is also counting any VMs that are currently in the preflight check and rollback copy creation process.
  • At the end of the agent update process, the assignment's summary page shows the version of the Horizon Agents Installer that is in use.
  • If you selected the Enable Rollback option, you can roll back to the previous agent version for a VM when the agent update has failed on that VM. This option is on the Desktops tab of the assignment detail page. For more information, see Manage Desktops in a Dedicated or Floating Desktop Assignment.

During the time the system is updating the desktops, the desktops' end users encounter the following behaviors:

  • If a desktop has an active session and you have Skip VMs with Active Users deactivated, that user is warned five minutes before the update occurs. This five-minute warning is to give the user time to save any in-progress work.
  • If a user attempts to log in to a desktop that is being updated, the login is unsuccessful and the user receives a message that the desktop is not yet available.

Upon request, your VMware representative can make the following adjustments in your environment:

  • Adjust the interval between scans for new Horizon Agents Installer versions.
  • Adjust the wait time for scans after tenant startup.
  • Adjust the default batch size from 30.
  • Set your system to restart VMs before installing agents.

Prerequisites

You must have created an Agents file share and added it to your environment. This means that you select Agents for the file share type when you create the file share. Agents file shares are used only for importing Horizon Agents Installer files. See Managing File Shares.

Procedure

  1. Click Assignments.

    The Assignments page displays, with a blue dot appearing next to the name of any assignment that has an Horizon Agents Installer update available. If you hover over a blue dot, a popup displays indicating the new version of the Horizon Agent Installer available for that assignment.

  2. Select the check boxes for one or more assignments. By selecting multiple assignments, you can update all of them to a common Horizon Agent Installer versions.
    Attention: If you select multiple assignments, they must all use the same operating system. You cannot update agents for assignments with different operating systems simultaneously.
  3. Click Update Agent.
    The Update Agent dialog displays.
  4. In the Software step, make settings as described in the following table.
    Option Description
    List of Software (Required) Select the software and version you want to use for the update. The latest version of the software is noted below the drop-down menu.
    Note: For assignments using Microsoft Windows 7 you must select Horizon Agent Installer 20.3.x.
    VMs Update Reservation (Required) In the Available VMs to Users field, enter a percentage of the assignment's VMs to keep available for users during the update.

    By default, the system marks all of the desktops for maintenance as the update starts. You can use this field to ensure a higher percentage of a small-sized pool is available as the system goes through and updates the desktops. Setting a higher availability percentage results in an adjustment to the number of desktops currently marked for maintenance.

    Note: If you do not need desktops available, type a zero (0). You must specify a value for Available VMs to Users, even when you do not care about having desktop VMs available to users during the update process.
    Skip Disconnected and Active Sessions (Optional) Activate the Skip VMs with Logged-in User toggle to have the system skip updating VMs that have a logged-in user (active or disconnected session) or a conflicting task running. This setting avoids the system's default behavior of forcing end users off their desktop when the update process starts on that desktop.
    VMs Rollback and Failure Threshold

    (Optional) Activate the Enable Rollback toggle to have the system create a rollback copy before the agent update is performed and keep that copy for seven days. If the agent update fails on a VM, you have an opportunity to roll back to the previous agent version for that VM during that seven-day window. For more information, see What to do next at the end of these steps.

    Note: Although the rollback window is set at seven days by default, you can request that VMware change this setting for you.

    (Required) In the Failure Threshold field, enter the number of VMs for which the agent update is allowed to fail before the update process is stopped. This prevents mass failures from occurring.

    The default value for Failure Threshold is the one you configured in Settings > General Settings
    Note: When the update process stops due to failed VM updates, you might observe a number of failed VMs that is higher than the threshold you set. This can occur for a variety of reasons.

    Retry agent update on skipped VMs

    (Optional) To have the system automatically retry any of skipped VMs, activate the Retry Skipped VMs toggle.

    In the Job Timeout field, specify the time period over which you want the system to continue automatically trying to update the skipped VMs.

    The Job Timeout field sets the number of minutes that the system retries updating the skipped VMs. Every 30 minutes, the system tries to update the skipped VMs until it reaches the end of this time period or until all of the assignment's desktop VMs have been updated.

    You can enter a value that ranges from 240 minutes (4 hours) to 1440 minutes (24 hours). The default value is 720 minutes (12 hours).

    Note: VMs that encounter an error during the update process are not retried. If the update fails for a VM, you can roll the VM back to the previous version if you have activated the Roll Back option.
  5. Click Next.
  6. (Optional) On the Command Line tab, add any command line options.
  7. Click Next.
  8. On the Summary tab, review the information and click Finish.

Results

  • A message displays at the top of the page indicating that the update has started.
  • The system updates the agent-related components on the desktop VMs in the dedicated VDI desktop assignment.
  • At the end of the agent update process, the assignment's summary page lists the version of the Horizon Agents Installer that is in effect.

You can view the progress of the update task by selecting Monitor > Activity. The task description indicates the update being performed and the assignment on which it is being performed. It also shows the number of VMs in various states (Success, Skipped, and so on). If the task is not completed successfully within 24 hours, and the retry and job timeout options are not in effect, the update task is shown in failure status.

If any VMs are skipped in the update task, the update task has Partial Success status on the Activity page. In the Activity page, you can see how many VMs are skipped in the update task. If you have a number of skipped VMs at the end of the update task even though the retry option was activated, either the Job Timeout value was not long enough for the system to get to all of the skipped VMs or the end users never logged out of those VMs.

What to do next

Go to the Assignments page and see if updates were successful. If updates failed for some VMs in an assignment, there is a visual indicator next to the assignment name on the Assignments page.

If you have enabled rollback when performing the agent update, you can roll back each failed VM to the previous agent version on the Desktops tab of the assignment detail page. For more information, see Manage Desktops in a Dedicated or Floating Desktop Assignment.