Citrix Virtual Apps and Desktops

View PDF

Create a prepared image machine catalog in Azure

November 19, 2024

Contributed by:

Create prepared images and use the prepared images to create an MCS machine catalog using:

Web Studio
PowerShell commands

The key steps to create an MCS machine catalog using the prepared image are:

Create the image definition and the initial image versions.
Use the image version as a prepared image to create a catalog

Use Web Studio

Create an image definition and initial image version

To create an image definition and the initial image version, do the following:

From Web Studio, go to the Images node, and click Create Image Definition. Click Next on the Introduction page.
On the Image Definition page, specify the OS type and Session type for the image definition.
Select an existing resource group or create a new one for holding the image resources. To enable image sharing, select Place image versions in the Azure Compute Gallery and then choose to create a new gallery or use an existing one to hold its image versions.
On the Image page, select Resources (only the resources applicable for the set connection are listed) and a master image to use as a template for creating the image version. You can select the Use a machine profile checkbox and select a machine profile.

Note:

Before selecting an image, verify that the master image has VDA 2311 or later installed and the MCSIO driver is installed on the VDA.
On the Storage and Licenses Types page, select the storage and license type to be used as part of the image preparation process.

Note:

If you select a machine profile on the Image page, the license type of the machine profile is pre-selected based on the profile setting.
On the Machine Specification page, select a machine size. If you select a machine profile on the Image page, the machine size of the machine profile is selected by default.
On the NICs page, select or add NICs for the preparation image. For each NIC, select an associated virtual network.
On the Disk Settings page, select the customer-managed encryption key (CMEK). If the machine profile doesn’t have a CMEK but the master image has, it pre-selects the CMEK from the master image.
On the Version Description page, enter a description for the initial image version created.
On the Summary page, check the details of the image definition and the initial image version created. Enter a name and description for the image definition. Click Finish.

Create image versions

Image versions allow for the management of different iterations or updates to a particular image. This functionality enables you to maintain multiple versions of an image for different purposes.

To create image versions from the initial image version, do the following:

Note:

The hosting unit of all the image versions must be the same.

Go to the Images node, select an image version or an image definition, and click Create Image Version.
On the Image definition page, you can change the hosting unit, and reselect the master image and machine profile for that image version.
If you want the configuration of the image version to be different from the initial configured image version, then configure the settings on the Storage and License Types, Machine Specification, NICs, and Disk Settings pages of the Create Image Version dialog.
Add a description for the image version. Click Finish.

create-image-versions

Note:

If the creation of the image version fails for any reason, the Troubleshoot tab at the bottom provides a Retry option.

Shared prepared image

To share prepared images across different host units for Azure, follow these steps:

Right-click an image version and select Manage Image Share. All the host units under the selected connection are listed. The resources where the image version is created from is disabled for any actions.
Select the host units with which you want to share the image and click Save. The Share Status column shows In progress.
Click the Resources tab for more details about the sharing status.

Note:

When the status of the image version sharing is in progress, the option to Delete Image Version or Manage Image Share is disabled.

Create a machine catalog from the Images node

Use the Create catalog option in the Images node to create a catalog using the image version.

Alternatively, you can select the version when creating a catalog in the Machine Catalogs node, linking to the prepared image option in the catalog creation workflow. See Create a machine catalog from the Machine Catalogs node

To create an MCS machine catalog from the Images node, do the following:

Select an image version and click Create catalog. Click Next on the Introduction page.
On the Desktop Experience page, select the required desktop experience.
From the Image page to Disk Settings page, the settings are pre-selected based on the selected image version.
On the Resource Group page, you can choose to create a new resource group or use an existing resource group to place the resources of this catalog.
Complete the settings on the following pages.
On the Summary page, check the details of the machine catalog. Enter a name and description for the machine catalog. Click Finish.
Go to the Machine Catalogs node to see the created machine catalog.

Create a machine catalog from the Machine Catalogs node

To create an MCS machine catalog from the Machine Catalogs node, do the following:

