Get started with Workload Balancing

You can configure the Workload Balancing virtual appliance in just a few steps:

1. Review the prerequisite information and plan your Workload Balancing usage.

2. Download the Workload Balancing virtual appliance.

3. Import the Workload Balancing virtual appliance into XenCenter.

4. Configure Workload Balancing virtual appliance from the virtual appliance console.

5. (Optional) If you already have a previous version of Workload Balancing installed, you can migrate data from an existing virtual appliance.

   Note:

   If you perform a rolling pool upgrade from Citrix Hypervisor 8.2 CU1 to XenServer 8, you cannot use Workload Balancing 8.2.2 and earlier with your XenServer 8 pools. Update your Workload Balancing virtual appliance to version 8.3.0 before performing the rolling pool upgrade. You can download the latest version of the Workload Balancing virtual appliance from the XenServer Downloads page.

6. Connect your pool to the Workload Balancing virtual appliance by using XenCenter.

   The Workload Balancing tab only appears in XenCenter if your pool has the required license to use Workload Balancing.

Before you start

The Workload Balancing virtual appliance is a single pre-installed VM designed to run on a XenServer host. Before importing it, review the prerequisite information and considerations.

Prerequisites

• Workload Balancing 8.3.0 and later are compatible with XenServer 8. We recommend using the XenCenter management console to import the virtual appliance.

• If you perform a rolling pool upgrade from Citrix Hypervisor 8.2 CU1 to XenServer 8, you cannot use Workload Balancing 8.2.2 and earlier with your XenServer 8 pools. Update your Workload Balancing virtual appliance to version 8.3.0 before performing the rolling pool upgrade. You can download the latest version of the Workload Balancing virtual appliance from the XenServer Downloads page.

• If you are currently using an earlier version of the Workload Balancing virtual appliance, you can use the migrate script to migrate your existing data when you upgrade to the latest version. For more information, see Migrate from an existing virtual appliance.

• The Workload Balancing virtual appliance requires a minimum of 2 GB of RAM and 30 GB of disk space to run. By default, the Workload Balancing virtual appliance is assigned 2 vCPUs. This value is sufficient for pools hosting 1000 VMs. You do not usually need to increase it. Only decrease the number of vCPUs assigned to the virtual appliance if you have a small environment. For more information, see Change the Workload Balancing virtual appliance configuration.

Pool requirements

To balance a pool with Workload Balancing, the pool must meet the following requirements:

• All hosts are licensed with a Premium Edition license

• All hosts meet the requirements for live migration:

  • Shared remote storage

  • Similar processor configurations

  • Gigabit Ethernet

• The pool does not contain any vGPU-enabled VMs. Workload Balancing cannot create a capacity plan for VMs that have vGPUs attached.

A single Workload Balancing virtual appliance can manage multiple pools up to a maximum of 100 pools, depending on the virtual appliance’s resources (vCPU, memory, disk size). Across these pools, the virtual appliance can manage up to 1000 VMs. However, if a pool has a large number of VMs (for example, more than 400 VMs), we recommend that you use one Workload Balancing virtual appliance just for that pool.

Considerations

Before importing the virtual appliance, note the following information and make the appropriate changes to your environment, as applicable.

• Communications port. Before you launch the Workload Balancing Configuration wizard, determine the port over which you want the Workload Balancing virtual appliance to communicate. You are prompted for this port during Workload Balancing Configuration. By default, the Workload Balancing server uses 8012.

  Note:

  Do not set the Workload Balancing port to port 443. The Workload Balancing virtual appliance cannot accept connections over port 443 (the standard TLS/HTTPS port).

