Skip to main content

Nutanix AHV

Overview

Frame's integration with Nutanix AHV allows customers to seamlessly connect their AHV clusters to the Frame Platform, enabling them to run virtual desktops and applications directly within their on-premises infrastructure. By registering their AHV cluster with their Frame tenant, customers gain the flexibility to manage workloads locally while leveraging Frame’s remote desktop delivery and orchestration capabilities. This hybrid model empowers organizations to maintain full control over their virtual environment while offering end-users a high-performance experience across any device.

Setup

Requirements

In order to register your AHV cluster with Frame, you need to ensure that you have addressed the following before proceeding:

  1. The Nutanix hyperconverged cluster must have:

    • Acropolis Operating System (AOS) 7.0.0.5 (minimum) or newer
    • Acropolis Hypervisor (AHV) compatible with the cluster hardware and AOS version
    • Prism Central 2024.3 or newer, with your Prism Central VM configured with at least 26 GB of RAM

    For further details on the supported combinations of AOS, AHV, and Prism Central for a given Ubuntu or Windows guest OS, consult with Nutanix's AOS Software Interoperability Matrix and AHV Guest OS Compatability and Interoperability Matrix.

    note

    Frame, unlike other Nutanix services hosted on a Prism Central-managed cluster, does not require any additional compute resources for Prism Central. Frame uses:

    • Prism Central APIs to query categories, obtain the list of template images tagged with Frame-specific categories, and query for the list of available VLANs in the AHV cluster.
    • Prism Element APIs to manage AHV cluster-based resources (e.g., provision/deprovision VMs/storage, power on/off VMs, attach/detach disks, replicate backups, etc.)

    For sizing the Prism Central VM, consider your specific number of virtual machines across your AHV cluster(s). Refer to the Nutanix KB article as a reference for right sizing your Prism Central VM.

  1. If vGPUs are to be used, then the following NVIDIA components must be installed, as documented in the Nutanix AHV Administration Guide:

    • NVIDIA vGPU Software License Server with a valid NVIDIA license file
    • NVIDIA GRID vGPU Host drivers
    • NVIDIA GRID vGPU Guest OS drivers

    AHV-compatible host drivers are available for download from Nutanix Portal. All other NVIDIA components are obtained via NVIDIA Licensing Software Downloads site.

  2. Network has been configured for the AHV cluster to communicate with the Frame control plane and for users to access the workload VMs on the AHV cluster following one of two network deployment models, as described in Private Networking or Private Networking with SGA.

  3. DHCP must be available for the Frame workload VMs.

  4. At least one template OS image installed with Frame Agent.

Supported NVIDIA GPUs

A list of supported NVIDIA GPUs can be found in official Nutanix AHV documentation.

note

Depending on the specific HCI hardware model and the Nutanix AHV/AOS version to be used, the hardware and/or AHV version may or may not support all of the GPU cards above.

Preparation

Adding your AHV cluster to your Frame customer or organization entity in order for you to create Frame account(s) on your AHV cluster requires the following 3 tasks:

  1. Preparing your Nutanix AHV cluster
  2. Preparing at least one template image
  3. Connecting your AHV cluster to Frame

This section discusses the two preparation tasks that are required before you can connect your AHV cluster to Frame.

Cloud Connector Appliance 4

This document details how to setup and configure your Nutanix AHV environment with Frame's Cloud Connector Appliance 4 (CCA4) Early Access

CCA 4 offers improved integration with Nutanix and simplifies the configuration process. While documentation for CCA 3 is still available, we recommend customers begin migrating to CCA 4 as it provides enhanced functionality and will receive ongoing support and updates.

Nutanix Cluster

You will start by creating one (1) Prism Element user account, one (1) Prism Central user account, and one (1) Prism Central categories to be used by Frame for provisioning and infrastructure management.

  1. Save your Prism Element user name and password. You will need this Prism Element user name and password later on in the process.

