Step-by-Step Technical Guide: Migrating On-Premises Citrix Environments to Citrix Cloud & Microsoft Azure

Technical Guide: Migrating On-Premises Citrix to Citrix Cloud on Microsoft Azure

Migrating an on-premises Citrix Virtual Apps and Desktops (CVAD) infrastructure to Citrix DaaS (Citrix Cloud) with workloads hosted in Microsoft Azure decouples the control plane management from your local data centers.

This architecture allows Citrix to manage core infrastructure (Delivery Controllers, Databases, Licensing, Studio, Director) as a SaaS platform while hosting session hosts/VDAs natively in Azure.

1. High-Level Architecture Overview

┌────────────────────────────────────────────────────────────────────────┐
│                        CITRIX CLOUD CONTROL PLANE                      │
│   (Managed SaaS: DaaS Studio, Director, Licensing, SQL, Workspace)    │
└───────────────────┬────────────────────────────────┬───────────────────┘
                    │ HTTPS Port 443                 │ HTTPS Port 443
                    ▼                                ▼
┌──────────────────────────────────────┐  ┌──────────────────────────────┐
│       ON-PREMISES DATA CENTER        │  ┌┴─────────────────────────────┴┐
│  • Active Directory Domain Services │  │      MICROSOFT AZURE VNET    │
│  • File Servers / Profile Shares     │  │  • Azure Cloud Connectors     │
│  • Legacy Backend Applications       │  │  • Azure Session Hosts (VDAs)│
└───────────────────▲──────────────────┘  │  • FSLogix / Azure Files     │
                    │                     └──────────────▲───────────────┘
                    │ ExpressRoute / Site-to-Site VPN    │
                    └────────────────────────────────────┘

Phase 1: Prerequisites & Azure Foundation

1. Networking & Identity Foundation

• Site-to-Site Connectivity: Establish a high-throughput, low-latency connection between your on-premises network and Azure via Azure ExpressRoute or an IPsec Site-to-Site VPN.
• Active Directory Synchronization: Ensure on-premises Active Directory Domain Services (AD DS) synchronizes with Microsoft Entra ID (formerly Azure AD) via Entra Connect.
• Azure Subnet & VNet Design: Create dedicated subnets inside your Azure VNet for:
  • Infrastructure-Subnet (Cloud Connectors, domain controllers)
  • VDA-Workload-Subnet (Session host VMs)
  • Storage-Subnet (Azure Files / NetApp Files)

Phase 2: Deploying Azure Resource Location & Cloud Connectors

Citrix Cloud Connectors serve as the secure proxy relaying API commands, session brokering, and identity checks over outbound Port 443 between Azure resources and Citrix Cloud.

[Azure VDAs] ──► [Citrix Cloud Connectors] ──► (Port 443 Outbound) ──► [Citrix Cloud DaaS]

