Jump to content
Welcome to our new Citrix community!

Citrix DaaS Power Management of Google Cloud Platform (GCP)-based Virtual Machines with PowerShell and REST-API

    • Contributed By: Gerhard Krenn Special Thanks To: Nitin Mehta, Yuhua Lu, Steve Beals, Google Cloud Support Team (Lavanya, Nishan)

Introduction

Using Citrix DaaS, you can power manage Machine Creation Services (MCS)-provisioned Virtual Machines across various supported Hypervisors and Cloud Services.
The Power Management operation provides:

  • Optimal user experience
  • Cost management and power savings

In GCP environments, you can create an MCS Machine Catalog that supports Hibernation.
You can suspend a Virtual Machine when the session is idle for some time and then reconnect to the previous state when a user signs in again.

If you want to keep your VM instance when it is not in use, you can suspend the VM without being charged for.
When you suspend a VM, GCP preserves the VM in your project and moves the contents of the VM's memory to storage.

While the VM is suspended, GCP only charges for the storage used to preserve the VM's memory.
Attributes like static IP addresses stay in place so that network functions work as expected when you resume the VM.
After resuming, GCP moves the VM's memory from storage back to the instance, and starts charging you for the now-running VM instance.

As a result, hibernating a Virtual Machine can be useful in scenarios such as:

  1. Development and test environments that are not being fully used during off periods, for cost savings or faster initialization than creating VM instances.
  2. Applications that require a long period of initialization after the instance has finished booting, but before the application is ready to service its first request, such as virtual developer workstations.

Note: We measured an almost 30% faster connection time when starting a session using a suspended VM compared to a powered-off VM! This increases the User Experience and User Acceptance!

Suspending an instance sends an ACPI S3 suspend signal to the instance's operating system. Suspending an instance is analogous to closing the lid of your laptop, putting the instance into a SUSPENDED state.
It differs from stopping an instance in the following ways:

  • Suspended instances preserve the guest OS memory, device state, and application state.
  • GCP charges for the storage necessary to save instance memory.
  • You can only suspend an instance for up to 60 days. After 60 days, the instance is automatically moved to the TERMINATED state.

All resources that are attached to the instance remain attached to the instance and are charged, including persistent disks and static or reserved external IP addresses.
All of these resources are charged according to the price sheet, even if an instance is suspended.

You cannot suspend an instance by using the standard processes that are built into the guest environment.
Commands, such as the systemctl suspend command in Ubuntu 16.04 and later, are not available. You can only use the Google Cloud CLI or REST to suspend an instance.

When you suspend an instance, you are charged for:

  • Instance memory: See Pricing for Suspended VM instances
  • Any persistent disk usage for the boot disk and any additional disks attached to the instance: See Persistent disk pricing
  • Any static IPs attached to the instance
  • Suspending VMs might save on your software licensing fees. For example, if you suspend Windows VMs, you do not incur Windows license fees.

The following table describes the effect of suspending a VM instance on its associated resources:

Resource Support
Memory Only VMs with less than or equal to 208 GB of memory can be suspended
Local SSD Local SSD data is discarded
Persistent disk Persistent HDD and SSD disks are kept
IP addresses Ephemeral IPs are released during suspension, but static IPs remain attached to the VM instances.
VM configuration (such as machine type, metadata, labels, and so on) All VM configurations, other than ephemeral IP addresses, are preserved and restored when the instance resumes

Supported Operating Systems

Linux:

  • CentOS 7, 8
  • CentOS Stream 8, 9
  • Debian 9, 11, 12
  • RHEL 7, 8, 9
  • RHEL for SAP 7.7, 7.9, 8.4, 8.6, 8.8, 9.0, 9.2
  • Rocky Linux 8, 9
  • Ubuntu 16.04 LTS, 18.04 LTS, 20.04 LTS, 22.04 LTS
  • Ubuntu Pro 16.04 LTS, Pro 18.04 LTS, Pro 20.04 LTS, Pro 22.04 LTS

Windows:

  • Windows Server 2022
  • Windows Server 2019
  • Windows Server 2016
  • Windows 10 x64
  • Windows 11 x64

Note: Windows 11 x64 is currently supported only on GCP Sole-Tenant nodes!
Further limitations: a BitLocker-enabled image is not supported!

Limitations

The following limitations apply for this feature:

  • You cannot suspend an instance that uses a GPU.
  • You cannot suspend an instance by using the standard processes that are built into the guest environment. Commands, such as the systemctl suspend command in Ubuntu 16.04 and later, are not available. The in-guest signal is ignored.
  • You can only suspend an instance for up to 60 days before the VM is automatically stopped.
  • You cannot suspend instances with more than 208 GB of memory.
  • You can suspend preemptible instances, but the preemptible instance might be terminated before it is successfully suspended.
  • You cannot suspend a Confidential VM.
  • You cannot suspend a VM that has CSEK-protected disks attached.

Prerequisites to use Hibernation

  • You must enable the feature for your subscription before you can use Hibernation.
  • To suspend an instance, use the Google Cloud console, the gcloud CLI, the API, or the Cloud Client Libraries.
  • You cannot suspend an instance by using the standard processes that are built into the guest environment. You can use the Google Cloud console, the Google Cloud CLI, or the API to suspend an instance.
  • The suspend operation can fail if it's triggered too soon after the instance was started. The instance must be fully started (including processes like Guest Agent) for the Suspend operation to succeed.
  • The OS must support Hibernation.
  • If a Virtual Machine is being created from an OS disk or a Gallery image, then the OS disk or Image definition must support Hibernation.
  • You need to use a persistent OS disk which is large enough to store the contents of the RAM, OS, and other applications running on the Virtual Machine.
  • The Virtual Machine must have the Virtual Machine Guest Agent installed if you are using the Windows or Linux Hibernate Extensions.

Note:

MCS automatically sets the Hibernation property for the generated resources. You do not need to configure the properties of the Master resources to support Hibernation.

Required permissions for Power Management

Minimum permissions give better security control. However, new features that require extra permissions fail if only minimum permissions are given.
You must have these permissions on the instance level:

"compute.instances.suspend" "compute.instances.resume"

A complete overview about Suspend and Resume of Instances in Google Cloud is too long and can be found at: Suspend and resume a VM

Citrix Cloud-related prerequisites to use hibernation

For Citrix DaaS to support Hibernation on GCP, no prerequisites are required.
This functionality is implemented out-of-the-box.

Create Hibernation-capable Virtual Machines and Machine Catalogs

In GCP environments, you can create an MCS Machine Catalog that supports Hibernation. Using this feature, you can suspend a Virtual Machine when the session is idle for some time and then reconnect to the previous state of the Virtual Machine when a user signs in again.
To use the Hibernation capability, you can do the following. However, before proceeding, see the prerequisites and limitations.

  • Create and manage a Hibernation-capable Machine Catalog using the Full Configuration interface or PowerShell commands. You must select a machine profile that supports Hibernation.
  • Create a Machine Catalog for existing Hibernation-capable Virtual Machines using the Full configuration interface. You can create a Machine Catalog containing both Hibernation-capable and incapable Virtual Machines. However, if you want Hibernation-related functionality, create the Machine Catalog with only Hibernation-enabled Virtual Machines.
  • Enable Hibernation on existing MCS-provisioned Virtual Machines using PowerShell commands.
  • Check the Hibernation property of a Machine Catalog, Virtual Machine, and broker machine using PowerShell commands.

Creating a Hibernation-enabled Virtual Machine using the GCP Console

Assuming all prerequisites are met, you can create a Hibernation-enabled GCP-based Virtual Machine using the GCP console.
No special instructions/steps are needed.

Keep in mind to fulfill all prerequisites otherwise errors may occur.

Note:

As GCP currently does not support deploying Windows Client OS-VMs out-of-the-box, you need to create a Windows 10/11-based VM yourself. Creating a VM by yourself is a lengthy process as shown in the next chapter.

Creating a Hibernation-enabled Virtual Machine using PowerShell

Before being able to access GCP with PowerShell you have to install the GoogleCloud-PowerShell module:

PS C:\TACG> Install-Module GoogleCloud                                                                        

