Merge multiple sites into a single site
Multi-site support for Automated Configuration provides a method to merge multiple on-premises sites into a single cloud site.
Multi-site support adds unique prefixes and suffixes to component names on a per on-premises-site basis, ensuring name uniqueness after multiple on-premises sites are merged to a single cloud site.
Prefixes and suffixes can be assigned for each of the following components on a per-on-premises-site basis.
AdminScopeAdminRoleApplicationAdminApplicationFolderApplicationGroupApplicationUserDeliveryGroupGroupPolicyHostConnectionMachineCatalogStoreFrontTag
Application folders support prefixing, suffixing, and rerooting. Rerooting adds an extra top-level folder to an application’s existing folder structure.
Prefix and suffix rules
- Prefixes and suffixes cannot contain any of the following special characters:
\ , / ; : # . * ? = < > | ( ) " ' { } [ ] - Prefixes and suffixes can contain trailing spaces but not leading spaces.
- Prefixes and suffixes must be double quoted to contain trailing spaces.
- Prefixes and suffixes are applied at the time of import, merge, and add. The source
.ymlfiles are never modified. - The prefix and suffix process automatically prefixes or suffixes dependent component names when applicable. For example, if machine catalog names are prefixed with “East,” then the delivery groups referencing them are also prefixed with “East.”
- If a component name already begins with the prefix or suffix, no prefix or suffix is added. Component names cannot contain double identical prefixes or suffixes.
- Prefixes and suffixes can be individually used or used in combination.
- Use of a prefix or a suffix on a component is optional.
Note:
The Studio displays components in alphabetical order.
Group components by site
Use prefixing to visually group components from a single site. Each site is listed in its own group with prefixing alphabetically controlling the ordering of different site groups.
Group components by name
Use suffixing to visually group like-named components from multiple sites. Like-named components from different sites visually alternate.
Prefix and suffix mapping file
Site prefixing begins with the SiteMerging.yml file that contains the site prefix and suffix mapping for one or more on-premises sites. You can manage the SiteMerging.yml file manually, or by using the available cmdlets listed at the Merging multiple on-premises sites cmdlets section.
Export on-premises site
Merging cannot begin until you have exported an on-premises site. To export an on-premises site, see Export on-premises configuration.
Central export target folder
The methods described in this section place multiple site exports into a central file share location. The SiteMerging.yml file, CustomerInfo.yml file, and all export files reside in that file share location, allowing you to do the import from one location independent of the on-premises sites.
Cloud-accessing operations never reference the on-premises sites or Active Directory, therefore allowing you to do cloud-accessing operations from anywhere.
There are two methods to do this:
- Direct file share: To import, merge, or add from the direct file share, you must decide from which machine you want to do the cloud accessing operation
- File share reference using
SiteMerging.yml: This method uses theSiteRootFoldermember of the site’s prefixes set and reduces the odds of targeting the wrong folder when exporting, importing, merging, or adding.
If you do not use a central file share method, then do the import, merge, or add from the individual Delivery Controllers. Create and replicate the SiteMerging.yml file on each Delivery Controller being migrated into the cloud. The default location is %HOMEPATH%\Documents\Citrix\AutoConfig. You must specify the –SiteName parameter to select the correct site prefixes.
Direct file share
The export, import, merge, and new/add operations provide a parameter to target or source a folder other than the default folder, %HOMEPATH%\Documents\Citrix\AutoConfig. The following examples use a central file share at \\share.central.net that the admin already has access to, having provided credentials as needed.
To target the export to a site-specific folder, use the –TargetFolder parameter:
From the East Delivery Controller:
mkdir \\share.central.net\AutoConfig\SiteEast
Export-CvadAcToFile –TargetFolder \\share.central.net\AutoConfig\SiteEast
From the West Delivery Controller:
mkdir \\share.central.net\AutoConfig\SiteWest
Export-CvadAcToFile –TargetFolder \\share.central.net\AutoConfig\SiteWest`
After the exports are complete, create the CustomerInfo.yml and SiteMerging.yml files and place them in \\share.central.net\AutoConfig.
Note:
Do not use the
SiteRootFolderparameter when creating the SitePrefixes.yml when using this direct file share reference method.
To import, merge, or add from the direct file share, you must decide from which machine you want to do the cloud accessing operation. Options include:
- One of the on-premises Delivery Controllers where the tool is already installed.
- The machine hosting the file share.
- A different machine.
Automated Configuration must be installed on the machine accessing the cloud. Neither the on-premises PowerShell SDK, Delivery Controller, nor Active Directory are used, so the cloud accessing execution requirements are simpler than the export requirements.
To merge the East Delivery Controller to the cloud:
Merge-CvadAcToSite –SiteName East –SourceFolder \\share.central.net\AutoConfig\SiteEast -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml
To merge the West Delivery Controller to the cloud:
Merge-CvadAcToSite –SiteName West –SourceFolder \\share.central.net\AutoConfig\SiteWest -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml
The following is a sample SitePrefixes.yml file used in the previous example.
East:
SiteRootFolder: "" # Important: leave this empty
AdminScopePrefix: "East_"
AdminRolePrefix: "East_"
ApplicationAdminPrefix: "East_"
ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
ApplicationFolderRoot: "East"
ApplicationGroupPrefix: "East_"
ApplicationUserPrefix: "East_"
DeliveryGroupPrefix: "East_"
GroupPolicyPrefix: "East_"
HostConnectionPrefix: "East_"
MachineCatalogPrefix: "East_"
StoreFrontPrefix: "East_"
TagPrefix: "East_"
AdminScopeSuffix: "_east"
AdminRoleSuffix: "_east"
ApplicationAdminSuffix: "_east"
ApplicationFolderSuffix: "_east"
ApplicationGroupSuffix: "_east"
ApplicationUserSuffix: "_east"
DeliveryGroupSuffix: "_east"
GroupPolicySuffix: "_east"
HostConnectionSuffix: "_east"
MachineCatalogSuffix: "_east"
StoreFrontSuffix: "_east"
TagSuffix: "_east"
West:
SiteRootFolder: "" # Important: leave this empty
AdminScopePrefix: "Western "
AdminRolePrefix: "Western "
ApplicationAdminPrefix: "Western "
ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
ApplicationFolderRoot: "Western"
ApplicationGroupPrefix: "Western "
ApplicationUserPrefix: "Western "
DeliveryGroupPrefix: "Western "
GroupPolicyPrefix: "Western "
HostConnectionPrefix: "Western "
MachineCatalogPrefix: "Western "
StoreFrontPrefix: "Western "
TagPrefix: "Western "
AdminScopeSuffix: ""
AdminRoleSuffix: ""
ApplicationAdminSuffix: ""
ApplicationFolderSuffix: ""
ApplicationGroupSuffix: ""
ApplicationUserSuffix: ""
DeliveryGroupSuffix: ""
GroupPolicySuffix: ""
HostConnectionSuffix: ""
MachineCatalogSuffix: ""
StoreFrontSuffix: ""
TagSuffix: ""
File share reference using SiteMerging.yml
This method uses the SiteRootFolder member of the site’s prefixes set. While more involved than the direct file share method, this method reduces the odds of targeting the wrong folder when exporting, importing, merging, or adding.
First, set the SiteRootFolder for each site in the SiteMerging.yml file. You must do this on the shared location.
New-CvadAcSiteMergingInfo –SiteName East –SiteRootFolder \\share.central.net\AutoConfig\SiteEast -SitePrefixesFolder \\share.central.net\AutoConfig
New-CvadAcSiteMergingInfo –SiteName West –SiteRootFolder SiteWest -SitePrefixesFolder \\share.central.net\AutoConfig
In this example, East is a fully qualified folder specification and West is a relative folder specification.
To target the export to a site-specific folder using the SiteMerging.yml file:
From the East Delivery Controller:
mkdir \\share.central.net\AutoConfig\SiteEast
Export-CvadAcToFile -SiteName East -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml
From the West Delivery Controller:
mkdir \\share.central.net\AutoConfig\SiteWest
Export-CvadAcToFile -SiteName West -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml
The export cmdlet uses the CustomerInfo.yml folder location to locate the SiteMerging.yml file. In the case of East, the SiteRootFolder is fully qualified. It is used as-is. In the case of West, the SiteRootFolder is not fully qualified. It is combined with the CustomerInfo.yml folder location to retrieve a fully qualified folder location for West.
To merge the East Delivery Controller to the cloud:
Merge-CvadAcToSite –SiteName East -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml
To merge the West Delivery Controller to the cloud:
Merge-CvadAcToSite –SiteName West -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml
The following is a sample SitePrefixes.yml file used in the previous example.
East:
SiteRootFolder: "\\\\share.central.net\\AutoConfig\\SiteEast"
AdminScopePrefix: "East_"
AdminRolePrefix: "East_"
ApplicationAdminPrefix: "East_"
ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
ApplicationFolderRoot: "East"
ApplicationGroupPrefix: "East_"
ApplicationUserPrefix: "East_"
DeliveryGroupPrefix: "East_"
GroupPolicyPrefix: "East_"
HostConnectionPrefix: "East_"
MachineCatalogPrefix: "East_"
StoreFrontPrefix: "East_"
TagPrefix: "East_"
AdminScopeSuffix: "_east"
AdminRoleSuffix: "_east"
ApplicationAdminSuffix: "_east"
ApplicationFolderSuffix: "_east"
ApplicationGroupSuffix: "_east"
ApplicationUserSuffix: "_east"
DeliveryGroupSuffix: "_east"
GroupPolicySuffix: "_east"
HostConnectionSuffix: "_east"
MachineCatalogSuffix: "_east"
StoreFrontSuffix: "_east"
TagSuffix: "_east"
West:
SiteRootFolder: "\\\\share.central.net\\AutoConfig\\SiteWest"
AdminScopePrefix: "Western "
AdminRolePrefix: "Western "
ApplicationAdminPrefix: "Western "
ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
ApplicationFolderRoot: "Western"
ApplicationGroupPrefix: "Western "
ApplicationUserPrefix: "Western "
DeliveryGroupPrefix: "Western "
GroupPolicyPrefix: "Western "
HostConnectionPrefix: "Western "
MachineCatalogPrefix: "Western "
StoreFrontPrefix: "Western "
TagPrefix: "Western "
AdminScopeSuffix: ""
AdminRoleSuffix: ""
ApplicationAdminSuffix: ""
ApplicationFolderSuffix: ""
ApplicationGroupSuffix: ""
ApplicationUserSuffix: ""
DeliveryGroupSuffix: ""
GroupPolicySuffix: ""
HostConnectionSuffix: ""
MachineCatalogSuffix: ""
StoreFrontSuffix: ""
TagSuffix: ""
Merge the sites
Citrix recommends performing the cloud operations in steps and to do a complete review of each result before doing the next cloud operation. For example, if merging three sites to a single cloud site:
- Merge the initial site to the cloud using the appropriate
SiteNamevalue. - Review the results in Studio.
- If the results are incorrect, determine the issue and its cause, correct it, and then rerun the merge. If necessary, remove the cloud components and start from scratch by using
Remove-CvadAcFromSitefor the selected component and members. If the results are correct, continue. - If the initial merge is correct, merge the second site to the single cloud site.
- Repeat steps 2 and 3.
- If the second merge is correct, merge the third site to the single cloud site.
- Repeat steps 2 and 3.
- Review the resources from the user’s perspective and verify that the view is in the desired state.
Remove a component using the site prefix
You can selectively remove single site components by using the prefix on the –IncludeByName parameter of the Remove-CvadAcFromSite cmdlet. In the following example, the West Delivery Controller delivery groups are not correct. To remove the delivery groups for just the West site:
Remove-CvadAcFromSite –DeliveryGroups –IncludeByName “Western *”
To remove all West components, run the following cmdlets in order.
Remove-CvadAcFromSite –GroupPolicies –IncludeByName “Western *”
Remove-CvadAcFromSite –Applications –IncludeByName “Western *”
Remove-CvadAcFromSite – ApplicationGroups –IncludeByName “Western *”
Remove-CvadAcFromSite –DeliveryGroups –IncludeByName “Western *”
Remove-CvadAcFromSite –MachineCatalogs –IncludeByName “Western *”
Remove-CvadAcFromSite –HostConnections –IncludeByName “Western *”
Remove-CvadAcFromSite –Tags –IncludeByName “Western *”
To remove group policies of the East components, use the suffix:
Remove-CvadAcFromSite –GroupPolicies –IncludeByName “*_east”