• Accounts for Workload Balancing. There are three different accounts that are used when configuring your Workload Balancing virtual appliance and connecting it to XenServer.

  The Workload Balancing Configuration wizard creates the following accounts with a user name and password that you specify:

  • Workload Balancing account

    This account is used by the XenServer host to connect to the Workload Balancing server. By default, the user name for this account is wlbuser. This user is created on the Workload Balancing virtual appliance during Workload Balancing configuration.

  • Database account

    This account is used to access the PostgreSQL database on the Workload Balancing virtual appliance. By default, the user name is postgres. You set the password for this account during Workload Balancing configuration.

  When connecting the Workload Balancing virtual appliance to a XenServer pool, you must specify an existing account:

  • XenServer account

    This account is used by the Workload Balancing virtual appliance to connect to the XenServer pool and read the RRDs. Ensure that this user account has the permissions to read the XenServer pool, host, and VM RRDs. For example, provide the credentials for a user that has the pool-admin or pool-operator role.

• Monitoring across pools. You can put the Workload Balancing virtual appliance in one pool and monitor a different pool with it. (For example, the Workload Balancing virtual appliance is in Pool A but you are using it to monitor Pool B.)

• Time synchronization. The Workload Balancing virtual appliance requires that the time on the physical computer hosting the virtual appliance matches that in use by the monitored pool. There is no way to change the time on the Workload Balancing virtual appliance. We recommend pointing both the physical computer hosting Workload Balancing and the hosts in the pool it is monitoring to the same Network Time (NTP) server.

• XenServer and Workload Balancing communicate over HTTPS. Therefore, during Workload Balancing Configuration, Workload Balancing automatically creates a self-signed certificate on your behalf. You can change this certificate to one from a certificate authority or configure XenServer to verify the certificate or both. For information, see the Certificates.

• Storing historical data and disk space size. The amount of historical data you can store is based on the following:

  • The size of the virtual disk allocated to Workload Balancing (by default 30 GB)
  • The minimum disk required space, which is 2,048 MB by default and controlled by the GroomingRequiredMinimumDiskSizeInMB parameter in the wlb.conf file.

  The more historical data Workload Balancing collects, the more accurate and balanced the recommendations are. If you want to store much historical data, you can do one of the following:

  • Archive the data as described in Archive database data
  • Make the virtual disk size assigned to the Workload Balancing virtual appliance larger as described in Extend the virtual appliance disk

  For example, when you want to use the Workload Balancing Pool Audit trail feature and configure the report granularity to medium or above.

• Load balancing Workload Balancing. If you want to use your Workload Balancing virtual appliance to manage itself, specify shared remote storage when importing the virtual appliance.

  Note:

  Workload Balancing cannot perform Start On placement recommendation for the Workload Balancing virtual appliance when you are using Workload Balancing to manage itself. The reason that Workload Balancing cannot make placement recommendations when it is managing itself is because the virtual appliance must be running to perform that function. However, it can balance the Workload Balancing virtual appliance just like it would balance any other VM it is managing.

• Plan for resource pool sizing. Workload Balancing requires specific configurations to run successfully in large pools. For more information, see Change the Workload Balancing virtual appliance configuration.

Download the virtual appliance

The Workload Balancing virtual appliance is packaged in an .xva format. You can download the virtual appliance from the XenServer Downloads page. When downloading the file, save it to a folder on your local hard drive (typically on the computer where XenCenter is installed).

When the .xva download is complete, you can import it into XenCenter as described in Import the Workload Balancing virtual appliance.

Import the Workload Balancing virtual appliance

Use XenCenter to import the Workload Balancing virtual appliance into a pool.

To import the virtual appliance into XenServer:

1. Open XenCenter.
2. Right-click on the pool (or host) into which you want to import the virtual appliance package, and select Import.
3. Browse to the vpx-wlb.xva package.

4. Select the pool or Home Server where you want to run the Workload Balancing virtual appliance.

   When you select the pool, the VM automatically starts on the most suitable host in that pool.

   Alternatively, if you don’t manage the Workload Balancing virtual appliance using Workload Balancing, you can set a Home Server for the Workload Balancing virtual appliance. This setting ensures that the virtual appliance always starts on the same host.