Click Machine Catalogs on the left navigation pane.
Click Create Machine Catalog. The Machine Catalog Setup page appears. Click Next through the Introduction, Machine Type, and Machine Management pages.
On the Image page:
1. Select Prepared image.
2. Under the Prepared image, select an image version of an image definition.
3. Click the image version name. To view more details about the selected image version, click the version number, which is underlined.
4. If the selected image version is configured with a machine profile, select a machine profile. If the selected image version is not configured with a machine profile, you cannot choose to use a machine profile.
Configure the settings on the following pages.
On the Disk Settings page, if the selected prepared image uses a disk encryption set, then you cannot remove the encryption set, but you can change the key to another encryption key.
On the Resource Group page, you can choose to create a new resource group or use an existing resource group to place the resources of this catalog.
Complete the settings on the following pages.
On the Summary page, check the details of the machine catalog. Enter a name and description for the machine catalog. Click Finish.

Use PowerShell

Create a prepared image

The detailed PowerShell commands to create a prepared image version spec are as follows:

Check the available image definition names using the Test-ProvImageDefinitionNameAvailable command. For example,
```
Test-ProvImageDefinitionNameAvailable -ImageDefinitionName <string[]>

```

Create an image definition using the New-ProvImageDefinition command. For example,

New-ProvImageDefinition -ImageDefinitionName image1 -OsType Windows -VdaSessionSupport MultiSession
<!--NeedCopy-->

Create a new configuration for image definition in the specified Hosting connection using the Add-ProvImageDefinitionConnection command.

The CustomProperties for Add-ProvImageDefinitionConnection can include the following. If you do not use the parameters, then default values are used.

ResourceGroups: The resource group that has the base disks.
UseSharedImageGallery: Indicator for the type of base disks. Use true for ACG (image sharing) and false for snapshot.
ImageGallery: The gallery name when the base disk is an ACG image version.

For example,

In case of snapshot and customer provided resource group:

 $CustomerOwnRsourceGroupProperties = @"
 <CustomProperties xmlns="http:// schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Property xsi:type="StringProperty" Name="ResourceGroups" Value="yangj_image" />
 </CustomProperties>
 "@
 <!--NeedCopy-->

In case of ACG and customer provided resource group and image gallery:

 $CustomerOwnAllProperties = @"
 <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" />
 <Property xsi:type="StringProperty" Name="ResourceGroups" Value="rg" />
 <Property xsi:type="StringProperty" Name="ImageGallery" Value="gallery" />
 </CustomProperties>
 "@
 <!--NeedCopy-->

In case of ACG and customer provided resource group only:

$CustomerOwnResourceGroupProperties = @"
<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="rg" />
</CustomProperties>
"@
<!--NeedCopy-->

In case of ACG and resource group and image gallery managed by Citrix:

 $CustomerOwnResourceGroupNothingProperties = @"
 <CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" />
 </CustomProperties>
 "@
 <!--NeedCopy-->

Add-ProvImageDefinitionConnection -ImageDefinitionName image1 -HypervisorConnectionName Azure28 [-CustomProperties $CustomProperties]
<!--NeedCopy-->

Create an image version using the New-ProvImageVersion command. For example,

New-ProvImageVersion -ImageDefinitionName image1 -Description "version 1"
<!--NeedCopy-->

Add a master image version spec to the image version using the Add-ProvImageVersionSpec command. For example,

Add-ProvImageVersionSpec -ImageDefinitionName  image1  -ImageVersionNumber  1 -HostingUnitName azure -MasterImagePath "XDHyp:\HostingUnits\azure\image.folder\azureresourcegroup.resourcegroup\win2022-snapshot.snapshot"
<!--NeedCopy-->

Note:

You can add only one master image version spec to one image version for a hosting unit.

Create a prepared image version spec from the master image version spec using the New-ProvImageVersionSpec command. For example,

New-ProvImageVersionSpec
-SourceImageVersionSpecUid  c6e7384c-b2f8-46d6-9519-29a2c57ed3cb
-NetworkMapping @{"0"="XDHyp:\HostingUnits\azure\virtualprivatecloud.folder\azureresourcegroup.resourcegroup\azure-vnet-eastus.virtualprivatecloud\dev.network"}
-ServiceOffering"XDHyp:\HostingUnits\azure\serviceoffering.folder\Standard_B2ms.serviceoffering" -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"></CustomProperties>" -RunAsynchronously
<!--NeedCopy-->