PS C:\TACG> Import-Module GoogleCloud -quiet
 Google Cloud SDK is not found in PATH. The SDK is required to run the module.

 Installing Google Cloud SDK

 WARNING: You will have to restart the shell and/or run 'gcloud init' (if you haven't run it after installing the SDK) before the module can be used.

PS C:\TACG>

After successful installation you need to initialize the module and log in to continue.

PS C:\TACG> PS C:\TACG> gcloud init
Welcome! This command will take you through the configuration of gcloud.

Your current configuration has been set to: [default]

You can skip diagnostics next time by using the following flag:
  gcloud init --skip-diagnostics

Network diagnostic detects and fixes local network connection issues.
Checking network connection...done.
Reachability Check passed.
Network diagnostic passed (1/1 checks passed).

You must log in to continue. Would you like to log in (Y/n)?  Y

A browser window opens and you have to authenticate.

deployment-guides-citrix-gcp-hib-sdk-signin1.png

deployment-guides-citrix-gcp-hib-sdk-signin2.png

deployment-guides-citrix-gcp-hib-sdk-signin3.png

After successful authentication you need to choose which GCP project you want to access:

Your browser has been opened to visit:

     https://accounts.google.com/o/oauth2/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

 You are logged in as: [XXXXXXXXXXX@XXXXXXX.XXXXXXX].

 Pick cloud project to use:
  [1] tacg-gcp
  [2] Enter a project ID
  [3] Create a new project
 Please enter numeric choice or text value (must exactly match list item):  1

 Your current project has been set to: [tacg-gcp].

 Do you want to configure a default Compute Region and Zone? (Y/n)?  n

 Created a default .boto configuration file at [C:\TACG\.boto]. See this file and
 [https://cloud.google.com/storage/docs/gsutil/commands/config] for more
 information about configuring Google Cloud Storage.
 Your Google Cloud SDK is configured and ready to use!

 * Commands that require authentication will use XXXXXXXXXX@XXXXXXXXXX.XXXXXXXXX by default
 * Commands will reference project `tacg-gcp` by default
 Run `gcloud help config` to learn how to change individual settings

 This gcloud configuration is called [default]. You can create additional configurations if you work with multiple accounts and/or projects.
 Run `gcloud topic configurations` to learn more.

 Some things to try next:

 * Run `gcloud --help` to see the Cloud Platform services you can interact with. And run `gcloud help COMMAND` to get hel
 p on any gcloud command.
 * Run `gcloud topic --help` to learn about advanced features of the SDK like arg files and output formatting
 * Run `gcloud cheat-sheet` to see a roster of go-to `gcloud` commands.

 PS C:\TACG>

Now you are ready for accessing the GCP environment using PowerShell.

Build a custom Windows 10-based Image

Detailed information about creating a Windows 10-BYOL-VM in GCP can be found here: Create custom Windows BYOL images

Set up the environment

PS C:\TACG> gcloud config set compute/region us-central1
 Updated property [compute/region].

PS C:\TACG> gcloud config set compute/zone us-central1-a
 Updated property [compute/zone].

PS C:\TACG>
PS C:\TACG> $PROJECT_ID="NAME_OF_THE_GCP_PROJECT"
PS C:\TACG> $PROJECT_NUMBER = gcloud projects describe `$PROJECT_ID` --format=value`(projectNumber`)

PS C:\TACG> gcloud projects add-iam-policy-binding `$PROJECT_ID` --member serviceAccount:`$PROJECT_NUMBER`@cloudbuild.gserviceaccount.com --role roles/compute.instanceAdmin.v1

 Updated IAM policy for project [XXXXXXXXXX].
 bindings:
 - members:
   - serviceAccount:XXXXXXXXXX@cloudbuild.gserviceaccount.com
   role: roles/cloudbuild.builds.builder
 - members:
   - serviceAccount:service-XXXXXXXXXX@gcp-sa-cloudbuild.iam.gserviceaccount.com
   role: roles/cloudbuild.serviceAgent
 - members:
   - serviceAccount:XXXXXXXXXX@cloudbuild.gserviceaccount.com
   role: roles/compute.instanceAdmin.v1
 - members:
   - serviceAccount:service-XXXXXXXXXX@compute-system.iam.gserviceaccount.com
   role: roles/compute.serviceAgent
 - members:
   - serviceAccount:service-XXXXXXXXXX@containerregistry.iam.gserviceaccount.com
   role: roles/containerregistry.ServiceAgent
 - members:
   - serviceAccount:XXXXXXXXXX-compute@developer.gserviceaccount.com
   - serviceAccount:XXXXXXXXXX@cloudservices.gserviceaccount.com
   role: roles/editor
 - members:
   - serviceAccount:citrixcloud@tacg-gcp.iam.gserviceaccount.com
   - user:XXXXXXXXXXX
   role: roles/owner
 - members:
   - serviceAccount:service-XXXXXXXXXX@gcp-sa-pubsub.iam.gserviceaccount.com
   role: roles/pubsub.serviceAgent
 etag: BwYLN8GkMPs=
 version: 1

PS C:\TACG> gcloud projects add-iam-policy-binding `$PROJECT_ID` --member serviceAccount:`$PROJECT_NUMBER`@cloudbuild.gserviceaccount.com --role roles/iam.serviceAccountUser

 Updated IAM policy for project [tacg-gcp].
 bindings:
 - members:
   - serviceAccount:XXXXXXXXXX@cloudbuild.gserviceaccount.com
   role: roles/cloudbuild.builds.builder
 - members:
   - serviceAccount:service-XXXXXXXXXX@gcp-sa-cloudbuild.iam.gserviceaccount.com
   role: roles/cloudbuild.serviceAgent
 - members:
   - serviceAccount:XXXXXXXXXX@cloudbuild.gserviceaccount.com
   role: roles/compute.instanceAdmin.v1
 - members:
   - serviceAccount:service-XXXXXXXXXX@compute-system.iam.gserviceaccount.com
   role: roles/compute.serviceAgent
 - members:
   - serviceAccount:service-XXXXXXXXXX@containerregistry.iam.gserviceaccount.com
   role: roles/containerregistry.ServiceAgent
 - members:
   - serviceAccount:XXXXXXXXXX-compute@developer.gserviceaccount.com
   - serviceAccount:XXXXXXXXXX@cloudservices.gserviceaccount.com
   role: roles/editor
 - members:
   - serviceAccount:XXXXXXXXXX@cloudbuild.gserviceaccount.com
   role: roles/iam.serviceAccountUser
 - members:
   - serviceAccount:citrixcloud@tacg-gcp.iam.gserviceaccount.com
   - user:XXXXXXXXXXXXXX
   role: roles/owner
 - members:
   - serviceAccount:service-XXXXXXXXXX@gcp-sa-pubsub.iam.gserviceaccount.com
   role: roles/pubsub.serviceAgent
 etag: BwYLN8J-u3E=
 version: 1

PS C:\TACG>

Upload all prerequisites

PS C:\TACG> gsutil mb -p $PROJECT_ID gs://$PROJECT_ID-media
 Creating gs://tacg-gcp-media/...

 PS C:\TACG> gsutil iam ch serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com:objectViewer  gs://$PROJECT_ID-media

 PS C:\TACG> gsutil cp C:\TACG\PowerShell_7.4.0-win-x64.msi gs://$PROJECT_ID-media/PowerShell.msi
 Copying file://C:\TACG\PowerShell_7.4.0-win-x64.msi [Content-Type=application/octet-stream]...
 \ [1 files][103.9 MiB/103.9 MiB]    4.2 MiB/s
 Operation completed over 1 objects/103.9 MiB.

 PS C:\TACG> gsutil cp C:\TACG\ndp48-x86-x64-allos-enu.exe gs://$PROJECT_ID-media/dotnet-sdk.exe
 Copying file://C:\TACG\ndp48-x86-x64-allos-enu.exe [Content-Type=application/x-msdownload]...
 \ [1 files][115.7 MiB/115.7 MiB]    4.2 MiB/s
 Operation completed over 1 objects/115.7 MiB.

 PS C:\TACG> gsutil cp C:\TACG\GoogleCloudSDKInstaller.exe gs://$PROJECT_ID-media/GoogleCloudSDKInstaller.exe
 Copying file://C:\TACG\GoogleCloudSDKInstaller.exe [Content-Type=application/x-msdownload]...
 - [1 files][148.6 KiB/148.6 KiB]
 Operation completed over 1 objects/148.6 KiB.

 PS C:\TACG>gsutil cp C:\TACG\Win10_22H2.iso gs://$PROJECT_ID-media/
 Copying file://C:\TACG\Win10_22H2.iso [Content-Type=application/octet-stream]...
  | [1 files][  5.7 GiB/  5.7 GiB]    4.2 MiB/s
 Operation completed over 1 objects/5.7 GiB.

PS C:\TACG>

You are now ready to build the custom image.
Running the workflow to build a custom image takes up to four hours.
Instead of running it locally, you now create a Cloud Build configuration so that you can let Cloud Build run the workflow in the background.

Run a custom image build workflow

  • Clone the Git repository containing the workflows for building Windows images
PS C:\TACG> git clone https://github.com/GoogleCloudPlatform/compute-image-tools.git
 Cloning into 'compute-image-tools'...
 remote: Enumerating objects: 23792, done.
 remote: Counting objects: 100% (2578/2578), done.
 remote: Compressing objects: 100% (520/520), done.
 Receiving objects: 100% (23792/23792), 15.04 MiB | 14.89 MiB/sremote: Total 23792 (delta 2195), reused 2348 (delta 2023)
 Receiving objects:

 Resolving deltas: 100% (17415/17415), done.
 PS C:\TACG>
  • Switch to the directory where the Git repository was cloned into
PS C:\TACG> cd compute-image-tools/daisy_workflows/image_build/windows/
PS C:\TACG\compute-image-tools\daisy_workflows\image_build\windows> dir windows-10*

  Directory: C:\TACG\compute-image-tools\daisy_workflows\image_build\windows

 Mode      LastWriteTime          Length Name
 ----      -------------          ------ ----
 -a----    30.11.2023 10:25       3528   windows-10-20h2-ent-x64-uefi.wf.json
 -a----    30.11.2023 10:25       3037   windows-10-20h2-ent-x86-bios.wf.json
 -a----    30.11.2023 10:25       3822   windows-10-21h2-ent-x64-uefi.wf.json
 -a----    30.11.2023 10:25       5041   windows-10-21h2-ent-x86-bios.wf.json
 -a----    30.11.2023 10:25       3822   windows-10-22h2-ent-x64-uefi.wf.json
 -a----    30.11.2023 10:25       5041   windows-10-22h2-ent-x86-bios.wf.json
 -a----    30.11.2023 10:25       3822   windows-10-next-ent-x64-uefi.wf.json

 PS C:\TACG\compute-image-tools\daisy_workflows\image_build\windows>

  • As we want to create a W10-based machine we must open the closest matching wf.json file and make some changes.

    deployment-guides-citrix-gcp-hib-dwf1.png

  • Now create a file in the directory named cloudbuild.yaml and paste the following code:

timeout: 86400s  # 4 hour timeout for entire build
steps:
- name: 'gcr.io/compute-image-tools/daisy'
  timeout: 86400s  # 4 hour timeout for build step
  args:
    - -project=$PROJECT_ID
    - -zone=us-central1-a
    - -var:updates=gs://$PROJECT_ID-media/updates/
    - -var:pwsh=gs://$PROJECT_ID-media/PowerShell.msi
    - -var:dotnet48=gs://$PROJECT_ID-media/dotnet-sdk.exe
    - -var:cloudsdk=gs://$PROJECT_ID-media/GoogleCloudSDKInstaller.exe
    - -var:media=gs://$PROJECT_ID-media/Win10_22H2_English_x64v1.iso
    - windows-10-22h2-ent-x64-uefi.wf.json
  • Now you can submit the build to Cloud Build
PS C:\TACG\compute-image-tools\daisy_workflows\image_build\windows> $PROJECT_ID="tacg-XXXXXX"
PS C:\TACG\compute-image-tools\daisy_workflows\image_build\windows> gcloud builds submit --project $PROJECT_ID  --async

 Creating temporary tarball archive of 64 file(s) totalling 282.7 KiB before compression.
 Uploading tarball of [.] to [gs://tacg-gcp_cloudbuild/source/1701339000.306825-8f51ae01f0b04c148157e6393f334859.tgz]
 Created [https://cloudbuild.googleapis.com/v1/projects/tacg-gcp/locations/global/builds/2448a8bb-dcbb-4fb2-a07d-f964b5473272].

Logs are available at [ https://console.cloud.google.com/cloud-build/builds/2448a8bb-dcbb-4fb2-a07d-f964b5473272?project=577702529180 ].
 ID                                    CREATE_TIME                DURATION  SOURCE   IMAGES  STATUS
 2448a8bb-dcbb-4fb2-a07d-f964b5473272  2023-11-30T10:10:04+00:00  -         gs://tacg-gcp_cloudbuild/source/1701339000.30  6825-8f51ae01f0b04c148157e6393f334859.tgz  - QUEUED

PS C:\TACG\compute-image-tools\daisy_workflows\image_build\windows>

The build takes around up to four hours to complete. You can track the status of the build in the Google Cloud console under Cloud Build > History.

deployment-guides-citrix-gcp-hib-dwf2.png

If these steps do not succeed, a CLI-based deployment might help.

Note:

Beware, third party links, Citrix is not responsible for any misuse or damage made by this information!

The necessary steps are described here:

Create a VM from a custom image

Further troubleshooting steps while building a custom Windows-based VM: Create custom Windows BYOL images

Get information about target editions of Windows

When the creation of the Master Image succeeded, the next steps can be started.

Creating a Hibernation-enabled Virtual Machine using REST-API

Note:

As GCP currently does not support deploying Windows Client OS-VMs out-of-the-box, you need to create a Windows 10/11-based VM yourself. Creating a VM by yourself is a lengthy process - an example can be found at [Creating a Hibernation-enabled Virtual Machine using PowerShell](#Creating a Hibernation-enabled Virtual Machine using PowerShell)

You can create a custom Windows 10/11-based VM yourself using REST-API calls:

POST https://compute.googleapis.com/compute/v1/projects/$PROJECT_ID/zones/$ZONES/instances

{
   "machineType":"zones/$MACHINE_TYPE_ZONE/machineTypes/$MACHINE_TYPE",
   "name":"$VM_NAME",   
   "disks":[
      {
         "initializeParams":{
            "sourceImage":"projects/$IMAGE_PROJECT/global/images/$IMAGE”
         },
         "boot":true
      }
   ],

   "networkInterfaces":[
      {
         "network":"global/networks/$NETWORK_NAME"
      }
   ],

   "shieldedInstanceConfig":{
      "enableSecureBoot":"$ENABLE_SECURE_BOOT"
   }
}

A detailed documentation of the REST-API call and its parameters can be found at: Create a VM from a custom image

Creating a Hibernation-capable Machine Catalog using the Citrix Cloud GUI

These prerequisites must be completed before creating a Machine Catalog:

Create a Service Account in IAM which has the correct Roles and Permissions needed. See About GCP permissions

Before creating a Google cloud platform (GCP) catalog, you need to finish creating a connection to GCP. See Connection to Google cloud environments

Look at the needed settings for Configuring Private Google Access

Note: For simplified security needs tick the “Route traffic through Citrix Cloud Connectors” box in the Hosting Connection properties you want to use!

deployment-guides-citrix-gcp-hib-create-mc3a.png

IMPORTANT: Check that the subnet of the outbound VM interface of the Cloud Connectors has Private Google Access enabled, otherwise the provisioning of the MC fails!

deployment-guides-citrix-gcp-hib-subnet-vpc.png

The following screenshots show the steps for creating a Hibernation-capable Machine Catalog.

deployment-guides-citrix-gcp-hib-create-mc1.png


deployment-guides-citrix-gcp-hib-create-mc2.png


deployment-guides-citrix-gcp-hib-create-mc3.png


deployment-guides-citrix-gcp-hib-create-mc4.png


deployment-guides-citrix-gcp-hib-create-mc5.png


deployment-guides-citrix-gcp-hib-create-mc6.png


deployment-guides-citrix-gcp-hib-create-mc7.png


deployment-guides-citrix-gcp-hib-create-mc8.png


deployment-guides-citrix-gcp-hib-create-mc9.png


deployment-guides-citrix-gcp-hib-create-mc10.png


deployment-guides-citrix-gcp-hib-create-mc11.png


deployment-guides-citrix-gcp-hib-create-mc12.png


deployment-guides-citrix-gcp-hib-create-mc13.png


deployment-guides-citrix-gcp-hib-create-mc14.png


deployment-guides-citrix-gcp-hib-create-mc15.png

Creation of the Machine Catalog is complete.

Creating a Hibernation-capable Machine Catalog using PowerShell

After you meet all the requirements to use Hibernation (link to the prerequisites topic), you can create a Hibernation capable Machine Catalog using the New-ProvScheme command.
For information on how to create a catalog using the Remote PowerShell SDK, see Creating a catalog.

  • Create the MC:
PS C:\TACG> `New-BrokerCatalog -AllocationType 'Static' -IsRemotePC $False -MinimumFunctionalLevel 'L7_34' -Name 'MC-GCP-HibTest-PSH' -PersistUserChanges 'OnLocal' -ProvisioningType 'MCS' -Scope @() -Sess
ionSupport 'SingleSession'`

AdminFolderName             :
AdminFolderUid              : 0
AllocationType              : Static
AppDnaAnalysisState         :
AssignedCount               : 0
AvailableAssignedCount      : 0
AvailableCount              : 0
AvailableUnassignedCount    : 0
CatalogName                 : MC-GCP-HibTest-PSH
Description                 :
HypervisorConnectionUid     :
IsRemotePC                  : False
MachinesArePhysical         : False
MdmEnrollment               : None
MetadataMap                 : {}
MinimumFunctionalLevel      : L7_34
Name                            : MC-GCP-HibTest-PSH
PersistUserChanges          : OnLocal
ProvisioningSchemeId        :
ProvisioningType            : MCS
PvsAddress                  :
PvsDomain                   :
RemotePCDesktopGroupPriorities  : {}
RemotePCDesktopGroupUids    : {}
RemotePCHypervisorConnectionUid :
Scopes                      :
SessionSupport              : SingleSession
Tags                        : {}
TenantId                    :
TimeZone                    :
UUID                        : 3XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Uid                         : 23
UnassignedCount             : 0
UsedCount                   : 0
ZoneHealthy                 : True
ZoneName                    : Initial Zone
ZoneUid                     : 00000000-0000-0000-0000-000000000000
  • Create an IdentityPool
PS C:\TACG> `New-AcctIdentityPool -AllowUnicode -Domain 'gcp.the-austrian-citrix-guy.at' -IdentityPoolName 'IP-GCP-HibTest-PSH' -NamingScheme 'GCP-Hib-PS-#' -NamingSchemeType 'Numeric' -OU 'CN=Computers,DC=gcp,DC=the-austrian-citrix-guy,DC=at' -Scope @()`

AvailableAccounts    : 0
DeviceManagementType : None
Domain               : GCP.THE-AUSTRIAN-CITRIX-GUY.AT
ErrorAccounts        : 0
IdentityContent      :
IdentityPoolName     : IP-GCP-HibTest-PSH
IdentityPoolUid      : fXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
IdentityType         : ActiveDirectory
InUseAccounts        : 0
Lock                 : False
MetadataMap          : {}
NamingScheme         : GCP-Hib-PS-#
NamingSchemeType     : Numeric
OU                   : CN=Computers,DC=gcp,DC=the-austrian-citrix-guy,DC=at
ResourceLocationId   :
StartCount           : 1
TaintedAccounts      : 0
WorkgroupMachine     : False
ZoneUid              :
Scopes               : {}
TenantId             :
  • Create a Provisioning Scheme
PS C:\TACG> `New-ProvScheme -HostingUnitName 'NW-TACG-GCP' -IdentityPoolName 'IP-GCP-HibTest-PSH' -MasterImageVirtual Machine 'XDHyp:\HostingUnits\NW-TACG-GCP\instance-w10.vm' -ProvisioningSchemeName 'MC-GCP' -Scope @()}`

TaskId                   : 7XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Active                   : False
Host                     : EA102823-4-2
DateStarted              : 02.01.2024 12:34:14
Metadata                 : {}
Type                     : NewProvisioningScheme
Status                   : Finished
CurrentOperation         :
TaskExpectedCompletion   : 02.01.2024 12:40:41
LastUpdateTime           : 02.01.2024 12:40:41
ActiveElapsedTime        : 387
DateFinished             : 02.01.2024 12:40:41
TerminatingError         :
Storage                  : {}
WorkflowStatus           : Completed
Warnings                 : {}
ProvisioningSchemeName   : MC-GCP
MasterImage              : XDHyp:\HostingUnits\NW-TACG-GCP\instance-w10.vm
PreparedImageDefinitionName   :
PreparedImageVersionUid  :
PreparedImageVersionNumber    :
IdentityPoolName         : IP-GCP-HibTest-PSH
IdentityPoolUid          : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
HostingUnitName          : NW-TACG-HibTestNN
HostingUnitUid           : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
CustomProperties         : <CustomProperties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.citrix.com/2014/xd/machinecreation">
                                 <Property xsi:type="StringProperty" Name="CryptoKeyId" Value="" />
                                 <Property xsi:type="StringProperty" Name="CatalogZones" Value="tacg-gcp-XXXXXX:us-central1:a" />
                                 <Property xsi:type="StringProperty" Name="StorageType" Value="pd-standard" />
                                 <Property xsi:type="StringProperty" Name="IdentityDiskStorageType" Value="pd-standard" />
                                 <Property xsi:type="StringProperty" Name="WBCDiskStorageType" Value="pd-standard" />
                                 <Property xsi:type="StringProperty" Name="PersistOsDisk" Value="False" />
                                 <Property xsi:type="StringProperty" Name="PersistWBC" Value="False" />
                               </CustomProperties>
InitialBatchSizeHint     : 0
ProvisioningSchemeUid    : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
TaskState                     : Finished
TaskStateInformation     : Completed
TaskProgress             : 100
DiskSize                 : 50
MasterImageNote          :
PersonalVDiskDriveLetter :
PersonalVDiskDriveSize   : 0
WriteBackCacheDiskSize   : 0
WriteBackCacheMemorySize : 0
WriteBackCacheDriveLetter:
Scopes                   : {}
NetworkMaps              : {0}
ProvisioningSchemeMetadata    : {[ImageManagementPrep_DoImagePreparation, True], [ImageManagementPrep_Excluded_Steps, ], [ImageManagementPrep_NoAutoShutdown, False]}
ServiceOffering          : n1-standard-1.serviceoffering
SecurityGroups           : {}
DedicatedTenancy         : False
ResetAdministratorPasswords   : False
StatusMessageSubstitutions    :
GpuTypeId                :
UseFullDiskCloneProvisioning  : False
  • Update the BrokerCatalog with the unique Id of the provisioning scheme created previously
PS C:\TACG> Set-BrokerCatalog -Name 'MC-GCP-HibTest-PSH' -ProvisioningSchemeId 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`
  • Add controller addresses to the provisioning scheme object
PS C:\TACG> Add-ProvSchemeControllerAddress -AdminAddress 'tacg-dccc.gcp.the-austrian-citrix-guy.at' -ControllerAddress @('tacg-dccc.gcp.the-austrian-citrix-guy.at') -ProvisioningSchemeName 'MC-GCP-HibTest-PSH'
  • Create the required AD computer accounts in Active Directory
PS C:\TACG> New-AcctADAccount -Count 1 -IdentityPoolUid XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -ADUsername 'TACG-GCP\XXXXXXXXXXXXXX'

 SuccessfulAccounts SuccessfulAccountsCount FailedAccountsCount FailedAccounts
 ------------------ ----------------------- ------------------- --------------
 {TACG-GCP\GCP-Hib-PS-1}                  1                   0 {}
  • Create a Virtual Machine, based on the template definition in the previously created Provisioning Scheme
PS C:\TACG> New-ProvVM -ADAccountName @('TACG-GCP\GCP-Hib-PS-1\$')  -ProvisioningSchemeName 'MC-GCP-HibTest-PSH'

TaskId                         : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Active                         : False
Host                           : EA102823-4-2
DateStarted                    : 02.01.2024 14:31:39
Metadata                       : {}
Type                           : NewVirtualMachine
Status                         : Finished
CurrentOperation               :
TaskProgress                   : 100
TaskExpectedCompletion         : 02.01.2024 14:36:04
LastUpdateTime                 : 02.01.2024 14:36:04
ActiveElapsedTime              : 25
DateFinished                   : 02.01.2024 14:36:04
TerminatingError               :
WorkflowStatus                 : Completed
MasterImage                    : XDHyp:\HostingUnits\NW-TACG-GCP\instance-w10.vm
ProvisioningSchemeName         : MC-GCP
StatusMessageSubstitutions          :
ProvisioningSchemeUid          : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
PreparedImageVersionUid        : 00000000-0000-0000-0000-000000000000
TaskState                      : Finished
TaskStateInformation           : Completed
HostingUnitUid                 : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
HostingUnitName                : MC-GCP
IdentityPoolUid                : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
IdentityPoolName               : IP-GCP-HibTest-PSH
ProvisioningSchemeVersion      : 1
VirtualMachinesToCreateCount   : 0
VirtualMachinesCreatedCount    : 1
VirtualMachinesCreationFailedCount  : 0
CreatedVirtualMachines         : {GCP-Hib-PS-1\$}
FailedVirtualMachines          : {}
  • Create a Broker Machine object
PS C:\TACG> New-BrokerMachine -CatalogUid 23 -HostedMachineId 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' -HypervisorConnectionUid 27 -MachineName ' TACG-GCP\GCP-Hib-PS-1'

TaskId                         : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Active                         : False
Host                           : EA102823-4-2
DateStarted                    : 02.01.2024 14:35:39
Metadata                       : {}
Type                           : NewVirtualMachine
Status                         : Finished
CurrentOperation               :
TaskProgress                   : 100
TaskExpectedCompletion         : 02.01.2024 14:36:04
LastUpdateTime                 : 02.01.2024 14:36:04
ActiveElapsedTime              : 25
DateFinished                   : 02.01.2024 14:36:04
TerminatingError               :
WorkflowStatus                 : Completed
MasterImage                    : XDHyp:\HostingUnits\NW-TACG-GCP\instance-w10.vm
ProvisioningSchemeName         : MC-GCP-HibTest-PSH
StatusMessageSubstitutions          :
ProvisioningSchemeUid          : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
PreparedImageVersionUid        : 00000000-0000-0000-0000-000000000000
TaskState                      : Finished
TaskStateInformation           : Completed
HostingUnitUid                 : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
HostingUnitName                : MC-GCP
IdentityPoolUid                : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX4
IdentityPoolName               : IP-GCP-HibTest-PSH
ProvisioningSchemeVersion      : 1
VirtualMachinesToCreateCount   : 0
VirtualMachinesCreatedCount    : 1
VirtualMachinesCreationFailedCount : 0
CreatedVirtualMachines         : {TACG-GCP\GCP-Hib-PS-1\$}
FailedVirtualMachines          : {}
  • Check successful Virtual Machine creation
PS C:\TACG> Get-BrokerMachine -MachineName 'TACG-GCP\GCP-Hib-PS-1'

AgentVersion                : 2311.0.0.247
AllocationType              : Static
ApplicationsInUse           : {}
AssignedClientName          :
AssignedIPAddress           :
AssignedUserSIDs            : {}
AssociatedTenantId          :
AssociatedUserFullNames     : {}
AssociatedUserNames         : {}
AssociatedUserSIDs          : {}
AssociatedUserUPNs          : {}
AzureADJoinedMode           : NotAadJoined
AzureDeviceId               :
BrowserName                 :
Capabilities                : {}
CatalogName                 : MC-GCP
CatalogUUID                 : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
CatalogUid                  : 45
CbpVersion                  :
ColorDepth                  :
ControllerDNSName           :
DNSName                     : GCP-Hib-PS-1.gcp.the-austrian-citrix-guy.at
DeliveryType                :
Description                 :
DesktopConditions           : {}
DesktopGroupName            :
DesktopGroupUUID            :
DesktopGroupUid             :
DesktopKind                 :
DesktopUid                  :
DrainingUntilShutdown       : False
FaultState                  : None
FunctionalLevel             : L7_34
HostedMachineId             : tacg-gcp-406812:us-central1:GCP-Hib-PS-1
HostedMachineName           :
HostingServerName           :
HypHypervisorConnectionUid  : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
HypervisorConnectionName    : HC-TACG-GCP
HypervisorConnectionUid     : 37
IPAddress                   :
IconUid                     :
ImageOutOfDate              : False
InMaintenanceMode           : False
IsAssigned                  : False
IsPhysical                  : False
IsReserved                  : False
LastAssignmentTime          :
LastConnectionFailure       : None
LastConnectionTime          :
LastConnectionUser          :
LastDeregistrationReason    : AgentSuspended
LastDeregistrationTime      : 02.01.2024 13:47:36
LastErrorReason             :
LastErrorTime               :
LastHostingUpdateTime       : 03.01.2024 13:52:36
LastPvdErrorReason          :
LastPvdErrorTime            :
LastRegistrationTime        : 02.01.2024 13:46:58
LoadIndex                   :
LoadIndexes                 :
MacAddress                  : 42:01:0A:80:00:17
MachineInternalState        : Unregistered
MachineName                 : TACG-GCP\GCP-Hib-PS-1
MachineUnavailableReason    : None
MaintenanceModeReason       : None
MetadataMap                 : {}
NameLookupFailureCount      : 0
OSType                      : Windows 10
OSVersion                   : Microsoft Windows NT 10.0.19045.0
PersistUserChanges          : OnLocal
PowerActionPending          : False
PowerState                  : Unknown
ProvisioningType            : MCS
PublishedApplications       : {}
PublishedName               :
PvdEstimatedCompletionTime  :
PvdPercentDone              :
PvdStage                    : None
PvdUpdateStartTime          :
RegistrationState           : Unregistered
SID                         : S-1-5-21-3438202269-1249746449-2955890345-1107
ScheduledReboot             : None
SecureIcaRequired           :
SessionAutonomouslyBrokered :
SessionClientAddress        :
SessionClientName           :
SessionClientVersion        :
SessionConnectedViaHostName :
SessionConnectedViaIP       :
SessionCount                : 0
SessionDeviceId             :
SessionHardwareId           :
SessionHidden               :
SessionKey                  :
SessionLaunchedViaHostName  :
SessionLaunchedViaIP        :
SessionProtocol             :
SessionSecureIcaActive      :
SessionSmartAccessTags      :
SessionStartTime            :
SessionState                :
SessionStateChangeTime      :
SessionSupport              : SingleSession
SessionType                 :
SessionUid                  :
SessionUserName             :
SessionUserSID              :
SessionsEstablished         : 0
SessionsPending             : 0
SummaryState                : Unregistered
SupportedPowerActions       : {Reset, Restart, Resume, Shutdown...}
Tags                        : {}
UUID                        : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Uid                         : 21
VMToolsState                : NotStarted
WillShutdownAfterUse        : False
WillShutdownAfterUseReason  : None
WindowsConnectionSetting    : LogonEnabled
ZoneHealthy                 : False
ZoneName                    : The Austrian Citrix Guy - GCP
ZoneUid                     : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Creation of the Machine Catalog is now complete.

Creating a Hibernation-capable Machine Catalog using REST-API

After you meet all the requirements to use Hibernation, you can create a Hibernation-capable Machine Catalog using REST-API calls. The following prerequisites must be met:

  • Ensure that you have a valid bearer token.
    The step to obtain a Bearer-Token is the same as shown earlier.
  • Ensure that you have the siteid (How to get site id).
  • Ensure you have created a connection and resource pool in Hosting.
  • Ensure you have a domain administrator account encoded in UTF-8 and encoded as a Base64 string. You must set the X-AdminCredential using the encoded credentials.
    To get the X-AdminCredential right you have to follow a few steps:
    • Encode your Domain credentials separated by a colon (Username:Password) as UTF-8
    • Use the encoded UTF-8 string and encode it into a Base64 string
    • Put the Base64 string as a Header value into your REST API call.
      Key: X-AdminCredential
      Value: Basic {{Base64-String}}

REST-API-Call to create an GCP-based Machine Catalog

Note: As this call is done asynchronously we only get a 202 Accepted response.
For determining the progress or if an error occurred we need to periodically call the Job progress as mentioned later.

POST https://api-eu.cloud.com/cvad/manage/MachineCatalogs?async=true 

Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}
X-AdminCredential: Basic MjFceDIx…

Body:
{
    "Name": "MC-GCP",
    "AllocationType":"Static",
    "MinimumFunctionalLevel":"LMAX",
    "PersistUserChanges":"OnLocal",
    "ProvisioningType":"MCS",
    "IsPowerManaged": true,
    "SessionSupport":"SingleSession",
    "Scopes":["00000000-0000-0000-0000-000000000000"],
    "Tenants":[],
    "Zone":"The Austrian Citrix Guy - GCP",
    "VdaUpgradeType":"NotSet",
    "ProvisioningScheme":{
           "MasterImagePath":"XDHyp:\\HostingUnits\\NW-TACG-GCP\\instance-w10.vm",
        "CpuCount":null,
        "MemoryMB":null,
        "UseWriteBackCache":false,
        "NumTotalMachines":1,
        "NetworkMapping":[
            {"DeviceNameOrId":"default","NetworkDeviceNameOrId":"0",
            NetworkPath":"XDHyp:\\HostingUnits\\NW-TACG-GCP\\default.virtualprivatecloud\\default.network"
            }],
             "Metadata": [
            {
                "Name": "SupportsHibernation",
                "Value": "True"
            }
        ],
        "IdentityType":"ActiveDirectory",
        "MachineAccountCreationRules":{
            "NamingScheme":"GCP-W11-#","NamingSchemeType":"Numeric","Domain":"gcp.the-austrian-citrix-guy.at","OU":"CN=Computers,DC=gcp,DC=the-austrian-citrix-guy,DC=at"},
        "PrepareImage":true,
        "DedicatedTenancy":false,
        "SecurityGroups":null,
        "UseFullDiskCloneProvisioning":false,
        "CustomProperties":[  {
                "Name": "CryptoKeyId",
                "Value": ""
            },
            {
                "Name": "CatalogZones",
                "Value": "tacg-XXXXXXX:us-central1:a"
            },
            {
                "Name": "StorageType",
                "Value": "pd-standard"
            },
            {
                "Name": "IdentityDiskStorageType",
                "Value": "pd-standard"
            },
            {
                "Name": "WBCDiskStorageType",
                "Value": "pd-standard"
            },
            {
                "Name": "PersistOsDisk",
                "Value": "False"
            },
            {
                "Name": "PersistWBC",
                "Value": "False"
            }
       ],
        "ServiceOffering": "n1-standard-1", 
        "AdminFolder":"0"
}

REST-API-Call - Return if everything is correct:

1

Get the Job ID to monitor the progress

Therefore we have to search all jobs to find the current Job ID.
Due to the lots of jobs returned we can search the response for CreateMachineCatalog and the date and time.

REST-API-Call to get all jobs to determine current Job ID:

GET https://api-eu.cloud.com/cvad/manage/Jobs  

Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}

REST-API-Call - Return if everything is correct (shortened) - look for CreateMachineCatalog and the date and time:

...
        },
        {
            "Id": "4XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "Type": "CreateMachineCatalog",
            "OverallProgressPercent": 100,
            "IsCancellable": false,
            "Parameters": [
                {
                    "Name": "name",
                    "Value": "MC-EX-AZ-TZ"
                },
                {
                    "Name": "request",
                    "Value": ""
                },
                {
                    "Name": "ProgressDescriptionContents",
                    "Value": "Created 1 of 1 Virtual Machines."
                }
            ],
            "SubJobs": [
                {
                    "Id": "00000000-0000-0000-0000-000000000000",
                    "Type": "Unknown",
                    "OverallProgressPercent": 100,
                    "IsCancellable": false,
                    "Parameters": [
                        {
                            "Name": "ProgressDescriptionContents",
                            "Value": "Gathering required information"
                        }
                    ],
                    "SubJobs": null,
                    "Status": "Complete",
                    "ResultLocation": null,
                    "ErrorString": null,
                    "ErrorCode": "Unknown",
                    "ErrorParameters": null,
                    "CreationTime": "2024-01-02T13:22:36.504+00:00",
                    "FormattedCreationTime": "2024-01-02T13:22:36Z",
                    "StartTime": "2024-01-02T13:22:36.614+00:00",
                    "FormattedStartTime": "2024-01-02T13:22:36Z",
                    "EndTime": "2024-01-02T13:22:36.848+00:00",
                    "FormattedEndTime": "2024-01-02T13:22:36Z"
                },
...

The ID parameter contains the current Job ID we can further use.

Call the Job ID to being able to get the status

REST-API-Call to get the status of the current Job ID:

GET https://api-eu.cloud.com/cvad/manage/Jobs/xxxxxxxx-xxxxxx 

Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}

REST-API-Call - Return
The value of Status shows if the job completed successfully or not.
If Status is Complete then the creation of the Machine Catalog is completed.
If it is not, scroll through the response to determine where an error and which error occurred.

...
{
    "Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "Type": "CreateMachineCatalog",
    "OverallProgressPercent": 100,
    "IsCancellable": false,
    "Parameters": [
        {
            "Name": "name",
            "Value": "MC-GCP"
        },
        {
            "Name": "request",
            "Value": XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
        },
        {
            "Name": "ProgressDescriptionContents",
            "Value": "Created 1 of 1 Virtual Machines."
        }
    ],
    "SubJobs": [
        {
            "Id": "00000000-0000-0000-0000-000000000000",
            "Type": "Unknown",
            "OverallProgressPercent": 100,
            "IsCancellable": false,
            "Parameters": [
                {
                    "Name": "ProgressDescriptionContents",
                    "Value": "Gathering required information"
                }
            ],
            "SubJobs": null,
            "Status": "Complete",
            "ResultLocation": null,
            "ErrorString": null,
            "ErrorCode": "Unknown",
            "ErrorParameters": null,
            "CreationTime": "2024-01-02T13:22:36.504+00:00",
            "FormattedCreationTime": "2024-01-02T13:22:36Z",
            "StartTime": "2024-01-02T13:22:36.614+00:00",
            "FormattedStartTime": "2024-01-02T13:22:36Z",
            "EndTime": "2024-01-02T13:22:36.848+00:00",
            "FormattedEndTime": "2024-01-02T13:22:36Z"
        },
        {
            "Id": "00000000-0000-0000-0000-000000000000",
            "Type": "Unknown",
            "OverallProgressPercent": 100,
            "IsCancellable": false,
            "Parameters": [
                {
                    "Name": "ProgressDescriptionContents",
                    "Value": "Creating Machine Catalog"
                }
            ],
            "SubJobs": null,
            "Status": "Complete",
            "ResultLocation": null,
            "ErrorString": null,
            "ErrorCode": "Unknown",
            "ErrorParameters": null,
            "CreationTime": "2024-01-02T13:22:36.536+00:00",
            "FormattedCreationTime": "2024-01-02T13:22:36Z",
            "StartTime": "2024-01-02T13:22:36.848+00:00",
            "FormattedStartTime": "2024-01-02T13:22:36Z",
            "EndTime": "2024-01-02T13:22:37.651+00:00",
            "FormattedEndTime": "2024-01-02T13:22:37Z"
        },
        {
            "Id": "00000000-0000-0000-0000-000000000000",
            "Type": "Unknown",
            "OverallProgressPercent": 100,
            "IsCancellable": false,
            "Parameters": [
                {
                    "Name": "ProgressDescriptionContents",
                    "Value": "Creating Identity Pool"
                }
            ],
            "SubJobs": null,
            "Status": "Complete",
            "ResultLocation": null,
            "ErrorString": null,
            "ErrorCode": "Unknown",
            "ErrorParameters": null,
            "CreationTime": "2024-01-02T13:22:36.551+00:00",
            "FormattedCreationTime": "2024-01-02T13:22:36Z",
            "StartTime": "2024-01-02T13:22:37.866+00:00",
            "FormattedStartTime": "2024-01-02T13:22:37Z",
            "EndTime": "2024-01-02T13:22:42.857+00:00",
            "FormattedEndTime": "2024-01-02T13:22:42Z"
        },
        {
            "Id": "00000000-0000-0000-0000-000000000000",
            "Type": "Unknown",
            "OverallProgressPercent": 100,
            "IsCancellable": false,
            "Parameters": [
                {
                    "Name": "ProgressDescriptionContents",
                    "Value": "Copying the master image"
                }
            ],
            "SubJobs": null,
            "Status": "Complete",
            "ResultLocation": null,
            "ErrorString": null,
            "ErrorCode": "Unknown",
            "ErrorParameters": null,
            "CreationTime": "2024-01-02T13:22:36.599+00:00",
            "FormattedCreationTime": "2024-01-02T13:22:36Z",
            "StartTime": "2024-01-02T13:22:43.056+00:00",
            "FormattedStartTime": "2024-01-02T13:22:43Z",
            "EndTime": "2024-01-02T13:30:31.09+00:00",
            "FormattedEndTime": "2024-01-02T13:30:31Z"
        },
        {
            "Id": "00000000-0000-0000-0000-000000000000",
            "Type": "AddMachineCatalogMachine",
            "OverallProgressPercent": 100,
            "IsCancellable": false,
            "Parameters": [
                {
                    "Name": "ProgressDescriptionContents",
                    "Value": "Created 1 of 1 Virtual Machines."
                }
            ],
            "SubJobs": null,
            "Status": "Complete",
            "ResultLocation": null,
            "ErrorString": null,
            "ErrorCode": "Unknown",
            "ErrorParameters": null,
            "CreationTime": "2024-01-02T13:22:36.614+00:00",
            "FormattedCreationTime": "2024-01-02T13:22:36Z",
            "StartTime": "2024-01-02T13:30:31.293+00:00",
            "FormattedStartTime": "2024-01-02T13:30:31Z",
            "EndTime": "2024-01-02T13:31:07.65+00:00",
            "FormattedEndTime": "2024-01-02T13:31:07Z"
        }
    ],
    "Status": "Complete",
    "ResultLocation": "/Jobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Results",
    "ErrorString": null,
    "ErrorCode": "Unknown",
    "ErrorParameters": [],
    "CreationTime": "2024-01-02T13:22:25.086+00:00",
    "FormattedCreationTime": "2024-01-02T13:22:25Z",
    "StartTime": "2024-01-02T13:22:25.102+00:00",
    "FormattedStartTime": "2024-01-02T13:22:25Z",
    "EndTime": "2024-01-02T13:31:08.265+00:00",
    "FormattedEndTime": "2024-01-02T13:31:08Z"
}

...

Creation of the Machine Catalog using REST-API calls is now complete.

How to use Hibernation feature

Hibernation-capable Virtual Machines can be hibernated/deallocated in two different ways:

  1. Initiate Hibernation of the Virtual Machine via the Studio action menu

    • Full Configuration interface:
      • Select a Virtual Machine in the hibernation-capable Machine Catalog and select Start. -After the Power State is On, right-click the Virtual Machine, and select Suspend. Click Yes to confirm the action. -The Power State changes from Suspending to Suspended. -You can check the status of the Virtual Machine in the GCP portal.

  2. To resume and reconnect back to a hibernated/deallocated Virtual Machine, use one of the following:

    • Administrators can resume the Virtual Machine using the Full Configuration interface.
    • End users can start the Virtual Machine using the Citrix Workspace menu.

Note:

You can do the following Power Management operations on the hibernated/deallocated Virtual Machines: (Suspend Virtual Machine from the running state, Resume Virtual Machine from the suspended state, Force shut down Virtual Machine from a suspended state, and Force restart Virtual Machine from the suspended state)

deployment-guides-citrix-azure-powermanagment-hibernate1.png

Enabling and Configuring Autoscale using the Full Configuration Interface

Citrix Autoscale provides a consistent, high-performance solution to proactively Power Manage your machines. It aims to balance costs and user experience. Autoscale incorporates the deprecated Smart Scale technology into the Console’s Power Management solution.

Autoscale enables proactive power management of all registered single-session and multi-session OS machines in a delivery group. It supports all platforms that Citrix DaaS supports - Citrix Hypervisor, AWS, Google Cloud Platform, Microsoft Azure Resource Manager, VMware vSphere, and many more.

Autoscale powers on and off machines in a delivery group based on a schedule that you set. A schedule includes the number of active machines for each time slot, with peak and off-peak times defined.

Autoscale supports both multi-session OS and single-session OS delivery groups. There are three user interfaces to be aware of:

  • Autoscale user interface for multi-session OS delivery groups (formerly RDS delivery groups)
  • Autoscale user interface for single-session OS random (pooled) delivery groups (formerly pooled VDI delivery groups)
  • Autoscale user interface for single-session OS static delivery groups (formerly static VDI delivery groups)

For managing Virtual Machines with Azure Hibernation enabled keep in mind that currently only single-session OS delivery groups are supported.

Enabling Autoscale

  1. You can enable Autoscale by choosing the corresponding Delivery group and click Manage Autoscale.

    deployment-guides-citrix-azure-powermanagment-enable1.png

  2. In the next window click Enable autoscale.

    deployment-guides-citrix-azure-powermanagment-enable2.png

Basic concepts of Citrix Autoscale for Azure Hibernation-enabled Virtual Machines.

Schedules:

  • Autoscale powers machines on and off based on the selected schedule. Autoscale lets you set multiple schedules that include specific days of the week and adjust the number of machines available during those times. If you expect a set of users to consume the machine resources at a specific time on specific days, Autoscale helps provide an optimized experience.
  • The schedule is based on the time zone of the delivery group.
  • Autoscale treats only those machines that are registered with the site as part of the available capacity in the calculations it makes. “Registered” means that the machine is available for use or already in use. Doing so ensures that only machines that can accept user sessions are included in the capacity for the delivery group.

Note:

Those machines are powered on during the schedule, whether there are sessions running on them.

Capacity buffer:

  • A Capacity buffer is used to add spare capacity to the current demand to account for dynamic load increases.

Autoscale lets you set the capacity buffer separately for peak and off-peak times. A lesser value in the capacity buffer field decreases the cost because Autoscale powers on less spare capacity. A greater value ensures an optimized user experience so that users do not have to wait for more machines to power on when launching sessions. By default, the capacity buffer is 10%. For single-session OS delivery groups, the capacity buffer is defined as a percentage of the total number of machines in the delivery group.

Note:

The capacity buffer results in machines being powered on when the total spare capacity drops to a level below “X” percent of the total capacity of the delivery group. Doing so reserves the required percentage of spare capacity.

Power policies:

  • The Power policies control the behavior of the Autoscale depending on Session status:
    • The session on the Virtual Machine is disconnected. The Virtual Machine is put into hibernation or shuts down when the specified disconnection time elapses, depending on the action you configured (the action to choose to put the machine into Hibernation is “Suspend”). By default, no action is assigned to disconnected machines. You can define actions separately for peak and off-peak times.

The session is logged off:

  • The Virtual Machine is suspended or shut down when the specified logoff time elapses, depending on the actions you configured (the action to choose to put the machine into Hibernation is “Suspend”). By default, no action is assigned to logged-off machines. You can define actions separately for peak and off-peak times.

deployment-guides-citrix-azure-powermanagment-enable3.png

Setting the Peak Times on the schedule:

  • You can set the Peak Times in 30min-intervals by clicking in the time-schedule. Each blue frame represents a timeslot marked as Peak Time. The Peak Times need not to be consecutive, non-consecutive timeslots are possible.

deployment-guides-citrix-azure-powermanagment-enable4.png

  • Non-consecutive timeslots are possible.

deployment-guides-citrix-azure-powermanagment-enable5.png

Enabling and Configuring Autoscale using PowerShell

  1. First we check whether Autoscale is already activated in the respective desktop group.

        Get-BrokerDesktopGroup -Name "BG-AZ-HibTest" | Select AutoscalingEnabled

    deployment-guides-citrix-azure-powermanagment-enable6.png

  2. If it is not enabled we can enable it.

        Get-BrokerDesktopGroup -Name "BG-AZ-HibTest"  -AutoscalingEnabled $true

  3. Check if a schedule is already configure by getting the Uid and then using the Get-BrokerPowerTimeScheme command.

        Get-BrokerDesktopGroup -Name "BG-AZ-HibTest" | Select Uid

    Get-BrokerPowerTimeScheme -DesktopGroupuid <Your Uid #.>

    deployment-guides-citrix-azure-powermanagment-enable7.png

  4. To create a schedule the syntax of the script is important to know:

    • The time slots representing the Peak Hours are created in 30min-based time frames starting to count at 0 representing 12pm.
    • If the Peak Hours are between 9am and 5pm we must set the time slots 18 (9am) to 34 (5pm).

    deployment-guides-citrix-azure-powermanagment-enable8.png

  5. The schedule is now created and enabled.

    Note:

    The script produces an error if another schedule has the same time slots marked as Peak Times!

  6. Now we can set the other important settings like Capacity Buffer, Power-Off delay.

        Set-BrokerDesktopGroup -Name "BG-AZ-HibTest" -PeakBufferSizePercent 0` -OffPeakBufferSizePercent 0

    Set-BrokerDesktopGroup -Name "BG-AZ-HibTest" -PowerOffDelay 1

  7. At last we must set the Power policies. As we want to hibernate/deallocate all Virtual Machines when not in use we set the action to “Suspend” and the time before the action occurs to one minute.

        Set-BrokerDesktopGroup -Name "BG-AZ-HibTest" -PeakLogoffTimeout 1 -PeakLogOffAction Suspend
    Set-BrokerDesktopGroup -Name "BG-AZ-HibTest" -PeakDisconnectTimeout 1 -PeakDisconnectAction Suspend
    Set-BrokerDesktopGroup -Name "BG-AZ-HibTest" -OffPeakLogoffTimeout 1 -OffPeakLogOffAction Suspend
    Set-BrokerDesktopGroup -Name "BG-AZ-HibTest" -OffPeakDisconnectTimeout 1 -OffPeakDisconnectAction Suspend

  8. Now all relevant Autoscale settings for hibernating Azure-based Virtual Machines are set and active.

Enabling and Configuring Autoscale using REST-API

In the following snippets we assume that the Bearer Token for Authentication of each REST-API-Call is valid.

  • First we check whether Autoscale is already activated in the respective desktop group:

    GET https://api-eu.cloud.com/cvad/manage/Deliverygroups/BG-AZ-HibTest

Authorization: Bearer {{Bearer-Token-Value}} Citrix-CustomerId: {{Citrix-CustomerID}} Citrix-InstanceID: {{Citrix-SiteID}}



Response shortened:
{
"AppAccessPolicy": null,
"AppProtectionKeyLoggingRequired": false,
"AppProtectionScreenCaptureRequired": false,
"AutomaticPowerOnForAssigned": true,
"AutomaticPowerOnForAssignedDuringPeak": false,
"AutoScaleEnabled": true,
"RestrictAutoscaleTag": null,
"ColorDepth": "TwentyFourBit",
"DefaultDesktopIconId": "1",
"DefaultDesktopPublishedName": "BG-AZ-HibTest",
"DesktopsInUse": 0,
"DesktopsNeverRegistered": 0,
"DesktopsPreparing": 0,
"HdxSslEnabled": null,
"IsPowerManaged": true,


...  


-  If Autoscale is not enabled, you can enable it using a `PATCH` call:



PATCH https://api-eu.cloud.com/cvad/manage/Deliverygroups/BG-AZ-HibTest


Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}
Raw Body:  


{
"AutoScaleEnabled": "true"
}


Response:
Response code `204` No Content means successful completion.

-  Check if a schedule is already configured:



GET api-eu.cloud.com/cvad/manage/Deliverygroups/BG-AZ-HibTest/PowerTimeSchemes


Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}


Response:



{
"Items": [
{
"DaysOfWeek": [
"Saturday",
"Sunday"
],
"Name": "BG-AZ-HibTest_Weekend",
"DisplayName": "Weekend",
"PeakHours": null,
"PeakTimeRanges": [],
"PoolSize": null,
"PoolSizeSchedule": [],
"PoolUsingPercentage": false,
"Id": "28"
},
{
"DaysOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"Name": "PSWeekdays",
"DisplayName": "PSWeekdays",
"PeakHours": null,
"PeakTimeRanges": [
"08:00-19:00"
],
"PoolSize": null,
"PoolSizeSchedule": null,
"PoolUsingPercentage": false,
"Id": "33"
}
]
}


A new schedule can only be configured if there are no coincidences regarding the `Peak Time` settings otherwise an error occurs!

-  Assuming the Peak Times are not set, a schedule can be created



POST api-eu.cloud.com/cvad/manage/Deliverygroups/BG-AZ-HibTest/PowerTimeSchemes


Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}
Raw Body:
{
"DaysOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"Name": "APIWeekdays",
"DisplayName": "APIWeekdays",
"PeakTimeRanges": [
"09:00-17:00"
],
"PoolSizeSchedule": [
{
"TimeRange": "00:00-08:00",
"PoolSize": 0
}
],
"PoolUsingPercentage": false
}


Response:



{
"DaysOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"Name": "APIWeekdays",
"DisplayName": "APIWeekdays",
"PeakHours": null,
"PeakTimeRanges": [
"09:00-17:00"
],
"PoolSize": null,
"PoolSizeSchedule": [],
"PoolUsingPercentage": false,
"Id": "39"
}


-  Check if Power Policies are set



GET api-eu.cloud.com/cvad/manage/Deliverygroups/BG-AZ-HibTest/


Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}
Raw Body:
{
}


Response (shortened):



{
"MachineOperatingSystems": [
{
"Name": "Windows 10",
"Value": 1
}
],
"MachineType": "Unknown",
"OffMachines": 0,
"OffPeakBufferSizePercent": 0,
"OffPeakDisconnectAction": "Suspend",
"OffPeakDisconnectTimeoutMinutes": 1,
"OffPeakExtendedDisconnectAction": "Nothing",
"OffPeakExtendedDisconnectTimeoutMinutes": 0,
"OffPeakLogOffAction": "Suspend",
"OffPeakLogOffTimeoutMinutes": 1,
"PeakAutoscaleAssignedPowerOnIdleTimeoutMinutes": 0,
"PeakAutoscaleAssignedPowerOnIdleAction": "Nothing",
"PeakBufferSizePercent": 0,
"PeakDisconnectAction": "Suspend",
"PeakDisconnectTimeoutMinutes": 1,
"PeakExtendedDisconnectAction": "Nothing",
"PeakExtendedDisconnectTimeoutMinutes": 0,
"PeakLogOffAction": "Suspend",
"PeakLogOffTimeoutMinutes": 1,
}


-  Assuming there are no Power Policies set, we can set some:

A response code of “204 No Content” means successful completion.  



PATCH https://api-eu.cloud.com/cvad/manage/Deliverygroups/BG-AZ-HibTest


Authorization:      Bearer  {{Bearer-Token-Value}}
Citrix-CustomerId: {{Citrix-CustomerID}}
Citrix-InstanceID: {{Citrix-SiteID}}
Raw Body:
{
"OffPeakDisconnectAction": "Suspend",
"OffPeakDisconnectTimeoutMinutes": 2,
"OffPeakLogOffAction": "Suspend",
"OffPeakLogOffTimeoutMinutes": 2,
"PeakDisconnectAction": "Suspend",
"PeakDisconnectTimeoutMinutes": 2,
"PeakLogOffAction": "Suspend",
"PeakLogOffTimeoutMinutes": 2
}


Response:



Response:
Response code 204 No Content 



Now all relevant Autoscale settings for hibernating Virtual Machines using Autoscale are set and active.

## Troubleshooting guide

Look at the Troubleshooting guide in the Google Cloud Documentation:
[https://cloud.google.com/compute/docs/troubleshooting/troubleshooting-suspend-resume?hl=en](https://cloud.google.com/compute/docs/troubleshooting/troubleshooting-suspend-resume?hl=en)

		
		
	



    
  










	
	
User Feedback

	


	



	
		
			

				


	

	
	

		
			
There are no comments to display.

		
	

	
	
		


		

			
				
				



	
	
		

			
				
Create an account or sign in to comment

				
You need to be a member in order to leave a comment

			
	
			

				

					

						
Create an account

						
Sign up for a new account in our community. It's easy!

						
							
						
						Register a new account
					

					

						
Sign in

						
Already have an account? Sign in here.

						Sign In Now
					

				

			

		

	



			
		

	


			

		
	











      

    

  





            


          

          


          

        

      
      
    

    
    

      

        

          

            
            
            
            
            
          

          

            
            
©  Cloud Software Group, Inc. All rights reserved.

          

        

      

    

    


	

		×
		

			
				

					
				

			

			

			

			
		

	






	

		×
		

			
    
				
  • Create New...
    •