5. Choose a storage repository on which to store the virtual disk for the Workload Balancing virtual appliance. This repository must have a minimum of 30 GB of free space.

   You can choose either local or remote storage. However, if you choose local storage, you cannot manage the virtual appliance with Workload Balancing.

6. Define the virtual interfaces for the Workload Balancing virtual appliance. In this release, Workload Balancing is designed to communicate on a single virtual interface.
7. Choose a network that can access the pool you want Workload Balancing to manage.
8. Leave the Start VMs after import check box enabled, and click Finish to import the virtual appliance.
9. After you finish importing the Workload Balancing .xva file, the Workload Balancing VM appears in the Resource pane in XenCenter.

After importing the Workload Balancing virtual appliance, configure the virtual appliance as described in Configure the Workload Balancing virtual appliance.

Configure the Workload Balancing virtual appliance

After you finish importing the Workload Balancing virtual appliance, you must configure it before you can use it to manage your pool. To guide you through the configuration, the Workload Balancing virtual appliance provides you with a configuration wizard in XenCenter. To display it, select the virtual appliance in the Resource pane and click the Console tab. For all options, press Enter to accept the default choice.

1. After importing the Workload Balancing virtual appliance, click the Console tab.

2. Enter yes to accept the terms of the license agreement. To decline the EULA, enter no.

   Note:

   The Workload Balancing virtual appliance is also subject to the licenses contained in the /opt/vpx/wlb directory in the Workload Balancing virtual appliance.

3. Enter and confirm a new root password for the Workload Balancing VM. We recommend selecting a strong password.

   Note:

   When you enter the password, the console does not display placeholders, such as asterisks, for the characters.

4. If connecting a pool using the FQDN of the Workload Balancing virtual appliance, enter the desired computer name for the appliance. If using the IP address, leave this field blank.

5. If connecting using the FQDN, enter the domain suffix for the virtual appliance. If using the IP address, leave this field blank.

   For example, if the fully qualified domain name (FQDN) for the virtual appliance is wlb-vpx-pos-pool.domain4.bedford4.ctx, enter domain4.bedford4.ctx.

   Note:

   The Workload Balancing virtual appliance does not automatically add its FQDN to your Domain Name System (DNS) server. Therefore, if you want the pool to use an FQDN to connect to Workload Balancing, you must add the FQDN to your DNS server.

6. Enter y to use DHCP to obtain the IP address automatically for the Workload Balancing VM. Otherwise, enter n and then enter a static IP address, subnet mask, and gateway for the VM.

   Note:

   Using DHCP is acceptable provided the lease of the IP address does not expire. It is important that the IP address does not change: When it changes, it breaks the connection between XenServer and Workload Balancing.

7. Enter a user name for the Workload Balancing database, or press Enter to use the default user name (postgres) of the database account.

   Note:

   We recommend to use the default user name postgres due to a known issue where you cannot connect your pools to the Workload Balancing virtual appliance if you do not use the default user name for the Workload Balancing PostgreSQL database.

   You are creating an account for the Workload Balancing database. The Workload Balancing services use this account to read/write to the Workload Balancing database. Note the user name and password. You might need them if you ever want to administer to the Workload Balancing PostgreSQL database directly (for example, if you wanted to export data).

8. Enter a password for the Workload Balancing database. After pressing Enter, messages appear stating that the Configuration wizard is loading database objects.

9. Enter a user name and password for the Workload Balancing Server.

   This action creates the account XenServer uses to connect to Workload Balancing. The default user name is wlbuser.

10. Enter the port for the Workload Balancing Server. The Workload Balancing server communicates by using this port.

    By default, the Workload Balancing server uses 8012. The port number cannot be set to 443, which is the default TLS port number.

    Note:

    If you change the port here, specify that new port number when you connect the pool to Workload Balancing. For example, by specifying the port in the Connect to WLB Server dialog.

    Ensure that the port you specify for Workload Balancing is open in any firewalls.

    After you press Enter, Workload Balancing continues with the virtual appliance configuration, including creating self-signed certificates.

