Having completed lots of Citrix Cloud deployments for a variety of customers, I had yet to encounter the requirement for migrating Apps or configuration settings (Citrix policies, machine catalogs, Delivery groups etc.) from an on premise Citrix farm to Citrix Cloud DaaS service (formerly Citrix Cloud Virtual Apps and Desktops Service). Most customers, when moving to Citrix DaaS service, take the opportunity to build a brand-new Citrix deployment from the ground up – i.e., new optimized Citrix Workloads, new Citrix policies, newly provisioned machine catalogs and delivery groups etc.
However, a recent customer Citrix DaaS deployment unearthed the requirement to replicate hundreds of published apps from the on-prem Citrix farm to the new Citrix DaaS service and make those published apps available to the same AD user groups via the Citrix Gateway Service. Searching around for the easiest automated way to migrate these apps – my colleague directed me to the Auto Config tool for Citrix DaaS.
In my view – Citrix have done a good job with this tool and the online documentation explaining how to run the tool. However, there were still a few small things to figure out a long the way, so I thought I’d do a quick post in case others need a quick guide on how to get this up and running and do the basics.
As can be seen from below image – the migration process can be divided into 3 logical steps:
Step 1 – Prerequisites
The first prerequisite is a domain-joined machine with .NET Framework 4.7.2 or later and the Citrix PowerShell SDK. These components are automatically installed on any on premise Delivery Controller already.
However, the customer wasn’t keen on going through Change Control to authorise installing the Auto Config tool on a production Delivery Controller. Instead I just installed Citrix Studio (which contains the required .Net Framework version and Citrix Cloud PowerShell SDK) on a domain joined workstation.
The second prerequisite is to populate the CustomerInfo.yml file.
This file which will contain the customer ID, client ID, and a secret key tells the Automated Config tool which Citrix Cloud environment you are trying to migrate configuration items to. Steps on how to generate the customer ID, client ID and secret key are contained here.
The next step is to generate the CustomerInfo.yml file via the following PowerShell command:
New-CvadAcCustomerInfoFile -CustomerId <customer ID> -ClientId <client ID> -Secret <Secret>
As an example your command should look something like this:
New-CvadAcCustomerInfoFile -CustomerId markhof123 -ClientId 6813EEA6-46CC-4F8A-BC71-539F2DAC5984 -Secret TwBLaaaaaaaaaaaaaaaaaw==
Two things to note that tripped me up initially:
- New-CvadAcCustomerInfoFile PowerShell command only works if you’ve already installed the Auto Config tool. Don’t try to generate the CustomerInfo.yml file prior to installing the tool as the command won’t run.
- The command seems to work but where is the CustomerInfo.yml file? It is automatically created in the root of the AutoConfig folder, exactly where it needs to be for the export / import operations in later steps.
Step 2 – Export on-premise configuration
Steps to export the on-prem configuration are as follows:
- Launch the Auto Config application and a PowerShell window opens
- Type the following command: Export-CvadAcToFile
Note: performing the export is a safe operation and will not modify your on prem Citrix farm or Citrix Cloud tenant in any way. It is simply exporting your current on prem configuration into a number of output files.
My first attempt to run the export resulted in the following error:
2 items to note here:
- The account you are running the Auto Config tool under must be a full Administrator on your on prem Citrix farm
- I need to specify the Delivery Controller address via the -AdminAddress flag if running the Auto Config tool on another domain joined machine, and not the Delivery Controller
When the command completes successfully – you will see an export folder in the AutoConfig folder which will be populated with files containing the configuration data of your on premise Citrix farm:
Step 3 – Import configuration to Citrix DaaS
Important to note that your must have generated the CustomerInfo.yml outlined in Step 1 for the import operation to succeed.
The following command will import call components into the Citrix DaaS configuration: Merge-CvadAcToSite
However, in this instance I only wanted to import the published applications as the customer had already created new machine catalogs, Delivery Groups etc. in their Citrix DaaS site.
The Auto Config tool allows granular importation by various component types:
- All
- Tags
- AdminRolesScopes
- MachineCatalogs
- StoreFronts
- DeliveryGroups
- ApplicationGroups
- ApplicationFolders
- Applications
- GroupPolicies
You can also filter further by specific DeliveryGroup names, machine names etc.
In this example, I simply needed to replicate hundreds of published apps which were all managed in separate Application Folders in Citrix Studio.
Firstly, I ran the following command to import the Application Folders:
This completed quickly and created blank Application Folders in my Citrix Cloud tenant.
Secondly, I imported all the published Apps via the following command:
Once the process was complete – I refreshed my Citrix Cloud manage console and could see all published apps now present.
Important to note: the first time I attempted to import the applications the operation failed. This was because the name of my new Delivery Group in Citrix Cloud was different to that of the Delivery Group in the on-premise farm that they applications were published to.
I simply had to rename the Delivery Group in Citrix Cloud to the same as the on prem environment and then the merge command was successful.
Step 4 – Troubleshooting (if required)
Once the import operation completes – you’ll want to check that everything imported successfully or check if there were any errors during the import process.
The Merge operation creates a folder in the AutoConfig directory with a useful log file that shows you the success or failures of the import operation:
As mentioned above – if the name of the Delivery Group the app is being imported to is not the same as the name of the Delivery Group setup in the Citrix Cloud tenant – you will see an error in the log file which highlights this:
If the import is successful – the end of the log file will show you how many items were migrated or if there were any errors etc:
It is also worth backing up your Citrix DaaS configuration with the Auto Config tool before attempting any import operations – in case anything goes awry or the wrong components get imported etc.
That way your Citrix DaaS configuration can be easily restored to it’s pre migration import state if required.
Final Thoughts
To summarize – the Auto Config tool is a powerful migration tool for getting your on premise configuration across to Citrix Cloud without the hassle of manually copying / replicating configuration items. It takes a little time to setup and configure as needed but it is definitely worth it – if it saves you bundles of time on what would otherwise be lengthy manual configuration tasks.