Product documentation
Citrix DaaS
View PDF

Dynamically provision machines

November 1, 2022
Contributed by: 
C R

Autoscale provides the capability to create machines and delete them dynamically. You can leverage the capability by using a PowerShell script. The script helps you dynamically scale up or down the number of machines in the delivery group based on the current load conditions.

The script offers the following benefits (and more):

  • Reducing storage costs. Different from Autoscale, which helps reduce your computing costs, the script provides a more cost-effective solution to provision machines.

  • Effectively handling load changes. The script helps you handle load changes by automatically scaling up or down the number of machines based on the current delivery group load.

Download the script

The PowerShell script is available at https://github.com/citrix/Powershell-Scripts/tree/master/XAXD/AutoscaleMcs.

How the script works

Important:

  • You cannot specify a machine catalog in more than one delivery group that is to be managed by the script. In other words, if multiple delivery groups share the same machine catalog, the script does not work with any of those delivery groups.
  • You cannot concurrently run the script for the same delivery group from multiple locations.

The script works at a delivery group level. It measures the load (in terms of load index) and then determines whether to create or delete machines.

Machines created through this script are uniquely tagged (through the ScriptTag parameter) so that they can be identified later. Creating or deleting machines is based on:

  • Maximum percentage load of a delivery group. Specifies the maximum level at which to create machines for Autoscale to address extra loads. When this threshold is exceeded, machines are created in batches to ensure that the current load decreases to or below the threshold.

  • Minimum percentage load of a delivery group. Specifies the minimum level at which to delete machines created through this script that have no active sessions. When this threshold is exceeded, machines created through this script that have no active sessions are deleted.

This script is intended to monitor across a delivery group and to create or delete machines when the trigger criterion is met. It executes on a per-run basis. This means that you need to run the script on a regular basis so that it can function as intended. We recommend that you run the script at a minimum interval of five minutes. Doing so improves overall responsiveness.

The script relies on the following parameters to work:

Parameter Type Default value Description
DeliveryGroupName String X Name of the delivery group to be monitored to determine the current load. You can provide a semicolon-separated list of names. For example: Invoke-AutoscaleMachineCreation.ps1 -DeliveryGroupName 'dg1;dg2;dg3' -XdProfileName profile.
XdProfileName String X Name of the profile to use for authenticating to remote servers. For details about authenticating to remote servers using this parameter, see Authentication API.
HighWatermark Integer 80 Maximum percentage load (in terms of load index) at which to create machines for Autoscale to address extra loads.
LowWatermark Integer 15 Minimum percentage load (in terms of load index) at which to delete machines created through this script that have no active sessions.
MachineCatalogName String X Name of the machine catalog where machines are to be created.
MaximumCreatedMachines Integer -1 Maximum amount of machines that can be created in a specified delivery group. If the value is equal to or less than 0, the script does not process this parameter.
ScriptTag String AutoscaledScripted Tag that applies to machines created through the script.
EventLogSource String X Source name that appears in Windows Event Viewer.

Note:

An “X” indicates that no default value is specified for that parameter.

By default, the script requires all parameters (except the ScriptTag parameter) the first time it runs. On subsequent runs, only the DeliveryGroupName and the XdProfileName parameters are required. Optionally, you can choose to update the minimum and maximum percentage loads.

Note that you must specify a single delivery group the first time you run the script. For example, the script does not work if you use the following PowerShell command to specify two delivery groups the first time you run the script:

  • Invoke-AutoscaleMachineCreations.ps1 -DeliveryGroupName 'dg1;dg2' -XdProfileName profile -LowWatermark 20 -HighWatermark 70 -MachineCatalogName 'cat1'\

Instead, first specify a single delivery group (in this example, dg1) using the following command:

  • Invoke-AutoscaleMachineCreations.ps1 -DeliveryGroupName 'dg1' -XdProfileName profile -LowWatermark 20 -HighWatermark 70 -MachineCatalogName 'cat1'\