11. Now, you can also log in to the virtual appliance by entering the VM user name (typically root) and the root password you created earlier. However, logging in is only required when you want to run Workload Balancing commands or edit the Workload Balancing configuration file.

After configuring Workload Balancing, connect your pool to the Workload Balancing virtual appliance as described in Connect to the Workload Balancing virtual appliance.

If necessary, you can find the Workload Balancing configuration file in the following location: /opt/vpx/wlb/wlb.conf. For more information, see Edit the Workload Balancing configuration file

The Workload Balancing log file is in this location: /var/log/wlb/LogFile.log. For more information, see Increase the detail in the Workload Balancing log.

Connect to the Workload Balancing virtual appliance

After configuring Workload Balancing, connect the pools you want managed to the Workload Balancing virtual appliance by using either the CLI or XenCenter.

Note:

A single Workload Balancing virtual appliance can manage multiple pools up to a maximum of 100 pools, depending on the virtual appliance’s resources (vCPU, memory, disk size). Across these pools, the virtual appliance can manage up to 1000 VMs. However, if a pool has a large number of VMs (for example, more than 400 VMs), we recommend that you use one Workload Balancing virtual appliance just for that pool.

To connect a pool to your Workload Balancing virtual appliance, you need the following information:

• IP address or FQDN of the Workload Balancing virtual appliance

  • To obtain the IP address for the Workload Balancing virtual appliance:

    1. In XenCenter, go to the Workload Balancing virtual appliance Console tab.
    2. Log in as root with the root password you created when you imported the appliance.
    3. Run the following command: ifconfig.

  • To specify the Workload Balancing FQDN when connecting to the Workload Balancing server, first add its host name and IP address to your DNS server.

• The port number of the Workload Balancing virtual appliance. By default, XenServer connects to Workload Balancing on port 8012.

  Only edit the port number when you have changed it during Workload Balancing Configuration. The port number specified during Workload Balancing Configuration, in any firewall rules, and in the Connect to WLB Server dialog must match.

• Credentials for the Workload Balancing account you created during Workload Balancing configuration.

  This account is often known as the Workload Balancing user account. XenServer uses this account to communicate with Workload Balancing. You created this account on the Workload Balancing virtual appliance during Workload Balancing Configuration.

• Credentials for the resource pool (that is, the pool coordinator) you want Workload Balancing to monitor.

  This account is used by the Workload Balancing virtual appliance to connect to the XenServer pool. This account is created on the XenServer pool coordinator and has the pool-admin or pool-operator role.

When you first connect to Workload Balancing, it uses the default thresholds and settings for balancing workloads. Automatic features, such as Automated Optimization Mode, Power Management, and Automation, are disabled by default.

Working with certificates

If you want to upload a different (trusted) certificate or configure certificate verification, note the following before connecting your pool to Workload Balancing:

• If you want XenServer to verify the self-signed Workload Balancing certificate, you must use the Workload Balancing IP address to connect to Workload Balancing. The self-signed certificate is issued to Workload Balancing based on its IP address.

• If you want to use a certificate from a certificate authority, it is easier to specify the FQDN when connecting to Workload Balancing. However, you can specify a static IP address in the Connect to WLB Server dialog. Use this IP address as the Subject Alternative Name (SAN) in the certificate.

Certificate verification is enabled by default on your pool. Disable certificate verification if your pool can’t connect to Workload Balancing:

1. Get the pool UUID:

   xe pool-list
   <!--NeedCopy-->
   

2. Disable certificate verification:

   xe pool-param-set wlb-verify-cert=false uuid=uuid_of_pool
   <!--NeedCopy-->
   

If your pool can connect to Workload Balancing with certificate verification turned off, the issue is with your certificate configuration. If it cannot connect, the issue is with either your Workload Balancing credentials or your network connection. Contact Support or see Troubleshoot Workload Balancing for more information.

For more information, see Certificates.

To connect your pool to the Workload Balancing virtual appliance

