Get started with Workload Balancing

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

  1. Download the Workload Balancing virtual appliance from http://www.citrix.com/downloads

  2. Import the virtual appliance into XenCenter.

  3. Configure Workload Balancing Appliance from the virtual appliance console.

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

    The Workload Balancing tab only appears in XenCenter if you have the required license to use Workload Balancing.

To balance a pool with Workload Balancing, the pool’s hosts must meet the requirements for live migration as described in Administer.

Import the Workload Balancing virtual appliance

The Workload Balancing virtual appliance is a single pre-installed virtual machine designed to run on a Citrix Hypervisor server. Before importing it, review the prerequisite information and considerations.

Prerequisites

The Workload Balancing virtual appliance is designed to run on Citrix Hypervisor 7.1 or later.

The virtual appliance provided with Citrix Hypervisor 8.2 or later can run on XenServer 7.1 CU2 and Citrix Hypervisor 8.x. However, to use all features of the virtual appliance on your XenServer 7.1 CU2 servers, you must install Hotfix XS71ECU2040.

We recommend using the XenCenter management console to import the 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 does not need to be increased in most cases, as it is sufficient for pools hosting 1000 VMs. Only decrease the number of vCPUs assigned to the virtual appliance if you have a very small environment.

If you are currently using a Workload Balancing virtual appliance provided with XenServer 7.1 CU2, Citrix Hypervisor 8.0, or Citrix Hypervisor 8.1 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.

Information to consider before importing the virtual appliance

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).

  • Account for Workload Balancing. The Workload Balancing Configuration wizard requires that you select and enter a user name and password for the Workload Balancing account and the database account. You do not need to create these accounts before running the Configuration wizard. The Configuration wizard creates these accounts for you.

  • 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.)

    Note:

    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.

  • Citrix Hypervisor 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 Citrix Hypervisor to verify the certificate or both. For information, see the Workload Balancing Administrator’s Guide.

  • 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.

    If you want to store much historical data, you can do one of the following:

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

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

    To increase the disk size, import the virtual appliance and then increase the virtual disk size by following the procedures in the Workload Balancing Administrator’s Guide.

  • 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.

Download the virtual appliance

The Workload Balancing virtual appliance is packaged in an .xva format. You can download the virtual appliance from the Citrix download page http://www.citrix.com/downloads. 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.

Import the virtual appliance into XenCenter

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

To import the virtual appliance into Citrix Hypervisor:

  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 virtual machine appears in the Resource pane in XenCenter.

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 virtual machine. Citrix recommends selecting a strong password.

    Note:

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

  4. Enter the computer name you want to assign to the Workload Balancing virtual appliance.
  5. Enter the domain suffix for the virtual appliance.

    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 virtual machine. Otherwise, enter n and then enter a static IP address, subnet mask, and gateway for the virtual machine.

    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.

    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 Citrix Hypervisor 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. The Workload Balancing log file is in this location: /var/log/wlb/LogFile.log. More information about these files and their purpose is in the Workload Balancing Administrator’s Guide.

Connect to the Workload Balancing virtual appliance

Note:

Workload Balancing is available for Citrix Hypervisor Premium Edition customers or those customers who have access to Citrix Hypervisor through their Citrix Virtual Apps and Desktops entitlement. For more information about Citrix Hypervisor licensing, see Licensing. To upgrade, or to buy a Citrix Hypervisor license, visit the Citrix website.

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

To complete the XenCenter procedure that follows, you need the:

  • IP address or FQDN of the Workload Balancing virtual appliance and its port number

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

  • Credentials for the Workload Balancing account you created during Workload Balancing configuration. Citrix Hypervisor uses this account to communicate with Workload Balancing.

This illustration shows: (1) How Citrix Hypervisor communicates with Workload Balancing using an account you created during the Workload Balancing configuration. (2) How the Workload Balancing virtual appliance authenticates to Citrix Hypervisor using the credentials for the pool.

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.

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.

Connect to Workload Balancing and 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 Citrix Hypervisor 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.

More information about configuring certificates is provided in the Workload Balancing Administrator’s Guide.

To connect your pool to the Workload Balancing virtual appliance

Note:

Workload Balancing is available for Citrix Hypervisor Premium Edition customers or those customers who have access to Citrix Hypervisor through their Citrix Virtual Apps and Desktops entitlement. To upgrade, or to buy a Citrix Hypervisor license, visit the Citrix website.

  1. In the Infrastructure pane of XenCenter, select XenCenter > your-resource-pool.

  2. In the Properties pane, click the WLB tab.

    The WLB tab displays the Connect button.

    Screenshot of the WLB tab in XenCenter

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

    Screenshot of the Connect to the WLB Server wizard

  4. 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, your WLB-appliance-computername.yourdomain.net.

      Tip:

      For more information, see To obtain the IP address for the WLB virtual appliance.

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

      By default, Citrix Hypervisor connects to Workload Balancing on port 8012.

      Note:

      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.

  5. In the WLB Server Credentials section, enter the user name and password the Citrix Hypervisor pool (master) uses to connect to the Workload Balancing virtual appliance.

    Screenshot of the Update Credentials dialog

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

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

    Screenshot of the Credentials dialog

    To use the credentials with which you are currently logged into Citrix Hypervisor, select the Use the current XenCenter credentials check box. If you have assigned a role to this account by using the RBAC feature, ensure that the role has sufficient permissions to configure Workload Balancing. For more information, see the RBAC section of the Workload Balancing Administrator’s Guide.

  7. 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 is running for a time, if you do not receive optimal recommendations, evaluate your performance thresholds as described in Administer. It is critical to set Workload Balancing to the correct thresholds for your environment or its recommendations might not be appropriate.

To obtain the IP address for the WLB virtual appliance

  1. Select the Workload Balancing virtual appliance in the Resource pane in XenCenter, and select the Console tab.

  2. Log in to the appliance. Enter the VM user name (typically “root”) and the root password you created when you imported the appliance.

  3. Enter the following command at the prompt:

    ifconfig
    

Migrate data from an existing virtual appliance

If you are using the Workload Balancing virtual appliance provided with XenServer 7.1 CU2, Citrix Hypervisor 8.0, or Citrix Hypervisor 8.1, 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 Citrix Hypervisor 8.2 is 8.2.1. However, initially Workload Balancing 8.2.0 was available with Citrix Hypervisor 8.2. You can also use this migration script to migrate from Workload Balancing 8.2.0 to 8.2.1.

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 virtual appliance provided with XenServer 7.1 CU2, run:

       /opt/vpx/wlb/migrate_db.sh 7.1.2 <IP of existing WLB appliance>
      
    • For the Workload Balancing virtual appliance provided with Citrix Hypervisor 8.0 or Citrix Hypervisor 8.1, run:

       /opt/vpx/wlb/migrate_db.sh 8.0.0 <IP of existing WLB appliance>
      
    • For the Workload Balancing virtual appliance initially provided with Citrix Hypervisor 8.2 (Workload Balancing 8.2.0), run:

       /opt/vpx/wlb/migrate_db.sh 8.2.0 <IP of existing WLB appliance>
      

    The command prompts you for password information when required.

  3. Connect the Citrix Hypervisor 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:

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

Get started with Workload Balancing