You can also share prepared image version spec with another hosting unit within the same hosting connection using the Add-ProvImageVersionSpecHostingUnit command. For example,
```
Add-ProvImageVersionSpecHostingUnit -ImageVersionSpecUid xxxxxxx -HostingUnitName AzureWest

```
Note:

One hosting unit and preparation type can have only one prepared instance.

Example of the complete set of Powershell commands to create image definition, image version, and prepared image version spec:

New-ProvImageDefinition -ImageDefinitionName image1 -OsType Windows -VdaSessionSupport MultiSession
 
$CustomProperties = @"
<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" />
    <Property xsi:type="StringProperty" Name="ResourceGroups" Value="rg" />
    <Property xsi:type="StringProperty" Name="ImageGallery" Value="gallery" />
</CustomProperties>
"@  
 
Add-ProvImageDefinitionConnection -ImageDefinitionName image1 -HypervisorConnectionName Azure28 -CustomProperties $CustomProperties
 
$imageVersion = New-ProvImageVersion -ImageDefinitionName image1 -Description "version 1"
 
$SourceImageVersionSpec = Add-ProvImageVersionSpec -ImageVersionUid $imageVersion.ImageVersionUid `
    -HostingUnitUid $hostingunit.HostingUnitUid `
    -MasterImagePath "XDHyp:\HostingUnits\azure28\image.folder\abc.resourcegroup\def-snapshot.snapshot"
 
New-ProvImageVersionSpec -NetworkMapping @{"0" = "XDHyp:\HostingUnits\azure28\virtualprivatecloud.folder\East US.region\virtualprivatecloud.folder\studio-mcs-infrastructure.resourcegroup\studio-mcs-vnet-eastus.virtualprivatecloud\mcs-dev.network" } -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"LicenseType`" Value=`"Windows_Server`" /></CustomProperties>" -ServiceOffering "XDHyp:\HostingUnits\azure28\serviceoffering.folder\Standard_B2s.serviceoffering" -SourceImageVersionSpecUid $SourceImageVersionSpec.ImageVersionSpecUid
Add-ProvImageVersionSpecHostingUnit -ImageVersionSpecUid xxxxxxx -HostingUnitName AzureWest
$PreparedImageVersionSpec = Get-ProvImageVersionSpec -ImageVersionUid $imageVersion.ImageVersionUid | Where SourceImageVersionSpecUid-eq $SourceImageVersionSpec.ImageVersionSpecUid
<!--NeedCopy-->

Note:

All image version specs in an image definition must belong to the same hosting unit.

An image version can have only one master image version spec and one prepared image version spec.

All image version specs must either have a machine profile or none of the image version specs must have a machine profile.

Create a catalog using a prepared image version spec

Create an MCS machine catalog from the prepared image version spec using the New-ProvScheme command. For example,

New-ProvScheme -ProvisioningSchemeName <string> -ImageVersionSpecUid <Guid> -HostingUnitUid <Guid> -IdentityPoolUid <Guid> [-VMCpuCount <int>] [-VMMemoryMB <int>] [-UseWriteBackCache] [-NetworkMapping <Hashtable>] [-CleanOnBoot] [-Scope <string[]>] [-Metadata <Hashtable>] [-ServiceOffering <string>] [-SecurityGroup <string[]>] [-TenancyType <string>] [-MachineProfile <string>] [-CustomProperties <string>] [-ResetAdministratorPasswords] [-UseFullDiskCloneProvisioning] [-RunAsynchronously] [-PurgeJobOnSuccess] [-ProvisioningSchemeType <ProvisioningSchemeType>]
<!--NeedCopy-->

Or,