Prism Central service user

  1. Log in to your Prism Central Management Console and go to your Prism Central settings by clicking on the "Admin Center" drop down menu in the top left corner of the management console.

    Prism Central - Settings

    Prism Central - Admin Center
  2. Click on “IAM” from the menu on the left-hand side and then "Identities". Click the "+ Add Local User” button.

    Prism Central - Local User Management

    Prism Central - Local User Management
  3. Fill out the "Add Local User” form that appears and click on the "Create" button.

    Prism Central - Add Local User

    Prism Central - Add Local User
  4. Save your Prism Central user name and password. You will need this Prism Central user name and password later on in the process.

  5. Next, create a new Authorization Policy for this service user by navigating from "IAM" to "Authorization Policies". Click on the "+ Create new Authorization Policy" button.

    a. In the Choose Role step, enter "Super Admin" for the role to add to this policy.

    Prism Central - Add Super Admin

    Prism Central - Add Super Admin

    b. In the Define Scope step, select "Full Access" and "Future Access".

    Prism Central - Enable User Roles

    Prism Central - Enable User Roles

    c. In the Assign Users step, add the local user you created in Step 7.

    Prism Central - Enable User Roles

    Prism Central - Enable User Roles

    d. Click "Save" to save the authorization policy configuration.

Prism Central Category

  1. Click on the hamburger menu icon in the upper left portion of your Prism Central interface.

  2. Expand the "Administration" menu item and select "Categories."

  3. Click on the "New Category" button.

    Prism Central - Categories

    Prism Central - Categories
  4. Fill in the form with the following values:

    Prism Central - Create Category

    Prism Central - Create Category
  • Name: FrameRole
  • Purpose: Categorizes VMs as Frame managed workload VMs
  • Values:MasterTemplate - Add this value.
  1. Click "Save" to save your Category defintion.

Template Image

Frame supports the use of Windows client/server operating systems and Ubuntu on Nutanix AHV. To bring a specific template OS image to Frame, refer to our BYO Image documentation for details on how to prepare one or more template OS images for Frame.

Connecting your AHV Cluster to Frame

Once you have satisfied the prerequisites, you are ready to register your AHV cluster on Frame. This section provides a step-by-step guide for how to create a CCA VM in Prism Central, as a first step of the AHV cluster registration process.

CCA ISO Download

You must first download the Frame Cloud Connector Appliance (CCA) ISO from our Downloads page and upload it to your Prism Image Library. You will use this CCA ISO to create a CCA VM in Prism Central.

Create a CCA VM

  1. First, in your Prism Central console, navigate to your VMs page and select "Create VM."

    Prism Central - Create VM

    Prism Central - Create VM
  2. Create a new VM for the Frame Cloud Connector Appliance (CCA) in a VLAN that meets the network requirements, as described in Private Networking or Private Networking with SGA.

    Prism Central - Specify VM Configuration

    Prism Central - Specify VM Configuration
    note

    For use cases with up to 500 concurrent users, Frame recommends configuring your CCA with 1 vCPU, 2 cores, and 4 GB RAM. For additional concurrent users, add additional CCA VMs after you have registered your AHV cluster.

  3. Click "+ Add New Disk" in the upper right corner of the window.

    Prism Central - Add Disk

    Prism Central - Add Disk
  4. Under the Operation drop down menu, select "Clone from Image" and then select the CCA4 qcow2 disk. Finally, click "Update"

    Prism Central - Clone from Image

    Prism Central - Clone from Image
  5. The Boot Configuration should be set to "Legacy BIOS" (default).

    Prism Central - Legacy BIOS

    Prism Central - Legacy BIOS
  6. Next, select "+ Add New NIC."

    Prism Central - Add New NIC

    Prism Central - Add New NIC
  7. Select your network for the CCA VM, then click “Add.” In this example, we're using vm_network_ipam VLAN as the network. Your network configuration may be different.

    Prism Central - Create NIC

    Prism Central - Create NIC
  8. Next, check the “Custom Script” check box and click on the “Type or Paste Script option.” Enter #cloud-config as shown below. Click “Save” and close the VM.

    Prism Central - Add Custom Script

    Prism Central - Add Custom Script
    EU Control Plane

    If you are configuring your CCA for Dizzion's EU control plane, paste the following script into the “Type or Paste Script” field:

    #cloud-config

    runcmd:
    - set_cca_env CCA_BACKPLANE_URL https://hub.deu.difr.com

  9. Save the VM with the preferences specified and power it on. By default, the CCA will try to acquire an IP address from a DHCP server. To set a static IP, follow the CCA Static IP Address instructions.

  10. Once the VM is powered on, continue with the step-by-step procedure for Configuring Your CCA VM for a new AHV Cloud Account or Adding a CCA to an Existing AHV Cloud Account.

Configuring your CCA VM