1. Deploy Connector VMs: Provision at least two Windows Server virtual machines (e.g., Standard_D2s_v5) in Azure for high availability within an Availability Set or Zone.
2. Domain Join: Join both servers to your Active Directory domain.
3. Install Connectors:
   • Log into your Citrix Cloud Console ([https://citrix.cloud.com](https://citrix.cloud.com)).
   • Navigate to Resource Locations > Add a Resource Location (e.g., Azure-EastUS-RL).
   • Download and run the CloudConnectorSetup.exe installer as a Domain Admin on both Connector VMs.
   • Confirm the connection state shows healthy in Citrix Cloud.

Phase 3: Automated Migration of Citrix Policies & Sites

To avoid manually recreating hundreds of Delivery Groups, Machine Catalogs, and Citrix Policies, use the official Citrix Automated Configuration Tool (ACT).

┌─────────────────────────┐                           ┌─────────────────────────┐
│ On-Prem Delivery Ctrl   │                           │    Citrix DaaS Studio   │
│   (Studio & Policies)   │                           │     (Cloud Service)     │
└────────────┬────────────┘                           └────────────▲────────────┘
             │                                                     │
             │  Export (.yml)                      Import (.yml)   │
             └──────────────► [Automated Config] ──────────────────┘
                                   Tool

1. Install ACT: Download the tool on an on-premises machine with PowerShell access to your Delivery Controllers.
2. Authenticate with Citrix Cloud:
   • Generate an API Client Key in Citrix Cloud under Identity and Access Management > API Access.
   • Populate the CustomerInfo.yml file with your CustomerId, ClientId, and SecretKey.
3. Export On-Premises Config:PowerShell# Exports site objects to YAML configuration files Export-CvadAcToFile
4. Update Hosting Connection: Edit the CvadAcSecurity.yml file to map your old hypervisor (vSphere/Hyper-V) connections to your new Azure Subscription ID, tenant credentials, and Resource Groups.
5. Import Config to Cloud:PowerShell# Merges configuration into Citrix DaaS Merge-CvadAcToSite -SiteActiveState $false

Phase 4: Image Preparation & Profile Migration

1. Golden Master Image Migration

• Option A (Fresh Image): Deploy a clean Windows 10/11 Enterprise Multi-Session VM directly in Azure.
• Option B (Migrate Image): Capture your on-premises VHD/VMDK master image, strip local hypervisor drivers/agents, and upload it to an Azure Compute Gallery via Azure Storage.
• VDA Installation: Install the latest Citrix Virtual Delivery Agent (VDA) on the master VM using the /controllers parameter pointing to your new Azure Cloud Connectors:DOSVDAWorkstationSetup.exe /quiet /controllers "AZ-CC01.domain.local AZ-CC02.domain.local" /enable_hdx_ports /masterimage

2. User Profile Storage Transition (FSLogix)

Convert from Citrix Profile Management (CPM) or local profiles to FSLogix Profile Containers hosted on Azure Files:

1. Provision an Azure Files Storage Account configured with AD DS authentication.
2. Deploy FSLogix Agent onto the Master VDA Image.
3. Configure GPO / Registry values for FSLogix redirection:
   • VHDLocations = \\azurefiles.file.core.windows.net\profiles
   • Enabled = 1

Phase 5: Machine Catalogs & Provisioning via Azure MCS

1. Configure Hosting Connection: In Citrix DaaS Studio, navigate to Hosting > Add Connection and Resources:
   • Choose Microsoft Azure as the Connection Type.
   • Authenticate using an Azure Service Principal with Contributor rights over the target Azure Resource Group.
2. Create Machine Catalog:
   • Select Machine Creation Services (MCS).
   • Choose the Golden Image from Azure Compute Gallery.
   • Select Azure VM Size (e.g., Standard_D4as_v5 for multi-session workloads).
   • Enable Citrix MCS I/O Storage Optimization (MCSIO) to cache temporary writes to RAM/disk, significantly cutting Azure OS disk IOPS costs.
3. Provision Delivery Groups: Assign the catalog VMs to user roles synchronized via Microsoft Entra ID / Active Directory.

Phase 6: Access Layer Cutover & Site Activation

Choose one of three access strategies to route traffic:

Route Strategy	Storefront Location	Gateway Location	Use Case
Option 1 (Full Cloud)	Citrix Workspace Service	Citrix Gateway Service	Complete SaaS solution; lowest operational burden.
Option 2 (Hybrid)	Citrix Workspace Service	On-Premises NetScaler ADC	High-bandwidth local HDX routing requirements.
Option 3 (Legacy Parallel)	On-Premises StoreFront	On-Premises NetScaler ADC	Zero change for end-users during gradual migration.

Finalizing Migration (Cutover Steps)

1. Set on-premises Delivery Groups into Maintenance Mode.
2. Run ACT activation cmdlet to activate the cloud site:PowerShellSet-CvadAcSiteActiveStateCloud -SiteActive
3. Validate user sessions, HDX performance, and FSLogix container mounting across pilot groups before fully decommissioning on-premises Delivery Controllers

⚖️ Regulatory & Technical Disclaimer

Disclaimer: This technical migration guide is provided for educational and architectural reference purposes only. Implementation details may vary based on specific network topologies, security compliance requirements, and software versions. Always test migration scripts and configurations in a non-production staging environment prior to production rollout.