New-ProvScheme -ProvisioningSchemeName <string> -ImageVersionSpecUid <Guid> -HostingUnitName <string> -IdentityPoolName <string> [-VMCpuCount <int>] [-VMMemoryMB <int>] [-UseWriteBackCache] [-NetworkMapping <Hashtable>] [-CleanOnBoot] [-Scope <string[]>] [-Metadata <Hashtable>] [-ServiceOffering <string>] [-SecurityGroup <string[]>] [-TenancyType <string>] [-MachineProfile <string>] [-CustomProperties <string>] [-ResetAdministratorPasswords] [-UseFullDiskCloneProvisioning] [-RunAsynchronously] [-PurgeJobOnSuccess] [-ProvisioningSchemeType <ProvisioningSchemeType>]
<!--NeedCopy-->

If you want to use an ACG image version spec, then set UseSharedImageGallery as true. For example,

$provSchemeCustomProperties= @"
<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
    <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" />
    <Property xsi:type="StringProperty" Name="StorageAccountType" Value="StandardSSD_LRS" />
</CustomProperties>
"@
New-ProvScheme -ProvisioningSchemeName assignimage -ImageVersionSpecUid $PreparedImageVersionSpec.ImageVersionSpecUid `
    -HostingUnitUid $hostingunit.HostingUnitUid `
    -IdentityPoolUid $IdentityPool.IdentityPoolUid `
    -CleanOnBoot -Scope @() -SecurityGroup @() `
    -ServiceOffering "XDHyp:\HostingUnits\azure28\serviceoffering.folder\Standard_B2s.serviceoffering" `
    -NetworkMapping @{"0"="XDHyp:\HostingUnits\azure28\virtualprivatecloud.folder\East US.region\virtualprivatecloud.folder\studio-mcs-infrastructure.resourcegroup\studio-mcs-vnet-eastus.virtualprivatecloud\mcs-dev.network"} `
    -CustomProperties $provSchemeCustomProperties
<!--NeedCopy-->

Example of the complete set of Powershell commands to create a catalog:

$Catalog = New-BrokerCatalog  -AllocationType "Random"  -IsRemotePC $False  -MinimumFunctionalLevel "L7_20" -Name "azurecatalog" -PersistUserChanges "Discard" -ProvisioningType "MCS" -Scope @() -SessionSupport "MultiSession"

$IdentityPool = New-AcctIdentityPool  -AllowUnicode  -Domain "azure.local" -IdentityPoolName "azurecatalog" -IdentityType "ActiveDirectory"  -NamingScheme "azure##" -NamingSchemeType "Numeric" -Scope @()

$PreparedImageVersionSpec = Get-ProvImageVersionSpec -ImageDefinitionName image1 -ImageVersionNumber 1 -Filter "PreparationType -eq 'Mcs'"

$Task = New-ProvScheme -ProvisioningSchemeName azurecatalog -ImageVersionSpecUid $PreparedImageVersionSpec.ImageVersionSpecUid -HostingUnitName azure -IdentityPoolName azurecatalog -CleanOnBoot -Scope @() -SecurityGroup @() -ServiceOffering "XDHyp:\HostingUnits\azure\serviceoffering.folder\Standard_B2s.serviceoffering" -NetworkMapping @{"0"="XDHyp:\HostingUnits\azure\virtualprivatecloud.folder\azureresourcegroup.resourcegroup\azure-vnet-eastus.virtualprivatecloud\dev.network"} -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`">    <Property xsi:type="StringProperty" Name="UseSharedImageGallery" Value="true" /><Property xsi:type=`"StringProperty`" Name=`"StorageAccountType`" Value=`"StandardSSD_LRS`" /></CustomProperties>" -RunAsynchronously

Get-ProvTask -TaskId $Task.TaskId
$ProvScheme = Get-ProvScheme -ProvisioningSchemeName azurecatalog

Set-BrokerCatalog -Name $Catalog.Name -ProvisioningSchemeId $ProvScheme.ProvisioningSchemeUid
<!--NeedCopy-->

More information

Image management

Where to go next

Manage prepared image machine catalogs

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Create a prepared image machine catalog in Azure

November 19, 2024

Contributed by:

November 19, 2024

Contributed by:

Create a prepared image machine catalog in Azure

Use Web Studio

Create an image definition and initial image version

Create image versions

Shared prepared image

Create a machine catalog from the Images node

Create a machine catalog from the Machine Catalogs node

Use PowerShell

Create a prepared image

Create a catalog using a prepared image version spec

More information

Where to go next

In this article