Generate Registration Key

  1. Log in to you Frame Account, navigate to “Cloud Accounts” either under Customer or Organization Level, and select “Add Cloud Account”

    Frame - Add Cloud Account

  2. A new page will appear, select "Nutanix-AHV".

    Frame - Add Cloud Account

  3. Enter a name for the new CCA 4 Cluster and click "Create."

  4. Select "Show Nodes" to expand the cluster overview.

    Add a Node

  5. Click on "Add a Node" to create a new registration key for your CCA VM.

    Add a Node

Register CCA Nodes

  1. Once the registration key has been generated and the previously created CCA is running, navigate to your CCA VM's IP address (https://<YOUR-CCA-VM-IP-address>/) in your browser to connect to the CCA wizard.

  2. To log in to the CCA wizard, use the Prism Central user credentials that you created earlier for Frame and specify the Prism Central URL.

    Cloud Connector Appliance - User Authentication

  3. CCA can communicate via an HTTPS proxy server to the Frame control plane. If a proxy server is not required, just click "Continue". Otherwise, enable the “Use proxy” slider.

    Cloud Connector Appliance - Proxy Server Option

  4. Specify the proxy server URL which the CCA will use to reach the proxy server. If the proxy server requires a service username and password, specify the service username and password required for the CCA to authenticate to the proxy server. Otherwise, leave the proxy username and password blank. Use the "Verify" button to validate your proxy server configuration.

    Cloud Connector Appliance - Proxy Server Configuration

  5. Copy and enter the activation key that was created in Step 3 under the Generate Registration Key section.

    Cloud Connector Appliance - Proxy Server Configuration

From there, wait until the registration of the new node is complete:

Cloud Connector Appliance - Proxy Server Configuration

Cloud Connector Appliance (CCA) 4 Setup

  1. To check the status of the current CCA setup, simply expand the Cluster overview. The status will be displayed under the "Status" column on the right-hand side.

    Cloud Connector Appliance - Configuration Status

  2. Under the status overview select "Regions." On the next screen, click “Add Region” to choose the AHV cluster which should be connected. Click "Sync” to get a list of all available AHV clusters that can be connected, select the desired one, and finally complete the process by clicking on "Add Regions".

    Cloud Connector Appliance - Add Regions

    Cloud Connector Appliance - Add Regions Complete

Import the Virtual Network

  1. Next, add the Virtual Network to be used for the Frame Accounts by clicking on the "Import Virtual Network" link in the top right corner of the page.

    Cloud Connector Appliance - Import Virtual Network

    1. Click on the "Sync" link next to the "Select Virtual Network" dropdown menu to get a list of all available networks on the target cluster. Cloud Connector Appliance - Import Virtual Network

    2. Select the one that needs to be imported.

    3. Enter a display name for the virtual network.

      Cloud Connector Appliance - Name Virtual Network

    4. Click "Import Virtual Network" at the bottom of the dialog.

Import the Image

  1. Next, switch to the Master Image category on the top row and select the "Import Image" link in the upper right corner.

    Cloud Connector Appliance - Import Image

    1. Click "Sync" to get a list of all available images that can be imported as a new Master Image.

      Cloud Connector Appliance - Sync Image

    2. Select the image you wish to use. Cloud Connector Appliance - Select Image

    3. Enter a display name for the Image.

    4. Click "Import" to complete the image setup process.
      Cloud Connector Appliance - Complete Image Import

Add Instance Types

  1. Next, navigate to the "Instance Types" tab. You can either create new instance types or edit existing ones. To add an instance type, click the blue "Add Instance Type" link in the upper right corner of the page. To edit an existing one, click the kebab menu within the row of the instance type you'd like to modify. For this example, we'll create a new instance type:

    Cloud Connector Appliance - Add Instance Type

    • Display Name: Name of the instance type that will appear to administrators and users within Frame Console and Launchpad, respectively.
    • GPU: If you have NVIDIA vGPUs configured in Prism, the list of vGPU profiles will be displayed. You may select a vGPU profile if you wish for the instance type to have a vGPU when VMs of this instance type are provisioned.
    • Cores: Number of cores for each vCPU.
    • CPUs: Number of vCPUs for this instance type.
    • Memory: The amount of RAM assigned to the instance type in GiB.

Add Storage Container

  1. Our next and final step is to add a storage capacity target for the use of enterprise profiles/personal drives. Select the “Storage Container” tab from the top row.

    1. Click “Add Storage Container” in the upper right corner. From there, click "Sync" to get a list of all available containers on the target cluster.

      Cloud Connector Appliance - Add Storage Container

    2. Select the storage container which should be used for profile/personal drives and click the "Add" button.

      Cloud Connector Appliance - Save Storage Container