1. In XenCenter, select your resource pool and in its Properties pane, click the WLB tab. The WLB tab displays the Connect button.

   

2. In the WLB tab, click Connect. The Connect to WLB Server dialog box appears.

   

3. In the Server Address section, enter the following:

   1. In the Address box, type the IP address or FQDN of the Workload Balancing virtual appliance. For example, WLB-appliance-computername.yourdomain.net.

   2. (Optional) If you changed the Workload Balancing port during Workload Balancing Configuration, enter the port number in the Port box. XenServer uses this port to communicate with Workload Balancing.

      By default, XenServer connects to Workload Balancing on port 8012.

4. In the WLB Server Credentials section, enter the user name and password that the pool uses to connect to the Workload Balancing virtual appliance.

   

   These credentials must be the account you created during Workload Balancing configuration. By default, the user name for this account is wlbuser.

5. In the Citrix Hypervisor Credentials section, enter the user name and password for the pool you are configuring. Workload Balancing uses these credentials to connect to the hosts in the pool.

   

   To use the credentials with which you are currently logged into XenServer, select Use the current XenCenter credentials. If you have assigned a role to this account using the Access Control feature (RBAC), ensure that the role has sufficient permissions to configure Workload Balancing. For more information, see Workload Balancing Access Control Permissions.

After connecting the pool to the Workload Balancing virtual appliance, Workload Balancing automatically begins monitoring the pool with the default optimization settings. To modify these settings or change the priority given to specific resources, wait at least 60 seconds before proceeding. Or wait until the XenCenter Log shows that discovery is finished.

Important:

After Workload Balancing runs for a time, if you don’t receive optimal placement recommendations, evaluate your performance thresholds. This evaluation is described in Understand when Workload Balancing makes recommendations. It is critical to set Workload Balancing to the correct thresholds for your environment or its recommendations might not be appropriate.

Migrate data from an existing virtual appliance

If you are using the Workload Balancing virtual appliance provided with XenServer, you can use the migrate script to migrate your existing data when you upgrade to the latest version (Workload Balancing 8.2.1 or later).

The version of Workload Balancing currently provided with XenServer is 8.3.0. However, Workload Balancing 8.2.0, 8.2.1, and 8.2.2 were previously available with earlier versions of Citrix Hypervisor. You can also use this migration script to migrate from Workload Balancing 8.2.1 or 8.2.2 to Workload Balancing 8.3.0.

To use the migrate script, you must have the following information:

• The root password of the existing Workload Balancing virtual appliance for remote SSH access
• The password of the data base user postgres on the existing Workload Balancing virtual appliance
• The password of the data base user postgres on the new Workload Balancing virtual appliance

Leave the existing Workload Balancing virtual appliance running on your pool while you complete the migration steps.

1. Follow the steps in the preceding section to import the new Workload Balancing virtual appliance.

2. In the SSH console of the new Workload Balancing virtual appliance, run one of the following commands.

   • For the Workload Balancing 8.2.1 virtual appliance, run:

      /opt/vpx/wlb/migrate_db.sh 8.2.1 <IP of existing Workload Balancing appliance>
     

   • For the Workload Balancing 8.2.2 virtual appliance, run:

      /opt/vpx/wlb/migrate_db.sh 8.2.2 <IP of existing Workload Balancing appliance>
     

   The command prompts you for password information when required.

3. Connect the XenServer pool with the new Workload Balancing virtual appliance.
4. After you are satisfied with the behavior of this version of the Workload Balancing virtual appliance, you can archive the old version of the virtual appliance.

Notes:

• In the case of a non-recoverable failure, reimport the latest version of the Workload Balancing virtual appliance.
• Do not disconnect the existing Workload Balancing virtual appliance. Otherwise, the data on the existing virtual appliance is removed.
• Keep the existing Workload Balancing virtual appliance until you have ensured that the new Workload Balancing virtual appliance is working as required.
• If necessary, you can roll back this migration by reconnecting the old version of the Workload Balancing virtual appliance to the XenServer pool.