Then, use the following command to run the script for the second delivery group (in this example, dg 2):

  • Invoke-AutoscaleMachineCreations.ps1 -DeliveryGroupName 'dg1;dg2' -XdProfileName profile

Prerequisites

To run the script, make sure that these prerequisites are met:

  • The machine resides within the same domain where machines are being created.
  • Remote PowerShell SDK is installed on that machine. For more information about the Remote PowerShell SDK, see SDKs and APIs.
  • Other prerequisites:
    • A delivery group to monitor
    • A machine catalog created through Machine Creation Services (MCS) that has an associated provisioning scheme (template)
    • An identity pool that is associated with the provisioning scheme
    • An event log source to be created so that the script can write information to the Windows Event Log
    • A secure client that allows you to authenticate to remote servers

Permissions, recommendations, and notices

When you run the script, keep the following in mind:

  • To authenticate to remote servers using the XdProfileName parameter, you need to define an authentication profile by using an API access secure client, created in the Citrix Cloud console. For details, see Authentication API.

  • You must have permissions to create and delete machine accounts in Active Directory.

  • We recommend that you automate the PowerShell script with Windows Task Scheduler. For details, see Create an automated task using Windows Task Scheduler.

  • If you want the script to write information (for example, failures and actions) to the Windows Event Log, you need to first specify a source name using the New-EventLog cmdlet. For example, New-EventLog -LogName Application –Source <sourceName>. You can then view the events in the Application pane of Windows Event Viewer.

  • If errors occurred during execution of the script, execute the script manually and then troubleshoot problems by performing script checks.

Authentication API

Before you run the script, you need to define an authentication profile by using an API access secure client. You must create a secure client using the same account under which the script will run.

The secure client must have the following permissions:

  • Create and delete machines using MCS.
  • Edit machine catalogs (to add and remove machines).
  • Edit delivery groups (to add and remove machines).

When you create a secure client, make sure that your account has the permissions above because the secure client automatically inherits the permissions from your current account.

To create a secure client, complete these steps:

  1. Sign in to Citrix Cloud and then navigate to Identity and Access Management > API Access.

  2. Type the name for your secure client and then click Create Client.

To authenticate to remote servers, use the Set-XDCredentials PowerShell command. For example:

  • Set-XDCredentials -APIKey <key_id> -CustomerId <customer_id> -SecretKey <secret_key> -StoreAs <name specified by the XdProfileName parameter>

Create an automated task using Windows Task Scheduler

You can automate the PowerShell script with Windows Task Scheduler. Doing so lets the script run automatically at certain intervals or when certain conditions are met. To execute this script with Windows Task Scheduler, make sure to select Do not start a new instance on the Create Task > Settings tab. Doing so prevents the Windows Task Scheduler from running a new instance of the script if the script is already running.

Script execution example

See below for an example of executing the script. Note that the script file is invoked multiple times. In this example, to simulate the load, one session is launched and then terminated.

Script Execution Example

Troubleshooting checklist for the script

The script writes information (for example, errors and actions) to the Windows Event Log. The information helps you troubleshoot issues you experience when executing the script. It might be helpful to keep the following troubleshooting checklist in mind:

  • Failure to communicate with remote servers. Possible actions:
    • Verify your connection to the server.
    • Verify that the API key you use is valid.
  • Failure to create machines. Possible actions:
    • Verify that the user account running the script has sufficient permissions to create user accounts in the domain.
    • Verify that the user who created the API key has sufficient permissions to use MCS to provision machines.
    • Verify the validity of the machine catalog (that is, its image still exists and is in good state).
  • Failure to add machines to a machine catalog or a delivery group. Possible action:
    • Verify that the user who created the API key has sufficient permissions to add and remove machines to and from machine catalogs and delivery groups.
Dynamically provision machines
November 1, 2022
Contributed by: 
C R
November 1, 2022
Contributed by: 
C R

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.