CCA Static IP Address

By default, CCA VMs are assumed to obtain their IP address from a DHCP server provided by you. If a static IP address is required for the CCA, then the IP address of the VM will need to be manually configured.

  1. After the CCA has been provisioned, open the console of the CCA VM from Prism Central (or Prism Element) and login as difr user, password cca.

  2. Select option 1 from the screen:

    Prism Central - Network Configuration

    Prism Central - Network Configuration
  3. Chose the network interface to configure:

    Prism Central - Network Configuration

    Prism Central - Network Configuration
  4. Enter the following information for the CCA VM:

    Prism Central - Network Configuration

    Prism Central - Network Configuration
    • Address: Static IP address of the CCA VM. Make sure to append the correct /XX to the IP address.
    • Gateway: IP address of the gateway for the CCA VM.
    • DNS address: IP address(es) of the DNS server(s) which can resolve public DNS records, including the FQDNs for the Frame control plane.
  5. Make sure to save your settings.

Adding a CCA to an Existing AHV Cloud Account

This section describes the workflow if you have an existing AHV Cloud Account and would like to perform any of the following operations:

  • Setup a highly available CCA configuration
  • Update the version of a CCA VM
  • Changed the AHV cluster's IP address and need to create a new CCA VM
  • Enable Enterprise Profiles, Personal Drives, or proxy server for an existing AHV Cloud Account
  • Modify settings for Enterprise Profiles, Personal Drives, or an existing proxy server configuration

First, create a new CCA VM following the instructions in the Create a CCA VM procedure.

Once your new CCA VM is powered on and you have logged in to your new CCA VM using your Prism Central user credentials, as described in Configuring your CCA VM, Steps 5-6, you can use the following workflow to update your proxy server settings (Steps 1 and 2 below) or make additional configuation changes (Steps 3 through 7).

  1. If you want to update the CCA configuration for your existing AHV Cloud Account to use a proxy server, then click on the slider to "Use Proxy."

    Cloud Connector Appliance - Proxy Server Option

    Cloud Connector Appliance - Proxy Server Option
  2. Specify the proxy server URL which the CCA will use to reach the proxy server. If the proxy server requires a service username and password, specify the service username and password required for the CCA to authenticate to the proxy server. Otherwise, leave the proxy username and password blank. Use the "Verify" button to validate a valid proxy server configuration.

    Cloud Connector Appliance - Proxy Server Configuration

    Cloud Connector Appliance - Proxy Server Configuration
  3. Since you are adding a CCA instance to an existing AHV cloud account, choose the Attach Appliance to Frame option.

    Cloud Connector Appliance - New or Existing AHV Cloud Account

    Cloud Connector Appliance - New or Existing AHV Cloud Account
  4. Confirm the AHV cluster and specify its Prism Element credentials. At this step, you can update the Enterprise Profiles and Personal Drives settings as well for the existing AHV Cloud Account.

    Cloud Connector Appliance - Enterprise Profiles and Personal Drives

    Cloud Connector Appliance - Enterprise Profiles and Personal Drives
  5. Select the Customer or Organization entity you created earlier in the Frame account setup. Choose the AHV Cloud Account for which high availability configuration is required and Click "Attach."

    Cloud Connector Appliance - Customer or Organization

    Cloud Connector Appliance - Customer or Organization
  6. The wizard should inform you that your CCA VM has successfully connected to Frame control plane.

    Cloud Connector Appliance - Registered

    Cloud Connector Appliance - Registered
  7. Once you have attached the new version of the CCA to the AHV cloud account, you can power off the CCA VM running the older version of CCA and terminate the VM. You can perform the above steps again to add additional CCA VMs of the new version for high availability and scalability.

Troubleshooting

If you experience issues with CCA 4, administrators can troubleshoot by reviewing logs or accessing network configuration through AHV’s VNC console.

If the CCA web interface does not display the Prism Central URL field, verify the following:

  • Ensure that the CCA VM was deployed using the latest CCA 4 image.
  • Confirm that the VM is properly connected to the network and can communicate with Prism Central.
  • Check that no additional "volume groups" are attached to the VM.

The CCA 4 Dashboard provides real-time visibility into the connection status between CCA and Frame, as well as CCA and Prism Central. It also displays the latest API requests and a summary of Prism Central activity since the CCA VM was last powered on. To access the Dashboard, open a browser and navigate to:

https://<CCA VM IP address>/

Log in using your Prism Central service account credentials.