Proof of Concept: Automated Configuration Tool
Author: Thamara Trejos
The Automated Configuration tool facilitates migrating and exporting configurations to the Citrix Virtual Apps and Desktop Service (CVADs). This Proof of Concept guide illustrates the step by step instructions on how to use this tool.
Administrators can easily test and explore the Citrix Virtual Apps and Desktop Service (CVADs) features and advantages, while simultaneously running existing On-Premises environments and even facilitate moves between cloud regions, back up existing configurations, and other use cases. The Automated Configuration download link also contains additional information and detailed documentation on said use cases and customizations.
What is the Automated Configuration tool for Citrix Virtual Apps and Desktops?
This tool is designed to help automate the migration of CVAD configuration (policies, applications, catalogs, and others) from one or more On-Premises site(s) to the Citrix Virtual Apps and Desktop service (CVADs) hosted on Citrix Cloud. It can also be used to migrate information between different Cloud regions or tenants.
The migration can be performed in stages by running the tool multiple times, allowing administrators to easily achieve the desired configuration state.
Why use this tool?
IT Administrators dealing with large or complex environments, often find migrations to be a tedious process. They frequently end up writing their own tools to accomplish this task successfully since it tends to be specific to their use cases.
Citrix wants to help ease this process by providing a tool that addresses use cases through automation. Administrators can easily test current configurations in Citrix Cloud and take advantage of the benefits offered by CVADs while keeping their current environments intact. Such benefits include reduced administrative overload when Citrix manages part of the back end and control plane, automatic and customizable Citrix Cloud component updates, and others.
How is this tool implemented?
Citrix has leveraged industry standard configuration as code to provide a mechanism to help automate migration processes. This tool discovers and exports one or more on-premises sites as a collection of configuration files, which administrators can optionally edit, and then import these files’ configuration into CVADs.
This code is not limited to migrations, it is the future for creating configuration for Citrix sites, and as such, applicable for many different use cases. Disaster recovery, Development/Testing/Staging to Production site synchronization, Geographic (GEO) moves, and several other scenarios are supported. For administrators using public cloud providers, this can help create a combination of objects automatically (parallel to Microsoft Azure ARM templates and AWS CloudFormation).
- CVAD On-Premises environment with at least one registered VDA.
- CVAD On-Premises environment running on one of the following versions: Any Long Term Service Release (LTSR) versions with their latest CU (7.6, 7.15, 1912); Or one of the corresponding latest two Current Releases (CR) versions (for example: 2003, 2006).
- The domain-joined machine where you plan on installing the Automated Configuration tool must be running .NET 4.7.2 version or higher.
- A machine with the Citrix PowerShell SDK, which is automatically installed on the DDC. Note: If running the tool on a different machine, it must be domain-joined and Studio must have the correct PowerShell snap-ins installed. This installer can be found on your corresponding version’s Product ISO installation media, which can be obtained from the Citrix Downloads > Citrix Virtual Apps and Desktops website.
- Download the Automated Configuration tool MSI.
- Valid CVADs or Workspace Premium Plus licenses.
- Administrator must be able to log into the Cloud Portal and obtain: The resource location name, customer ID, client Secret (app ID and Secret Key)
- The existing Citrix Cloud Resource Location has at least one Cloud Connector, which is marked as green (Healthy) and is part of the same domain as the On-Premises setup. Note: Citrix recommends having two or more Cloud Connectors (for redundancy and High Availability). For information on how to set up your Cloud Connectors, refer to this guide.
This proof of concept guide demonstrates how to
- Complete the On-Premises pre-requisites
- Export your On-Premises site configuration into YAML (.yml) files
- Complete the cloud pre-requisites
- Complete the requisites for importing site configuration when using different provisioning methods (Provisioning Services - PVS and Machine Creation Services - MCS)
- Import your Site Configuration into Cloud (by editing the required files)
- Troubleshooting tips and where to find more information
Complete Pre-requisites for Exporting from on-premises site
These steps must be run in your DDC or the domain-joined machine where you want to install the Automated Configuration tool.
Download the latest Automated Configuration tool MSI to your On-Premises DDC or a domain-joined machine. Note: See the Pre-requisites section for more details on how to run it from a different machine.
After the MSI runs, a window indicating successful completion pops up. Click Finish to close the MSI setup window.
Note: Upon successful execution, the MSI creates the corresponding folder structure, located in
C:\Users\<username>\Documents\Citrix\AutoConfig, and also a desktop icon called Auto Config, which launches a PowerShell command prompt. This tool is the one used on subsequent steps.
Export your On-Premises site configuration
export PowerShell command, you can export your existing On-Premises configuration and obtain the necessary .yml files. These files are used to import your desired configuration into Citrix Cloud.
The Auto Config PowerShell tool launches and the current directory points to the tool’s default path (
C:\Users\<username>\Documents\Citrix\AutoConfig). Note: This directory is also where the .yml files are created later.
On the Auto Config Command Prompt, run the
Export-CvadAcToFile -all $truecommand. This command exports policies, manually provisioned catalogs and delivery groups, applications, application folders, icons, zone mappings, tags, and other items. Note: For MCS and PVS machine catalogs and delivery groups, refer to the steps on Requisites for Importing Site Configuration using different Provisioning Methods section in this guide.
Once the tool finishes running, the Overall status shows as True and the export process is completed (the output lines shown will match the following illustration). Note: If there are any errors, diagnostic files are created in the action-specific subfolders
(Export, Import, Merge, Restore, Sync, Backup, Compare), which can be found under
%HOMEPATH%\Documents\Citrix\AutoConfig. Refer to the Troubleshooting Tips section if you encounter any errors.
Note: See the following image for an example of the contents on a .yml file (
- Note: If necessary, copy the .yml files to the machine you want to use to import settings to your Citrix Cloud environment. Exporting and importing can be done from the same machine.
Complete Prerequisites in Cloud
Go to your Resource Location and make sure your Cloud Connectors are both showing green (Available). Note: If you need instructions on how to set up your Cloud Connectors, refer to this guide.
To verify the health status of your Cloud Connectors, first log in to your cloud portal with your Citrix administrator credentials (or your Azure AD credentials, when applicable).
- Note: The Cloud Connector(s) must show green, indicating a Healthy status, as seen on the following image. Citrix recommends having more than one Cloud Connector per Resource Location, for redundancy purposes.
Requisites for Importing Site Configuration using different Provisioning Methods
Dealing with Provisioning Services (PVS) Machine Catalogs, Delivery and Application Groups and Policies
Extra steps are required to import your PVS Catalogs and their corresponding applications. Follow these instructions to prepare your environment, before proceeding to import the Application settings.
Note: After performing these actions, follow the steps mentioned on the Import your Site Configuration into Cloud section in this guide.
- Run the Auto Config tool as an Administrator
- Access the
C:\Users\<username>\Documents\Citrix\AutoConfigfolder and open up the
CvadAcSecurity.ymlfile, which you must edit for PVS to work. Note: The UserName and Password fields refer to your PVS Site Server credentials. Be sure to specify your logon as
DOMAIN\Username, add the password, and save the file when ready.
- After performing these actions, follow the steps mentioned on the Import your Site Configuration into Cloud section in this guide.
Dealing with Machine Creation Services (MCS) Machine Catalogs, Delivery and Application Groups and Policies
Currently, this tool does not support importing MCS machine catalogs or their corresponding delivery groups in an automated way. However, you can still import other configuration such as Applications and policies automatically using this tool.
You must ensure you create the machine catalog and delivery group using the same names as the ones on On-Premises setup. Follow these steps to prepare your environment, before proceeding to import the Application settings:
In your Cloud portal, click the Hamburger menu > My Services > Virtual Apps and Desktops Service > Manage tab to create your MCS machine Catalog as you normally would. You must select the desired OS Type, Master Image, Storage, Licensing, Network, and Account settings.Important: Be sure to name your catalog exactly the same way your existing On-Premises catalog is named. Note: If needed, refer to this guide for information on how to set up your catalogs.
Still in Cloud Studio, create the corresponding Delivery Group for the new Catalog and ensure you name it exactly after the corresponding On-Premises Delivery Group as well. Note: For more details on how to create your Machine Catalogs and Delivery Groups, refer to [this guide/en-us/tech-zone/learn/poc-guides/cvads.html).
In your On-Premises environment’s Citrix Studio, under the Applications node, confirm that the desired applications belong to the matching Delivery Groups by selecting the desired app and then right-clicking on the app to go to the Properties as follows:
Back on the PowerShell console, run the Merge command and use the byDeliveryGroupName flag, which filters the Applications by Delivery Group name. Complete Syntax example:
Merge-CvadAcToSite –Applications $true –ByDeliveryGroupName <DG_name>
On your Cloud Studio console, go to the Applications node and refresh to make sure the apps are listed as expected. Select the applications and go to Application Properties > Groups to double-check.
- Application Folders in Cloud Studio Before running the Migration tool
- Application Folders in Cloud Studio After running the Migration tool
- Note: After performing these actions, follow the steps mentioned on the Import your Site Configuration into Cloud section in this guide.
Importing MCS-related Policies
Once you’ve performed the previous actions, if you need to import policies associated with your MCS Machine Catalogs and your Delivery groups, follow these instructions:
Check the Policies Assigned to tab and compare it against your On-Premises policy assignment, as illustrated on the following example:
- On-Premises Studio:
- Cloud Studio:
Import your Site Configuration into Cloud
During this step, you obtain the customer connection details, manually create your Zone mappings and import the configuration to your Cloud tenant. Note: For PVS and MCS, first follow the corresponding subsections under the Import your Site Configuration into Cloud section in this guide.
Obtaining Customer Connection Details
Administrators must edit the
CustomerInfo.yml file and add the corresponding CustomerName, CustomerID, and SecretKey values to it. These values can be obtained and generated from the Cloud portal, as shown in the following steps.
On your Cloud portal click the hamburger menu again and go to Identity and Access Management:
Back on your Cloud portal, under the Identity and Access Management portal and API Access tab, enter the name you want to identify this API key with on the Name your Secure Client box and then click the Create Client button. Note: This generates the
Client IDand the
Manually create the Zone Mapping file (ZoneMapping.yml)
On-Premises Zones cannot be automatically migrated to a cloud Resource Location, so they must be mapped using the
ZoneMapping.yml file. Note: Migration failures occur if the zone is not mapped with a homonymous resource location (a Resource Location with the exact same name).
Back in the same directory where your .yml files reside
(Documents\Citrix\AutoConfig), open up the
ZoneMapping.ymlusing Notepad or your preferred text editor. Note: The
Primaryvalue must be replaced with the name of your corresponding Zone you want to migrate objects from (in your On-Premises environment).
You can find this name under your On-Premises Citrix Studio console > Configuration > Zones. Note: if your Zone is named
Primaryin your On-Premises environment, this value on the
ZoneMapping.ymlfile doesn’t need to be changed:
Still on the
Name_Of_Your_Resource_Zonevalue must be replaced with your Cloud Resource Location name, which can be found on your cloud portal under the Hamburger menu > Resource Locations:
- Note: Multiple Zones in your On-Premises environment can also map to one Resource Location in the cloud. However there always needs to be one row in the file for each zone in the On-Premises environment. For multiple zones on-premises and one Resource Location, the format on this file would look as follows:
When mapping Zones to different Resource locations, the file must look like this instead:
Back on the Migration tool PowerShell console, run the following command:
Merge-CvadAcToSiteto merge the existing Cloud configuration (if any exists) with the configuration exported from the On-Premises site.
On this same folder, you can find a
Backup_YYYY_MM_DD_HH_mm_ssfolder. Note: Copy this folder somewhere safe as it is a backup of the configuration.
Verify configuration created in Cloud Studio
Access your Virtual Apps and Desktops service Manage tab via the Cloud Console > My Services > Virtual Apps and Desktops service > Manage tab).
Refresh to make sure the Machine catalogs, Delivery groups, policies, tags, and applications are now showing as expected. Note: Depending on what you import, the results vary as they are specific to your own unique configuration. Review each section to make sure the expected items are listed.
- Machine Catalogs list example:
If everything looks as expected, your CVADs migration is complete.
General information for troubleshooting:
- Running any cmdlet creates a log file and an entry in the master history log file. The entries contain the date, operation, result, backup, and log file locations of the execution. This log provides potential solutions and fixes to common errors.
- The master history log is located in
%HOMEPATH%\Documents\Citrix\AutoConfig, in the file named
History.Log.* All operation log files are placed in a backup folder.
- All log file names begin with
CitrixLog, then show the
auto-configoperation and the date and timestamp of the cmdlet execution.
- Logs do not auto-delete.
For more information:
Refer to the Automated Configuration Tool Troubleshooting FAQ article.
You can also reach out via the Support Forum.
If after consulting the information listed previously you still need assistance, get in touch with your Citrix representatives, Customer Success Manager, or Support.