Many Nutanix customers deploy persistent workloads on Nutanix® infrastructure. These workloads may be Windows ® Client (Windows 10 or Windows 11) desktops, or they could be custom-built Windows Server (2019, 2022 etc) based Operating Systems.
Regardless of how a workload is built (note that we are not talking about MCS in this article), integrating it with a Power-Managed Catalog in Citrix® Virtual Apps and Desktops (CVAD) allows administrators and support folk to manage the machine within both Citrix Studio and Citrix Director.
Currently, CVAD integration with the Nutanix platform is via the Prism Element™ management console. There are two exceptions where Prism Central™ integration is used:
- Citrix integration with the Nutanix Cloud Clusters™ (NC2) platform on the Microsoft Azure ® cloud.
- Citrix integration with the Nutanix Disaster Recovery as a Service™ (DRaaS) solution.
The integration for each workload is made up of two components:
- A Hosting Connection Identifier. This tells CVAD which Hosting Connection each workload is associated with, or in human speak: “Where the workload lives”.
- A Hosted Machine Identity identifies the virtual machine at the hypervisor layer. In the Nutanix world, this unique identity matches our unique virtual machine uuid in the Nutanix AHV ® hypervisor.
There are scenarios where these records can become out of sync and a workload can be orphaned:
- A customer implements a new Nutanix cluster and moves workloads across to it.
- A customer activates a disaster recovery scenario, and the workloads are activated on another cluster.
In either of these scenarios, without intervention, CVAD no longer understands where the workload resides and in some scenarios such as in a Protection Domain Activation, how to identify the workload as its UUID will have changed.
A quick note on Zoning considerations. Resources such as Catalogs and their associated Hosting Connections ideally should live within the same Citrix Zone. There can be scenarios where a split of a Catalog and its associated Hosting Connection can result in sub-optimal or even failed session launch. You cannot change a machines Zone ID as it is inherited from the Catalog it resides in. The script caters for a change of Catalog Zone if required.
The Script Purpose and Logic
To help automate the process of resolving orphaned machines, and to provide some predictable workflows for planned migration scenarios, we have written an example PowerShell ® script to demonstrate how to re-associate workloads with CVAD when they have been moved to a different Nutanix cluster, either in a planned migration or disaster recovery scenario.
The script operates with the following logic:
- Connects to the CVAD Site via the Citrix PowerShell Snapins and retrieves a list of power-managed machines which are not in an MCS or PVS catalog.
- Connects to a Nutanix cluster which you specify and queries the cluster for virtual machines that you specify. This could be either:
- A Nutanix Protection Domain hosting machines you wish to target
- A list of machinesA CSV import file
- Compares the machines in Nutanix to those in the CVAD Site. Checks if:
- The Hosting Connection you have specified is the one currently assigned to the Machine. If not, makes it so.
- The HostedMachineId attribute on the CVAD Machine matches the UUID of the machine in Nutanix AHV. If not, makes it so.
- Resets the Hosting Connection so that power states are refreshed without delay.
- If enabled, moves the specified Catalog (or Catalogs) into the same Zone as the target Hosting Connection. The script targets machines which could be spread across multiple Catalogs, so a list of Catalogs to target must be supplied.
The script logic and nature of the CVAD attributes mean that you can run this process in multiple directions without issue. As long as the Hosting Connection ID and HostedMachineId attributes are accurate, Citrix Power Management continues to work as expected.
Operational Model
In the below two scenarios, a single Citrix Site has a Hosting Connection to both Cluster 1 (source) and Cluster 2 (target).
The envisaged model of operation is as follows.
Scenario 1: A planned migration to a new Nutanix cluster occurs:
- CVAD understands the machines currently exist on Nutanix Cluster 1 which has a Citrix Hosting Connection associated with the Prism Element named “AHV Hosting Cluster 1”.
- The administrator migrates the workload to a new cluster, in this case, using a Nutanix Protection Domain Migration. The new Cluster has a Hosting Connection named “AHV Hosting Cluster 2”.
- The administrator has chosen to use the Protection Domain as the source of all machines to target for alteration.
- The administrator executes the script, targets the new Nutanix Cluster which has the Protection Domain now Active, and specifies the new Hosting Connection (AHV Hosting Cluster 2).
- Because the machines have been gracefully moved, their UUID is the same. The script will execute only a change of the Hosting Connection ID on the targeted machines, and then reset the Hosting Connection itself to avoid the delay in Power States being returned to the Service.
Scenario 2 Part A: A disaster recovery scenario has occurred, where a Protection Domain is Activated on the remote cluster:
- CVAD understands the machines currently exist on Nutanix Cluster 1 which has a Citrix Hosting Connection associated with the Prism Element named “AHV Hosting Cluster 1”.
- The administrator Activates the workloads on the target cluster, in this case, using a Nutanix Protection Domain Activation. The new cluster has a Hosting Connection named “AHV Hosting Cluster 2”.
- The administrator has chosen to use the Protection Domain as the source of all machines to target for alteration.
- The administrator executes the script, targets the new Nutanix Cluster which has the Protection Domain now Active, and specifies the new Hosting Connection (AHV Hosting Cluster 2).
- Because the machines have been forcefully activated on the target cluster, their Nutanix UUIDs will have changed. The script will execute a change of both the HostedMachineID (the machine identifier) and the Hosting Connection ID on the targeted machines. It will then reset the Hosting Connection itself to avoid the delay in the Power States being returned to the Service.
Scenario 2 Part B: The disaster recovery event is complete, and the workloads need to be migrated back to their original cluster. The Protection Domain is Migrated back to Cluster 1:
- CVAD currently understands that the machines exist on Nutanix Cluster 2, which has a Hosting Connection associated with the Prism Element named “AHV Hosting Cluster 2”.
- The administrator has chosen to use the Protection Domain as the source of all machines to target for alteration.
- The administrator executes the script, targets the original Nutanix cluster which has the Protection Domain now Active, and specifies the original Hosting Connection (AHV Hosting Cluster 1).
- Because the machines have been gracefully moved, their UUID is the same. The script will execute only a change of the Hosting Connection ID on the targeted machines, and then reset the Hosting Connection itself to avoid the delay in Power States being returned to the Service.
The script uses the following logic to address the Citrix PowerShell requirements:
- Validates that Citrix PowerShell snapins can be imported and used before doing anything else.
- Validates that the Citrix Site is reachable.
The script has advanced parameter and scenarios included in the appropriate ReadMe within the GitHub ® repository to address commonly understood potential scenarios.
Nutanix Automation Components Used
This script uses a combination of Nutanix v2 APIs and Citrix PowerShell Cmdlets.
Nutanix Prism Element API v2 Usage
PrismGateway/services/rest/v2.0/cluster: To validate connectivity to the target Nutanix cluster.PrismGateway/services/rest/v2.0/vms: To query virtual machine details.PrismGateway/services/rest/v2.0/protection_domains: To query a Protection Domain for a list of entities (virtual machines).
Citrix PowerShell CmdLets are used for all Citrix query and update commands.
Summary and Technical Requirements
This script example exists to demonstrate the ease of workload migration across multiple Nutanix clusters whilst CVAD integration is still at the Prism Element level. It is 100% PowerShell driven and
uses native API functionality for Nutanix Prism Element tasks and Citrix PowerShell Cmdlets for any CVAD queries or updates.
To successfully execute the script, the following requirements must be met:
- An appropriate credential for the Prism Element tasks. The script assumes a single account across all Prism Element instances, and we recommend a service account is used. For our testing of all components in the script, we used a cluster admin level account, however, all tasks are read-only within the Prism Element environment.
- A Windows based machine with the Citrix PowerShell Cmdlets installed. These can simply be installed by installing Citrix Studio. Alternatively, you can follow Citrix guidance to install the required snapins manually. You must use PowerShell 5.1 due to the Snapin requirements.
- The user account executing the script has appropriate permissions to the Citrix environment to perform the update tasks
PowerShell 5.1 can be used. Due to the requirement of Citrix PowerShell Snapins, PowerShell core is not supported.
To note, the script specifically and by design does not:
- Handle any form of VDA registration change. You must handle this within your environment as required (GPO etc).
- Handle any form of Active Directory OU location changes etc (see above point).
- Interact with a Nutanix Protection Domain outside of querying it for a list of machines if a Protection Domain is used as the source of truth (see parameter description).
If you manage Citrix MCS persistent workloads and wish to use the capability of this script, you will need to migrate those workloads into a Power Managed catalog prior to executing this script.
You can find the script below on our GitHub Repository: Reset Hosted Machine ID Citrix VAD
© 2023 Nutanix, Inc. All rights reserved. Nutanix, the Nutanix logo and all Nutanix product, feature and service names mentioned herein are registered trademarks or trademarks of Nutanix, Inc. in the United States and other countries. Other brand names mentioned herein are for identification purposes only and may be the trademarks of their respective holder(s). This post may contain links to external websites that are not part of Nutanix.com. Nutanix does not control these sites and disclaims all responsibility for the content or accuracy of any external site. Our decision to link to an external site should not be considered an endorsement of any content on such a site. Certain information contained in this post may relate to or be based on studies, publications, surveys and other data obtained from third-party sources and our own internal estimates and research. While we believe these third-party studies, publications, surveys and other data are reliable as of the date of this post, they have not independently verified, and we make no representation as to the adequacy, fairness, accuracy, or completeness of any information obtained from third-party sources.