Upgrade VDAs using the VDA Upgrade Service
You can initiate VDA upgrades through the VDA upgrade service by selecting the target machine catalog, individual machine, or group of machines and then selecting “Upgrade VDAs”.
Note:
Citrix recommends backing up VDAs before performing upgrades when possible.
Scheduling Upgrades
The VDA upgrade process in Citrix can be carried out on a catalog level, a group of machines level, or an individual machine level, depending on the requirements. Upgrades can be set to start immediately or can be scheduled at a date and time up to 7 days in advance.
Considerations
-
Catalog vs. Group of Machine vs. Machine Scope: Catalog upgrades are ideal for bulk updates while upgrading machines individually or by groups allows more granular control.
-
Scheduling: Upgrades can be scheduled for up to 7 days in advance. If using machine catalog level upgrades, machines added to the catalog after the upgrade is scheduled are not included as part of the existing scheduled upgrade.
Key Differences
| Feature | Per-Catalog Upgrade | Per-Machine Upgrade | Group of Machines |
|---|---|---|---|
| Scope of upgrades | Entire catalog | Individual machine | Group of machines from a Machine Catalog |
| Schedule control | A single schedule applies to all VDAs in the machine catalog, best for large-scale upgrade operations | VDAs are scheduled individually, which is mostly used for testing and one-off upgrades | VDAs are scheduled in groups, giving you the flexibility to upgrade different groups of VDAs at different times |
| Management | Managed through machine catalogs node in the Full Configuration interface or the New-VusCatalogSchedule cmdlet |
Managed through Search node in the Full Configuration interface or the New-VusMachineUpgrade cmdlet |
Managed through the Search node in the Full Configuration interface, or by passing a list of machines to the New-VusMachineUpgrade cmdlet |
| Use Case | Bulk upgrades for an entire Machine Catalog | Granular control for targeted upgrades and test scenarios | Targeted control of a subset of VDAs. Can be used to stagger the upgrades within a catalog |
| VDA versions available | For CR and all currently supported LTSR VDA versions, the latest version as well as 2 previous (N-2) versions are available to upgrade to. See VDA versions available for more information | For CR and all currently supported LTSR VDA versions, the latest version as well as 2 previous (N-2) versions are available to upgrade to. See VDA versions available for more information | Only the latest LTSR or CR VDA version is available to be upgraded |
| Additional Components | Installs or upgrades VDA components on each VDA. Leaving a component unchecked will not uninstall the feature, but the component will not be upgraded | Installs or upgrades the VDA component on the VDA. Leaving a component unchecked will not uninstall the feature, but the component will not be upgraded | Additional components cannot be managed by the VDA upgrade service when upgrading a group of machines. Note: Additional features, like “Enable Restore Cleanup” is available for group of machine upgrades |
| Additional Features | Additional features can be enabled or upgraded | Additional features can be enabled or upgraded | Additional features can be enabled or upgraded |
| Concurrency | Controlled as a setting when scheduling the upgrade. See Concurrency for more information | A single VDA is upgraded | Automatically load balanced based on the number of VDAs selected as part of the upgrade schedule |
| Failure Threshold | A failure threshold can be set to prevent future upgrades if a provided number of VDAs fail upgrades. See Failure Threshold for more information | Failure thresholds are not applicable for a per-machine upgrade | Failure thresholds are not available for group of machine upgrades. Consider setting the size of the group of machines to be upgraded to be the maximum number of VDAs that would be an acceptable failure amount |
How scheduled upgrades work
The VDA Upgrade Agent on the VDAs communicates with Citrix Cloud periodically to determine if the VDA should be upgraded. VDAs can be scheduled to upgrade immediately or up to 7 days in advance. When scheduling an upgrade in advance, you can set the date and time (in UTC) that the upgrade begins.
The upgrade duration sets the length of time after the scheduled upgrade start time during which upgrades occur. By default, for machine catalog and group of machine upgrades, Citrix load balances VDA upgrades throughout the upgrade duration to improve performance and avoid bottlenecks.
Once an upgrade begins, the VDA is placed into maintenance mode until the upgrade is complete. If a session is present on the VDA, the VDA will not upgrade until no sessions are present. No new sessions can be brokered to the VDA when it is in maintenance mode. If a user disconnects from a session during an upgrade window, the user will not be able to reconnect until the upgrade is complete.
The VDA will continue to attempt an upgrade until the scheduled upgrade duration is complete. If a session is present throughout the upgrade duration, the upgrade will be canceled, and maintenance mode will be turned off for the VDA. Consider a longer upgrade duration to improve the VDA upgrade success rate.
Note:
VDAs manually placed into maintenance mode before a scheduled upgrade will fail to upgrade.
VDA Versions Available
New VDA versions are available to upgrade through the VDA upgrade service shortly after the new VDA versions are made generally available. The VDA upgrade service maintains N-2 versions of the VDA for CR versions and N-2 CU versions for all LTSR versions that are currently supported.
In the full configuration interface, when upgrading either a catalog or an individual machine, the UI prompts you for which version you want to upgrade your VDAs to.
To determine the available VDA versions using PowerShell, use the Get-VusAvailableVdaVersion cmdlet.
Without passing a machine or a catalog with the cmdlet, the cmdlet will return the latest available version for all upgrade tracks.
To get the specific versions available for a resource, pass a VDA (-MachineName, -MachineUid or -MachineUuid) or catalog (-CatalogName, -CatalogUid, or -CatalogUuid) with the Get-VusAvailableVdaVersion cmdlet.
For example:
Get-VusAvailableVdaVersion -CatalogName ‘[Name of your Machine Catalog]’
Additional Components
Additional components can be installed or upgraded when upgrading VDAs by machine catalog or by individual machine. If you do not check a component, it will not uninstall the component, but the component will not be upgraded as part of the overall VDA upgrade.
Features
Features can be enabled or upgraded on VDAs through the VDA upgrade service. If you do not check a feature, it will not disable the feature, but the feature will not be upgraded as part of the overall VDA upgrade.
By default, the Enable restore cleanup checkbox is selected. Citrix recommends enabling the restore cleanup feature to ease management and improve recovery of failed upgrades. With the feature enabled, a system restore point is created before the upgrade starts. If an upgrade fails, the VDA is restored to the system restore point. The restore point is deleted after the successful installation of the VDA. For more information, see Restore on install or upgrade failure.
Note:
Windows System Restore is only supported on single-session operating systems (e.g., Windows 10 and 11). The Windows System Restore feature must be enabled on the VDA for the “Enable restore cleanup” feature to work. Upgrades may fail if “Enable restore” or “Enable restore cleanup” is selected, but Windows System Restore is not configured on the VDA.
Concurrency
When upgrading machine catalogs, VUS enables you to define a maximum number of VDAs that will upgrade simultaneously. This can help reduce the load on your internet connection or file server and, when used in conjunction with failure thresholds, enables you to stop upgrades if a number of VDAs fail to upgrade.
As soon as the scheduled upgrade starts, all VDAs in the catalog are placed in maintenance mode. An upgrade will start on a quantity of VDAs that matches the defined maximum concurrency setting. As soon as a VDA upgrade is completed, another VDA will begin to upgrade to maintain the concurrent number of VDAs upgrading simultaneously.
If no concurrency is specified for a machine catalog scheduled upgrade, Citrix uses a default concurrency value based on the total number of VDAs in the Catalog and the upgrade duration.
Upgrades take an average of around 30 minutes to complete, but this can vary greatly based on environmental conditions. Consider setting your concurrency to a quantity where all VDAs can upgrade in the provided upgrade duration. For example, if you have 20 VDAs that are set to upgrade over 4 hours, you need 5 VDAs to upgrade an hour. Using the average upgrade duration of 30 minutes, you can set the concurrency value to 3 to meet the 5 VDA upgrades per hour requirement (3 upgrades per 30 minutes results in 6 updates per hour).
Failure Threshold
When upgrading machine catalogs, use a failure threshold to prevent further VDAs from being upgraded if a given number of VDAs have failed. Failure thresholds can reduce the impact radius of issues that cause upgrade failures, reducing troubleshooting efforts for administrators.
Failure thresholds prevent any future VDAs from starting upgrades, but do not stop VDAs that have already started the upgrade. For example, if a machine catalog has 100 VDAs, concurrency is set to 10 VDAs, and the failure threshold is set to 3, if all VDA upgrades fail, at least 13 VDAs will have attempted to upgrade, and the remaining 87 will have never started, and the upgrade will be cancelled.
10 concurrent VDAs start to upgrade at the beginning of the scheduled upgrade, if the first upgrade fails, another VDA will start the upgrade to maintain the 10 concurrent simultaneous upgrades. If the second upgrade fails, another VDA will begin the upgrade. If the third upgrade fails, all VDAs that are currently in the upgrade process will continue, and the rest of the VDAs in the upgrade schedule will have their upgrade cancelled.
VDA Installer Location
You can choose for VDAs to download the VDA installation media from either the Citrix-hosted CDN or a local file share.
Upgrades through a locally hosted file share reduce the requirement for providing network rules to allow VDAs to fetch the installation media and can decrease bandwidth utilization during the upgrade process.
If using the Citrix-hosted CDN, VDAs must be able to communicate with the URLs listed in Connectivity.
If using a local file share, the file share must have the following prerequisites.
- The VDA Upgrade Agent must be version 7.40.0.35 or later, which is installed by default on VDA version 2311 or later.
- The VDA Upgrade Agent does not require a scheduled VDA upgrade to upgrade. The VDA Upgrade Agent updates automatically.
- If upgrading using PowerShell, the Virtual Apps and Desktops Remote PowerShell SDK version 7.42 or newer must be installed.
- File Share Permissions
- The network shares containing VDA installer packages must have read access for the VDA Upgrade Agent service which runs as Local System (NT AUTHORITY\SYSTEM principal).
- Domain-Joined VDAs:
- The Local System account (VUA runs as Local System), uses computer credentials when accessing network shares.
- The file share must be given read access to Domain Computers.
- In Advanced Share Settings, File and Printer Sharing must be enabled.
- Non Domain-Joined VDAs:
- The Local System account (VUA runs as Local System), uses ANONYMOUS LOGON when accessing network shares.
- In the Network and Sharing Center, Password Protected Sharing must be disabled.
- In the folder permissions Security tab, read access permissions must be granted to ANONYMOUS LOGON.
- In Advanced Share Settings, File and Printer Sharing must be enabled.
- The shared folder name must be added to the Network Access Security Policy.
- VDA installer
- The VDA installer must be downloaded from the Citrix Downloads website and placed in the file share.
- The relevant VDA installer for the machine catalog must be downloaded.
- Use the Multi-session OS VDA installer if the catalog type is multi-session.
- Use the Single-session OS VDA installer if the catalog type is single-session.
- For a given upgrade, the version of the installer on the file share must be an excat match of a version published by VUS. Use the
Get-VusAvailableVersionPowerShell cmdlet to determine the available versions.
To set VDAs to upgrade from a local file share in the Full Configuration interface, select “Use local file share” in the VDA installer location and input the path to the installer. For example, "\\hostname\VDA-Packages\VDAWorkstationSetup_2308.exe".
To set VDAs to upgrade from a local file share using PowerShell, use the -VdaWorkstationPackageUri (single-session OS) or -VdaServerPackageUri (multi-session OS) parameter when scheduling your upgrade.
Force Logoff Sessions
To increase the number of VDAs that are available for upgrade during a scheduled upgrade, consider forcefully logging off user sessions during the upgrade. The forceful logoff occurs when the upgrade begins for each individual VDA, not at the start of the overall scheduled upgrade window.
Since different VDAs start upgrading at different times within the scheduled period, users will only be logged off when their specific VDA starts its upgrade.
To forcefully log off disconnected sessions during scheduled upgrades using the Full Configuration interface, select the Log off disconnected sessions option.
To forcefully log off active sessions during scheduled upgrades using the Full Configuration interface, select the Log off active sessions option. If logging off active sessions, users will receive a notification in their session 10 minutes before the upgrade starts, reminding them to save their work before being logged off automatically.
To forcesfully log off disconnected sessions during scheduled upgrades using PowerShell, use the -LogoffOption parameter when scheduling your upgrade. The available options for -LogoffOption are listed below:
- ActiveSessionsOnly: If an active session is on the VDA during the scheduled upgrade window, the user will be logged off. A banner will display 10 minutes before the user is logged off to provide a warning. VDAs with disconnected sessions will not be logged off during the upgrade window. If the disconnected session remains throughout the upgrade window, that VDA upgrade will be cancelled.
- DisconnectedSessionsOnly: If a disconnected session is present on the VDA during the scheduled upgrade window, the user will be logged off. Users are not notified that their disconnected session will be logged off. VDAs with active sessions will not be logged off during the upgrade window. If the active session remains throughout the upgrade window, that VDA upgrade will be cancelled.
- ActiveAndDisconnectedSessions: If a disconnected or active session is on the VDA during the scheduled upgrade window, the user will be logged off. For active sessions, a banner will display 10 minutes before the user is logged off to provide a warning.
- DoNotLogoff: Active and disconnected sessions are not logged off. If a session is present on the VDA throughout the duration of the upgrade schedule, the upgrade is cancelled at the end of the scheduled upgrade window.
When possible, Citrix recommends forcefully logging off sessions to increase the number of VDAs that upgrade successfully.
Important:
Forcefully logging off sessions can result in users losing unsaved work from their session.
Reboot VDAs before upgrades
Use the option to automatically reboot VDAs before upgrades to improve the success rate by ensuring each VDA starts the process in a clean, consistent state. Rebooting before upgrade can mitigate the risk of common failures, such as pending reboots, lingering processes, or incomplete system updates.
When this option is enabled, each VDA is rebooted individually just before its upgrade begins, rather than at the start of the overall upgrade window.
To use the reboot VDA before upgrade feature, the VDA upgrade agent must be version 7.44 (released with Citrix Virtual Apps and Desktops 2503) or later.
Edit or Cancel the VDA workflow
After you schedule the upgrades for a catalog, you can edit the start time and duration of the upgrade or cancel it altogether.
To edit or cancel an upgrade using the UI at the machine catalog level, right-click on a machine catalog with an existing scheduled upgrade and click Edit Scheduled VDA Upgrade. To edit an existing machine catalog level upgrade using PowerShell, use the Set-VusCatalogUpgrade and Remove-VusCatalogUpgrade cmdlets.
To edit or cancel an upgrade at the machine level, in the search node, right-click on a machine with an existing scheduled upgrade and click Edit Scheduled VDA Upgrade. You cannot edit the scheduled VDA upgrade for multiple machines simultaneously. To edit an existing machine-level upgrade using PowerShell, use the Set-VusMachineUpgrade and Remove-VusMachineUpgrade cmdlets.