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® DaaS allows administrators and support folk to manage the machine within both Citrix Web Studio and Citrix Director.
Currently, Citrix DaaS 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 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 Citrix DaaS 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, Citrix DaaS 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. In Citrix DaaS, a Zone is a Resource Location. 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 Citrix DaaS 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 Citrix DaaS via a Secure Client 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 machines A CSV import file
- Compares the machines in Nutanix to those in Citrix DaaS. 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 Citrix DaaS 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 Citrix DaaS 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, Citrix DaaS 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:
- Citrix DaaS 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 c
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:
- Citrix DaaS 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 c
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 c
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:
- Citrix DaaS 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 has advanced parameter and scenarios included in the appropriate ReadMe within the GitHub® repository to address commonly understood potential scenarios.
Citrix API limits
When retrieving machines from Citrix DaaS, there is a maximum returned object count of 1000 machines. The script tries to optimize the number of calls made to the DaaS service, so the following behaviours apply. This is an FYI only, but good to understand:
- If the default MaxDaaSVMCount of 1000 or below is used, then a single initial call to the DaaS Service is made to retrieve all machines. This list of machines is then referenced for other operations in the Script.
- If the value of MaxDaaSVMCount is above 1000, then the script will first seek to understand Nutanix virtual machine targets, and then make a call for each one to the DaaS service. This means that the number of API calls made for machine lookups will directly tie to the number of Nutanix machines targeted.
If there are 150 Nutanix virtual machines to target, and there are 900 machines in the Citrix DaaS tenant, a single call to retrieve all machines will be made by the script.
If there are 150 Nutanix virtual machines to target, and there are 1500 machines in the Citrix DaaS tenant, 150 calls will be made to retrieve the machine details.
Automation Components Used
The script uses an API-only approach, with a combination of Nutanix v2 APIs and Citrix Cloud DaaS API. The following APIs have been used as an example of what can be achieved:
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 DaaS API Usage
cctrustoauth2/root/tokens/clients: To create a Citrix Access Token for the API requests.cvadapis/me: To retrieve the Citrix Site ID for the DaaS Site.cvadapis/{SiteID}/hypervisors/$($TargetHostingConnectionName): To retrieve details about the specified Hosting Connection.cvadapis/{SiteID}/Machines: To retrieve DaaS power-managed machines and to set Hosting attributes as required.cvadapis/{SiteID}/hypervisors/{HostingConnection}/resetConnection: To reset the Citrix Hosting Connection if changes have been made to the environment.cvadapis/{SiteID}/MachineCatalogs/{Catalog}:To get Catalog details and assess suitability for zone switch.cvad/manage/Zones/{zoneid}/$moveItems: To handle the moving of the Catalog from Zone 1 to Zone 2.
Summary and Technical Requirements
This script example exists to demonstrate the ease of workload migration across multiple Nutanix Clusters whilst Citrix DaaS integration is still at the Prism Element lLevel. It is 100% PowerShell driven and uses native API functionality for both Citrix DaaS and Prism Element tasks.
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 Citrix DaaS Secure Client must be downloaded and stored in an accessible directory by the user executing the script.
PowerShell 5.1 onwards can be used, including PowerShell 7. Testing has only been completed on a Windows Operating System, however, there are no specific known dependencies on Windows.
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:
© 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.